Contents:

1. Introduction
2. Installation
3. Generate your VOTable
4. Use VOTable data in Aladin
5. Explore Aladin script capability
6. Use Aladin applet sites to display your own data
7. Interface Aladin with your own Java application

1. Introduction

During this tutorial you will learn to create a VOTable file and use it in a VO application, for instance Aladin.

You will...
...manipulate VOTable (usage of conVOT translator and/or SAVOT java library)
...use VOTable in Aladin (loading - saving - processing)
...interface Aladin in your context (Web server and/or application)

Time: 90mn
Tutors: Pierre Fernique and Thomas Boch [CDS]

2. Installation

1. Copy all materials required for VOTable/Aladin tutorial from the CD (or from this location URL: ftp://archive.eso.org/pub/vo-workshop/VOTable-Aladin/) into a dedicated directory on your machine, for example /Votal (\Votal for Windows).
2. As this tutorial require command lines, open a terminal console. For Windows user, you can open one by the menu "Start → Execute → cmd". For MacOS user, "Applications → Tools → Terminal". Set the current directory: "cd /Votal" (or cd \Votal for Windows).
3. Verify that the java binaries are executable by testing "java -version" command line (if it is not the case check your path or create an alias).

Notice that this tutorial requires a full java environment (java runtime+ java compiler + java enabled Web browser - for instance the J2SE Software Development Kit (SDK) - download it from http://java.sun.com/j2se/1.4.2/download.html). However a simple java runtime environment is enough to do a large part of this tutorial.

3. Generate your VOTable

Goal: Manipulate VOTable file either by program or by libraries.

[10mn]
Beginners) Generate a VOTable file from a TSV file (Tab-Separated-Values) via a step by step converter. Here you will use conVOT application from VO India.

1. You have a TSV file or a FITS table: (choose the example "m51.tsv" or your own data)
2. Launch conVOT application by this command: java -jar conVOT.jar
3. Follow the instruction of the application (warning: the m51.tsv file has a dash-line separating the header and data, do not forget to adjust the "First data Line No:" widget default value)
4. Save the result in a file with the name "votable.xml"

[10mn]
Advanced) Generate a VOTable file from a TSV file (Tab-Separated-Values) by program. Here you will use SAVOT java library from CDS).

1. Compile and execute the "TSV2VOTable" java program by following these instructions:
• Compilation:
  javac -classpath ".:savot.jar" TSV2VOTable.java
  (for Windows replace ":" by ";")
  If you have not a java compiler (javac) a pre-compiled version is provided (TSV2VOTable.class)
• Execution:
  java -classpath ".:savot.jar" TSV2VOTable m51.tsv
  (for Windows replace ":" by ";")
2. Compare the original TSV file (m51.tsv) and the resulting VOTable file (votable.xml).
3. For this purpose, use your prefered text editor.
4. Modify this program to handle UCDs (just uncomment the 4 dedicated commented lines, recompile it, and run it again, then compare the results).
5. Have a look at TSV2VOTable2.java code which show you how to use SAVOT in a streaming mode instead of loading all TSV data in memory before writing the result.

4. Use VOTable data in Aladin

Goal: Use VOTable in a VO tool. Here Aladin.

1. Launch Aladin by this following command: java -jar Aladin.jar
2. Load the VOTable file built in step A: menu Load → MyData → Browse → "votable.xml"
3. Select some objects to see the corresponding measurements: click on an object or enclose several of them by a "click-and-drag rectangle"
4. Visualise simultaneously your data with other VO resources. For instance load an image for the same field : menu Load → "one image server on the left side" → SUBMIT [→ "select an image" → SUBMIT] (your data cover a field of 20 arcmin, choose an image according to)

[10mn]
Advanced) Use UCDs from the VOTable for creating generic Aladin filters.

