Aladin Lite v3 API reference

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 nameDescriptionDefault value
targetInitial target, as a position or an object name resolved by Sesame0 +0
cooFrameCoordinate system: "ICRS", "ICRSd" or "galactic".
"ICRS" will display coordinates in sexagesimal format whereas "ICRSd" will output decimal format.
"ICRS"
surveyIdentifier of the initial image survey. See this section for more details."P/DSS2/color"
fovInitial value of the visible field of view, in decimal degrees60
showReticleIf true, the reticle will be displayedtrue
showCooGridIf true, the coordinate grid will be displayedfalse
showCooGridControlIf true, the coordinate grid control GUI is displayedfalse
projectionSet the projection of the view. Possible values are SIN, AIT, MOL, ARC, TAN, among othersSIN
showProjectionControlIf true, the projection control GUI selector will be displayedtrue
showZoomControlIf true, the zoom control GUI is displayed (plus/minus buttons)true
showFullscreenControlIf true, the button to pass in full screen mode (at the top right of the interface) is displayedtrue
showLayersControlIf true, the icon to open the layers controls is displayedtrue
expandLayersControlIf true, the layers control GUI will be expandedfalse
showGotoControlIf true, the icon to easily jump to a new position/object is displayedtrue
showShareControlIf true, the icon to get a link to the current view is displayedfalse
showSimbadPointerControlIf true, add the Simbad pointer tool to the toolbarfalse
showContextMenuIf true, enable the context menu when right-clicking in the view. This context menu allows for easy access to the following actions: copy the clicked position, snapshot the view, add data, identify an object, access to HiPS2FITS cutout service, etc.false
showFrameIf true, coordinate are displayed (at the top left of the interface)true
fullScreenIf true, Aladin Lite starts in "full screen" modefalse
reticleColorColor of the reticle"rgb(178, 50, 178)"
reticleSizeSize in pixels of the reticle22

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

Setting the size of the FoV
  • 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.

Restricting the allowed field of view range

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() {...}})

Setting the view projection

You can change the projection of the aladin lite view to be, for example, an all-sky one.
For setting the view to the aitoff projection: aladin.setProjection("AIT"). Many projections have been implemented into aladin lite such as zenithal, pseudo-cylindrical, cylindrical and conics ones. The full list of available projections are the following:
  • Zenithal: SIN, TAN, STG, ZEA, FEYE, AIR, ARC, NCP
  • Pseudo-cylindrical: AIT, MOL, PAR, SFL
  • Cylindrical: MER, CAR, CEA, CYP
  • Conic: COD
  • Hybrid: HPX

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', 'png' or 'fits')>}));
The URL you give can be private or even on localhost.

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

The v3 enables an easier way to create a custom HiPS layer from an url, or even an HiPS ID.

aladin.newImageSurvey(<HiPS-base-URL>) or aladin.newImageSurvey(<HiPS-ID>) are both possible.

The call to createImageSurvey or newImageSurvey returns an HpxImageSurvey object. This object can be added to the aladin lite view, either as a base image layer:

  • aladin.setImageLayer(<HpxImageSurvey-object>)
  • aladin.setBaseImageLayer(<HpxImageSurvey-object>)
or as an overlay image layer by specifying an arbitrary, unique, layer name aladin.setOverlayImageLayer(<HpxImageSurvey-object>, <layer-name>)

Retrieving an image layer

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

More generally, you can retrieve a specific layer by calling aladin.getOverlayImageLayer(<layer-name>). Using that method with base as the layer name acts the same as calling aladin.getBaseImageLayer().

The HpxImageSurvey object

An HpxImageSurvey object offers several methods allowing you to personalize the rendering of an image survey. After getting your image survey let survey = aladin.getBaseImageLayer() you are able to call the following methods:

  • survey.setOpacity/setAlpha(<opacity-value>). This value must be given between 0.0 and 1.0. At the opposite, for retrieving the opacity level of the survey, call survey.getAlpha()
  • survey.setColormap(<colormap-name>, {stretch: <transfer function>, reversed: <reverse the colormap>}).
    • The list of available colormaps can be retrieved with: A.getAvailableListOfColormaps().
      Nonethenless, Here is the full list of it:
      blues, cividis, cubehelix, eosb, grayscale, inferno, magma, parula, plasma, rainbow, rdbu, rdyibu, redtemperature, spectral, summer, viridis, ylgnbu, ylorbr, native to go back to the original image color map
    • Optional accepted keywords are:
      • stretch with possible values among linear, pow2, asinh, log and sqrt
      • reversed, a boolean that if true indicates that the colormap is reversed

    Example: survey.setColormap('spectral', {stretch: 'asinh', reversed: true}) will use the spectral reversed colormap evaluated with a asinh stretch.
  • survey.setCuts(<low-cut>, <high-cut>) for changing the cutouts of the render
  • survey.readPixel(<x-in-px>, <y-in-px>) will return the pixel value corresponding to the xy screen coordinates given (in pixels).
  • survey.setImageFormat(<format>) to set the format of the survey. Accepted list of formats are: jpeg, png and fits. Some surveys will not have all those formats available, especially the fits format, but many of them actually have them. Retrieving fits tiles gives much better visual quality than traditionnal jpeg ones as fits values are usually coded on short (16 bits) or even float (32 bits) precision values. Relatively, jpeg or png tiles have pixel values coded on 8 bits, i.e. only 256 different values.
  • survey.setBlendingConfig(<additive-mode>) to set the blending options of the survey. additive-mode to true means the color of the survey pixels will be added to the surveys rendered previously. This allows the possibility to blend multiple surveys together, each associated to a specific color channel. At the opposite, additive-mode to false means the final screen color will be a linear combination of the survey color with the one rendered previously
Tonal color corrections methods are available:
  • survey.setGamma(<gamma-value>). Values accepted are between 0.1 and 10.
  • survey.setSaturation(<sat-value>). Values accepted are between -1 and 1, with -1 corresponding to a grayscale image and +1 with fully saturated.
  • survey.setContrast(<contrast-value>). Values accepted are between -1 and 1. Under specific circumstances, this may help to reduce image noises. Usually, tuning the constrast of an image also affects its brightness
  • survey.setBrightness(<brightness-value>). Accepted values are between -1 and 1

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:

Key nameDescription
nameThe label of the catalogue layer.
shapeThe shape used for each source in the catalog.
Possible values are: circle, plus, rhomb, cross, triangle and square (default value).
An HTMLCanvasElement or an Image object can also be passed (JPEG, PNG formats are supported, even SVG in most modern browsers).
colorThe color of the shape for each source.
sourceSizeThe size of the source in pixels.
raFieldID, name or index of the field to be used as Right Ascension. If not given, Aladin Lite will try to guess on the basis of UCDs.
decFieldID, name or index of the field to be used as declination. If not given, Aladin Lite will try to guess on the basis of UCDs.
labelColumnA label can be displayed next to the source shape. The value of labelColumn is the name of the column to be used for this purpose.
If this option is used, color and font of the label can be given with labelColor and labelFont.
labelColorColor of the label
labelFontFont of the label, eg 12px sans-serif
onClickDescribes the action to be executed when a source is clicked. By default, nothing happens. Available values are showTable (displays measurements associated to the clicked source in a table at the bottom of the GUI), showPopup (display measurements in a popup)
See this property in action in this example.
limitLimit the number of sources (default value: undefined)

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

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.