Aladin/IDL interoperability

Thomas Boch, Laurent Cambrésy, Bernd Vollmer.

Goals

Some astronomers at CDS have expressed the need for an interface between Aladin and IDL (Interactive Data Language). This interface shall allow the user to launch Aladin from IDL, to exchange data between IDL and Aladin (and vice versa), etc.

We aim at studying how this goal can be fulfilled, in order to eventually provide an API allowing one to easily use Aladin as a tool within IDL scripts.

This document is also an evaluation of the IDL Java Bridge and which level of interaction can be achieved with it.

Technology used

Since version 6.0, IDL provides a technology called Java Bridge - relying on JNI - allowing to manipulate Java objects from IDL. We have chosen this technology, since it appeared to be the most straightforward and flexible way to interface Aladin with IDL.

NB : Only public methods can be accessed through Java Bridge

Prototype API

All our tests and developments have been done on a Linux machine, with IDL v. 6.2. Thus, setup instructions will refer to the Linux version of IDL.

Nevertheless, our examples should also work on Windows. Please refer to the IDL manual to see how to configure IDL Jave Bridge on Windows.

Needed configuration

In order to use this API, you need :

• IDL supporting Java Bridge, i.e IDL v. >= 6.0
• a JRE (Java Runtime Environment) >= 1.5.0 . We had troubles with (Swing or AWT) graphic objects when using a JRE 1.4.x. According to the IDL manual, this is due to a Java bug.

Important notice for Mac OS users : IDL documentation says that IDL on Mac pateforms is hard-coded to use the Java VM 1.3.1, ignoring any value set to IDLJAVAB_LIB_LOCATION. As Aladin v4 works only for JVM >= 1.4, it means that Mac users won't be able to use this API to control Aladin. We're still looking for a satisfactory solution.

Dependencies

Some functions of our API relie on the IDL Astronomy Library, which should be installed on the user machine.

Setting up IDL

NB : this installation procedure is also available in file idl_aladin_interface/README.txt, once the archive has been uncompressed.

Download idl_aladin_interface.tar.gz, and uncompress it - tar zxvf idl_aladin_interface.tar.gz -, for instance in $HOME/idl_modules/.
Download Aladin.jar (for instance in $HOME/jar/). You will need an Aladin version >=4.0
You need then to update the IDL path in order to easily find the new module. Edit the file pointed by the environment variable $IDL_STARTUP (usually $HOME/.idl_startup), and add the following line :

!path=expand_path('$HOME/idl_modules/idl_aladin_interface')+!path=

Before being able to use the API, you need to properly configure the IDL Java Bridge :

• create a new file $HOME/.idljavabrc with the following line :

  JVM Classpath = $CLASSPATH:$HOME/jar/Aladin.jar

  . This property will tell IDL where to find needed Java classes
• create an environment variable called IDLJAVAB_LIB_LOCATION and pointing the JVM shared library to be used. For instance, your .tcshrc file may have the following lines :

setenv JAVA_HOME /usr/java/jdk1.5.0_04
setenv IDLJAVAB_LIB_LOCATION $JAVA_HOME/jre/lib/i386/client

In order to check your setup, launch idl and type the following command : a = launch_aladin() . If Aladin is starting, your configuration is fine.

Increasing the JVM memory

You can set some JVM options in the $HOME/.idljavabrc . For instance, the 2 following lines will setup the initial memory allocation to 32MB, and the maximum memory allocation to 512MB :

JVM Option1 = -Xms32m
JVM Option2 = -Xmx512m

Other JVM options can also be added in the same manner.

API functions

• launch_aladin - This function launches a new instance of Aladin and returns a pointer to this instance, which will be needed later to communicate with Aladin.
  Typical usage : IDL > aladin = launch_aladin()

