• Initializing Aladin Lite
• Managing the view
• Image layers
• Catalogue layers
• Overlay layers
• Managing layers
• Listeners
• Misc
• API examples

Aladin Lite creation

A.aladin(<container-div-selector>, <options>?)

Creating an Aladin Lite instance is quite easy: after having inserted the embedding code in your page, just call var aladin = A.aladin('#aladin-lite-div');. The variable aladin is a reference to the Aladin lite instance.

Note that Aladin Lite view will automatically adapt if the container div is resized, as shown in this example.

Initialization options

The method takes an optional second argument which gives the initialization options as a key-value object. Possible options are:

Key name	Description	Default value
target	Initial target, as a position or an object name resolved by Sesame	0 +0
cooFrame	Coordinate system: "ICRS", "ICRSd" or "galactic". "ICRS" will display coordinates in sexagesimal format whereas "ICRSd" will output decimal format.	"ICRS"
survey	Identifier of the initial image survey. See this section for more details.	"P/DSS2/color"
fov	Initial value of the visible field of view, in decimal degrees	60
showReticle	If true, the reticle will be displayed	true
showZoomControl	If true, the zoom control GUI is displayed (plus/minus buttons)	true
showFullscreenControl	If true, the button to pass in full screen mode (at the top right of the interface) is displayed	true
showLayersControl	If true, the icon to open the layers controls is displayed	true
showGotoControl	If true, the icon to easily jump to a new position/object is displayed	true
showShareControl	If true, the icon to get a link to the current view is displayed	false
showSimbadPointerControl	If true, add the Simbad pointer tool to the toolbar	false
showFrame	If true, coordinate are displayed (at the top left of the interface)	true
fullScreen	If true, Aladin Lite starts in "full screen" mode	false
reticleColor	Color of the reticle	"rgb(178, 50, 178)"
reticleSize	Size in pixels of the reticle	22

Example of Aladin Lite initialization with custom options

Customizing location of GUI elements

If you want to customize the location of the GUI elements (full screen icon, zoom controller, goto controller, layers controller), the easiest way is to override the CSS properties of the corresponding class (respectively .aladin-fullscreen, .aladin-zoomControl, .aladin-gotoControl, .aladin-layersControl).

Getting information about the view

aladin.getRaDec() returns a [ra, dec] with the current equatorial coordinates of the Aladin Lite view center.

aladin.getSize() will return an array with the current dimension (width, height) of Aladin Lite view in pixels.

aladin.getFov() returns an array with the current dimension on the sky (size in X, size in Y) of the view in decimal degrees.

aladin.getFovCorners(<nbSteps?>) returns an array of [ra, dec] points along the current rectangular view. By default, the position of the 4 corners are returned. You can get more control points passing an optional nbSteps parameter. The returned format is: [[ra1, dec1], [ra2, dec2], ..., [ra_n, dec_n]] with n equals to 4*nbSteps.

Updating view properties

• Use aladin.setFov(<FoV-in-degrees>) to change the FoV size.

• aladin.adjustFovForObject(<object-name>) will try to adjust the field of view according to the properties of the object name given as parameter. This works only for object known by Simbad ; it is based on the object dimension and magnitude.

Method aladin.setFovRange(<min-fov-in-degrees>, <max-fov-in-degrees>) allows to restrict the field of view range.

Example: aladin.setFovRange(0.3, 30) will ensure the displayed field of view is always smaller than 0.3 degree and larger than 30 degrees. Setting the current position of the center of the view

There are several methods to update the current position:

• aladin.gotoRaDec(<ra-in-degrees>, <dec-in-degrees>)
• aladin.gotoObject(<object-name-or-position>, <callback-options>?) . This method can understand both a position or an object name. Object names will be resolved by Sesame.
  You can pass optional success or error callback functions that will be called resp. when the target name is successfulyl resolved or when an error happened. Example:
  aladin.gotoObject('Messier 1', {success: function(raDec) { alert(raDec);}, error: function() {...}})

Displaying a custom HiPS image layer

