• 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
showCooGrid	If true, the coordinate grid will be displayed	false
showCooGridControl	If true, the coordinate grid control GUI is displayed	false
projection	Set the projection of the view. Possible values are SIN, AIT, MOL, ARC, TAN, among others	SIN
showProjectionControl	If true, the projection control GUI selector 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
expandLayersControl	If true, the layers control GUI will be expanded	false
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
showContextMenu	If 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
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.

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

• 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.

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>)

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

• 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:

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.