• load_table - Create a new catalogue plane in Aladin. Inputs are a set of up to 9 IDL vectors. First 2 vectors (v1 and v2) are supposed to be Right Ascension and Declination. These 2 columns are needed, so that Aladin is able to plot objects position on the sky.
  Typical usage : IDL> load_table, aladin, ra, dec, Umag, Bmag, Vmag, VECNAME=['RA','DEC',umag','bmag','vmag'], PLANENAME='my_table'

• load_image - Create a new Aladin image plane from a header and an image data array.
  Typical usage : IDL> load_image, aladin, im, hdr, PLANENAME='my_image'

• get_image - Retrieve FITS data array and header from an Aladin image plane.
  Typical usage : IDL> get_image, aladin, '2MASS', im, hdr

• get_table - Retrieve table values from an Aladin catalogue plane.
  Typical usage : IDL> get_table, aladin, ra, dec, jmag, hmag, kmag, PLANENAME='2MASS', COLNAMES=['RAJ2000', 'DEJ2000', 'Jmag', 'Hmag', 'Kmag']

• select_objects - Select in Aladin objects of a given table according to their row indexes.
  Typical usage : IDL> select_objects, aladin, 'GSC2.2', t

• send_script_command - Send a script command to Aladin.
  Typical Usage : IDL> send_script_command, aladin, 'modeview 9'

• add_ct - This function adds a color table to the list of Aladin color tables, and uses it for the current reference image. Inputs are the arrays (256 elements) for each component (RGB).
  Typical usage : IDL> ctname = add_ct(aladin, r, g, b, 'my_color_table')

• set_ct - Set the color table for the current reference image in Aladin.
  Typical usage : IDL> set_ct, aladin, 'my_color_table'

• set_reticle_pos - Set the position of the Aladin reticle. Inputs are RA and DEC in J2000
  Typical usage : IDL> set_reticle_pos, aladin, 24.32, -53.91

• get_reticle_pos - Retrieve the reticle position (J2000 equatorial coordinates)
  Typical isage : IDL> get_reticle_pos, aladin, ra, dec

• get_pixelval_at_reticle_pos - Retrieve the pixel value of the current reference image, at the position of the reticle
  Typical usage : =IDL> get_pixelval_at_reticle_pos, aladin, pixval

• stop_aladin - Quit Aladin and destroy the reference to the aladin object. Use this function to properly quit Aladin.
  Typical usage : IDL> stop_aladin, aladin

Each indivual .pro file in directory pro contains an exhaustive description and documentation about the corresponding IDL function.

Usage example

IDL> a = launch_aladin() ; launch Aladin and get back a refrence to this instance
IDL> im = readfits('IRAS100.fits', hdr) ; read image in IDL
IDL> load_image, a, im, hdr ; send image to Aladin
IDL> loadct, 27 ; change color table
IDL> tvlct, r, g, b, /get ; retrieve RGB components of the color table
IDL> ctname = add_ct(a, r, g, b, 'Eos B') ; add this color table to Aladin
IDL> send_script_command, a, 'get vizier(2MASS)' ; send a script command to load 2MASS data in Aladin
IDL> get_table, a, ra, dec, j, h, k, PLANENAME='2MASS', COLNAMES=['RAJ2000', 'DEJ2000', 'Jmag', 'Hmag', 'Kmag'] ; retrieve table loaded in Aladin in IDL vectors
IDL> select_objects, a, '2MASS', where(j gt 16 AND k lt 15) ; select sources corresponding to a constraint

Flash tutorial

A Flash tutorial (in french) is available here .
A Flash tutorial in english, demonstrating the new functions get_table and select_objects is available here.
A full tutorial in english is coming soon.

Example application

Conclusion and limitations

Although the initial configuration might seem a bit tricky and painful, IDL Jave Bridge provides a relatively easy mechanism to create, access and call Java objects and methods. Yet, all the actions have to be initiated from the IDL side. Thus, it is not possible trigger an action from the Java application (ie Aladin), there is no callback mechanism allowing to call a given IDL procedure from a Java class (what would have liked to be able to do is for instance calling an IDL procedure when the position of the reticles has changed). The only way to simulate this callback feature is to regularly ask (from IDL) for the reticle position and to detect when there is a change in the value, and then to call the suitable IDL procedure. Example : [Example TO BE ADDED]

Data are not shared between IDL and Aladin. When passing an array from IDL to Aladin, the IDL array has to be copied to a Java array, and this copy is relatively slow. Moreover, because of IDL loose typing, it is not always easy to know which Java type an IDL variable will be mapped to. Given these 2 arguments, we have sometimes given preference to writing data to a temporary file instead of directly passing data arrays.

Our API is limited to IDL 6.x, and won't work neither in previous IDL versions, nor in GDL. For users of those softwares, a solution to explore would be to use PLASTIC in XML-RPC mode (this would require a XML-RPC API for IDL/GDL) or in HTTP mode.

Finally, we have sometimes experienced some unattended, unexplained, non-easily-reproductible freezing.

Related work

Making different tools or applications work together is a often discussed topic in the VO world. The following pointers might be of interest for the reader :

• PLASTIC : PLASTIC is a protocol - developed in the VOTech frame - allowing to make desktop tools in a language-neutral way
• VOApp : VOApp is an attempt to produce a generic Java interface allowing Java VO applications to intercommunicate

Contact

If you have any question or problem related to this topic, please contact ThomasBoch

-- ThomasBoch - 23 Feb 2006