To display a custom HiPS (previously generated by Hipsgen for instance, use the following method:
aladin.setImageSurvey(aladin.createImageSurvey(<HiPS-ID>, <HiPS-name>, <HiPS-base-URL>, <HiPS frame ('equatorial' or 'galactic', usually 'equatorial')>, <HiPS max order>, {imgFormat: <tiles format ('jpg' or 'png')>})); The URL you give can be private or even on localhost.

You can see a working example here of displaying a custom HiPS

Retrieving the base image layer

Calling aladin.getBaseImageLayer() will return an ImageLayer object corresponding to the base image layer.

Updating the color map

Call getColorMap() on an ImageLayer object to retrieve its color map.
Once retrieved, call update(<color-map-name>) to set a new color map. Recognized values are:

• cubehelix
• eosb
• rainbow
• grayscale
• native to go back to the original image color map

Example: setting a cubehelix color map

Visualizing a FITS image

While Aladin Lite currently does not support natively, small FITS images can be visualized by converting them server-side to HiPS under the hood using the displayFITS(<FITS-URL>) method.
Example: displayFITS('http://data.astropy.org/tutorials/FITS-images/HorseHead.fits')

The input parameter can also be given as a base64 data URL.

Displaying a HiPS catalogue layer

To display a HiPS catalogue (previously generated by Hipsgen-cat for instance, use the following method:
aladin.addCatalog(A.catalogHiPS(<HiPS-base-URL>, <options?>))

You can see a working example here of displaying a HiPS dedicated to SIMBAD objects.

The option map can take a filter parameter whose expected value is a function. This filter function is being passed a Source object and must return true if the source must be shown, false otherwise. The following example allows one to filter Gaia sources (loaded from the catalogue HiPS) according to the value of their proper motion.

Creating a new catalogue layer

Catalogue layers are meant to hold list of astronomical sources. They are created using A.catalog(<options>?) and added to Aladin Lite with aladin.addCatalog(catalogInstance)

Possible options are:

Updating a catalogue

Adding some sources to the catalogue

Sources can be created manually using A.source(ra, dec, data) and added to an existing catalog layer using the addSources(...) method which takes either an array of Source instances or a single instance of Source.

Example: Creating catalogue sources with a custom shape

Removing individual sources

Individual sources can be removed from a catalogue instance with the remove(sourceReference), as demonstrated in this example.

Changing the symbol associated to sources

Calling updateShape({color: <new-color>, shape: <new-shape>, sourceSize: <new-size>}) on a catalogue layer will modify the symbol associated to the sources in the catalogue.

Example: cat.updateShape({color: '#86d', shape: 'cross'}) will update the color and shape attributes while keeping the sourceSize untouched.

Loading a VOTable

Catalogue layers can also be created from a VOTable URL: calling A.catalogFromURL(<votable-URL>, <options>?, <successCallback>?, <useProxy>?) will return a Catalog object which can then be added to the Aladin Lite instance.

The compulsory parameter is the URL of the VOTable we want to load. Other parameters are optional:

• options: display options for the catalog. See above for an exhaustive list of understood keys.
• succesCallback: function called when the parsing of the VOTable has been done. The callback function will be called with as a parameter the array of parsed Sources.
• useProxy: true or false (default value: true). By default, Aladin Lite uses an HTTP proxy to retrieve remote resources, in order to allow for cross-domain calls. If the server providing the VOTable supports CORS or if you request a VOTable from the same domain than your Javascript code, you can set this parameter to false in order to make a direct query.

Examples:
Loading a VOTable from VizieR
Using labels to display object names

Easy access to SIMBAD, VizieR, NED and SkyBot data

We provide with helper functions to easily load SIMBAD, NED or VizieR data for a given region of the sky:

• A.catalogFromSimbad(<target>, <radius-in-degrees>, <catalog-options>?, <successCallback>?) will return a Catalog instance with Simbad data of the requested region around the target. Target can be an object name, a position or an object {ra: <ra-value>, dec: <dec-value>}.
• A.catalogFromVizieR(<vizier-cat-id>, <target>, <radius-in-deg>, <cat-options>?, <successCallback>?) will return a Catalog instance with data of the requested VizieR catalogue.
• A.catalogFromNED(<target>, <radius-in-degrees>, <catalog-options>?, <successCallback>?) will return a Catalog instance with NED data of the requested region.
• A.catalogFromSkyBot(<ra>, <dec>, <radius>, <epoch>, <query-options>?, <cat-options>?, <successCallback>?) will query the SkyBot service for solar system objects and return a Catalog instance for the requested cone (right ascension, declination, radius in degrees) and epoch. Additional optional query options can be specified as a keyword/value dictionary, eg: {"-loc": 500, "-filter": 0}

Examples:
Visualizing SIMBAD and NED data around M 82
Visualizing Hipparcos data in the Pleiades

Creating a marker

A marker displays a position on the sky. Clicking on a marker will open a popup with a title and text set upon creation.

Use A.marker(ra, dec, {popupTitle: <title of the popup>, popupDesc: <text (possibly HTML) for the popup>}) to create a new marker. You can then add it to an existing Catalog.

Example: Creating multiple markers

var aladin = A.aladin('#aladin-lite-div');

var overlay = A.graphicOverlay({color: 'cyan'});
aladin.addOverlay(overlay);

Pixel coordinates to world coordinates

pix2world(<x>, <y>) transforms pixel coordinates to world coordinates, origin (0,0) of pixel coordinates being at top left corner of Aladin Lite view. It returns a [ra, dec] array with world coordinates in degrees.

World coordinates to pixel coordinates

world2pix(<ra>, <dec>) transforms world coordinates to pixel coordinates in the view. It returns a [x, y] array with corresponding pixel coordinates in the Aladin Lite view. It returns null if the projection failed somehow.

Retrieve current view as a PNG

Calling getViewDataURL() on the aladin instance will return the current view as a base64-encoded string. This method takes an optional parameter to specify the image format, either 'image/png' or 'image/jpeg'.

Get URL of the current view

Calling getShareURL() on the aladin instance will return a permanent link showing the current field of view for the current selected image HiPS.

Get embed code

Calling getEmbedCode() on the aladin instance will return the HTML code to be inserted in a web page, and corresponding to the current field of view (target and zoom level) and to the currently displayed HiPS.

Click here to access to the full list of examples illustrating Aladin Lite API.