1. Load several tables from VizieR (for which there are already all UCDs): menu Load → Vizier Catalogs → in "Astronomy" list select "Photometry" → SUBMIT. Vizier will send you all "photometrical" catalogs having at least one object in the field.
2. In the VizieR resulting list, load two or three catalogs, each of them in a individual Aladin "plane". For that : click on one line + SUBMIT, repeat this sequence for other catalogs.
3. Look at the result in the main Aladin window. You can switch on/off individual catalog by clicking on their logo in the Aladin stack (below the Aladin "eye"). You can select all objects of a catalog by clicking on its name in the Aladin stack, and open the popup menu by pressing the right mouse button (or Apple key + mouse button for Mac) and select the menu item: "Select all objects of the selected planes".
4. Display only the brightest objects: ToolBar → filter → Beginner mode → "then tick the corresponding item".
5. See the corresponding filter command syntax: in the Aladin stack, select the created filter by clicking on its name + in the ToolBar → Prop. This filter command draws object catalogs for which the first column tagged with a UCD concerning "Photometry" (UCD1 : any UCD beginning with "PHOT_") has to have a value less than 12.
6. See other examples of predefined filters (button "Examples") and apply some of them. Notice that some filters use UCDs which may not be present in your catalog ⇒ no effect (load USNO for playing with proper motion filter, Simbad for playing with object ellipses and do not forget to click and drag the corresponding Aladin planes below the filter plane in the Aladin stack).

[10mn]
Home work for advanced) Cross-match your data with another table.

1. You need at least two catalog loaded. So if necessary, choose one survey from VizieR catalog surveys: menu Load → Surveys in VizieR → "select one survey" → SUBMIT, or at the opposite remove some catalog planes from your Aladin stack (select their names + ToolBar + del).
2. Launch the cross-match tool: menu Tools → Catalog crossmatch tool → "look for the available constraints" → Perfom cross-match
3. Hide the original data: in Aladin stack → click on each plane icon of the corresponding data.
4. Select some objets (click on them) and look at the corresponding measurements (distance + original data from first catalog + original data from second catalog).
5. Save the result in VOTable: menu Save → Export some planes → "Select Xmath result plane only" + simplify the filename + tick VOTABLE → EXPORT
6. See the result with your favorite text editor.

5. Explore Aladin script capability

Goal: Do your own programing with Aladin.

1. Open the script console: menu Aladin → Tools → Aladin script console
2. Look at the script commands corresponding to your Aladin session: by UP arrow or "hist" command
3. Try these commands: "grid on", "get Simbad", "get NED", "modeview 4", "get Aladin(DSS2)", "get NVSS"
4. Look at the list of available script commands: menu Help → Help on Aladin script commands → OK
5. Play with them.

[10mn]
Advanced) Create the script to do the VOTable xmatch processing of Sec. 4.

1. Try each command step by step.
2. Create a file with these commands (name it "Myscript.ajs").
3. Start Aladin by passing the Myscript.ajs file to the Aladin standard input:
   java -jar Aladin.jar < Myscript.ajs
   (The UCDs may be required in the data to help Aladin selecting the right positional columns.)

6. Use Aladin applet sites to display your own data

Goal: Use Aladin in a Web context.

Suppose you installed the result of the step A-advanced on your web server. Your users can download your data in VOTable. But you would like to offer to your users the visualisation of your data in Aladin applet.

For this exercice you can choose one of these following URLs providing VOTable results (replace by your own URL if you have one):

• IBVS datatable: 5488-t3
• asteroid position computed by IMCCE/France for M51 at 2453384.92154 Julian day

[5mn]
Beginners) Use the dedicated help form (http://aladin.u-strasbg.fr/java/nph-aladin.pl?frame=form) and test the resulting Aladin launching URL.

[5mn]
Very advanced) Create the corresponding launching script and create manually the URL following this syntax:
http://aladin.u-strasbg.fr/java/nph-aladin.pl?frame=launching∓-script=... (remember that your script has to be HTTP encoded).

7. (Home work for very advanced): Interface Aladin with your own Java application

Goal: Use Aladin in a Java collaborative context.

[15mn]

1. In your java application, instantiate Aladin by this way:
   import cds.tools.ExtApp;
   ExtApp aladin = cds.aladin.Aladin.launch();
2. Control Aladin by script commands through the ExtApp.execCommand(String script) method.
3. Look the Aladin FAQ about this point: http://aladin.u-strasbg.fr/java/FAQ.htx#ExtApp