Annotations

Annotations are glyphs displayed on top of images to depict the presence of known sky objects, like galaxies, bright stars and so on. They come from catalogues but can only be displayed on images for which we know which part of the sky they represent, images that have been plate solved and contain the world coordinate system (WCS) information in their header, so only FITS or Astro-TIFF files.

View of full annotated image

Plate solving, can be done within Siril in the menu Tools ‣ Astrometry ‣ Image Plate Solver... entry, or using external tools like astrometry.net or ASTAP.

Buttons for annotations

When a plate solved image is loaded in Siril, you can see the sky coordinates for the pixel under the mouse pointer displayed at the bottom right corner and the buttons related to annotations become available. The first button toggles on or off object annotations, the second the celestial grid and the compass.

Offline annotation catalogues

Siril comes with a predefined list of catalogues for annotations:

• Messier catalogue (M)

• New General Catalogue (NGC)

• Index Catalogue (IC)

• Lynds Catalogue of Dark Nebulae (LdN)

• Sharpless Catalogue (Sh2)

• Star Catalogue (3661 of the brightest stars)

In addition, 2 user defined catalogues can be used:

• User DeepSky Objects Catalogue (DSO)

• User Solar System Objects Catalogue (SSO)

They are populated with the commands described in the section about searching for a known object.

They are stored in the user settings directory. Their location depends on the operating system:

• for Unix-based OS they will be in ~/.config/siril/catalogue

• on Windows they are in %LOCALAPPDATA%\siril\catalogue.

All of the above catalogues can be enabled/disabled for display in the Preferences menu ‣ Astrometry tab.

The two user defined catalogues can also be purged (i.e. deleted) via the appropriate buttons.

A slider on the right side, allows you to easily navigate across the catalogue list.

Catalogue management in Preferences/Astrometry

These annotation catalogues are used primarily for display purposes. Starting from Siril 1.3, they are also used to locate the center of the image for astrometry tool. If the object is found locally, the resolver will be shown as Local. If not, it will fall back using an online resolver.

Object resolved from local annotations catalogues

Online annotation catalogues

You may want to query other databases than the ones already shipped with Siril, described in the offline annotation catalogues section. This works, again, for plated-solved images only.

Starting from Siril 1.3, this is possible with the command conesearch. This new command replaces and expands capabilities previously provided by nomad and solsys from Siril 1.2.

Siril command line

conesearch [limit_magnitude] [-cat=] [-phot] [-obscode=] [-tag={on|off}] [-log={on|off}] [-trix=] [-out=]

Displays stars from the local catalog by default for the loaded plate solved image, down to the provided limit_magnitude (13 by default for most catalogues, except 14.5 for aavso_chart, 20 for solsys, and ommitted for pgc).

An alternate online catalog can be specified with -cat=, taking values

- for stars: tycho2, nomad, gaia, ppmxl, bsc, apass, gcvs, vsx, simbad, aavso_chart

- for exoplanets: exo

- for deep-sky: pgc

- for solar system objects: solsys (closest IAU observatory code can be passed with the argument -obscode= for better position accuracy)

For stars catalogues containing photometric data, stars with no B-V information will be kept; they can be excluded by passing -phot

The argument -trix= can be passed instead of a catalogue followed by a number between 0 and 511 to plot stars contained in local catalogues trixel of level 3 (for dev usage mainly)

Some catalogs (bsc, gcvs, pgc, exo, aavso_chart, varisum and solsys) will also display, by default, names alongside markers in the display (GUI only) and list them in the log. For others with larger number of objects, namely vsx and simbad, the information can also be shown but, as it may clutter the display, it is not activated by default. This behavior can be toggled on/off with the options -tag=on|off to display names alongside markers and -log=on|off to list the objects in the console log

The list of items that are present in the image can optionally saved to a csv file by passing the argument -out=

Todo

To be expanded when we have the new UI elements

The table below lists all the catalogues that are available, alongside links to the original data.

Table of available catalogues

Catalogue	-cat=	Reference
Local	Omitted	local star catalogues
Tycho2	tycho2	https://cdsarc.cds.unistra.fr/viz-bin/cat/I/297
Nomad	nomad	https://cdsarc.cds.unistra.fr/viz-bin/cat/I/297
GAIA DR3	gaia	https://cdsarc.cds.unistra.fr/viz-bin/cat/I/355
PPMXL	ppmxl	https://cdsarc.cds.unistra.fr/viz-bin/cat/I/317
Bright Stars Catalogues	bsc	https://cdsarc.cds.unistra.fr/viz-bin/cat/V/50
APASS DR9	apass	https://cdsarc.cds.unistra.fr/viz-bin/cat/II/336
GCVS	gcvs	https://cdsarc.cds.unistra.fr/viz-bin/cat/B/gcvs
VSX	vsx	https://cdsarc.cds.unistra.fr/viz-bin/cat/B/vsx
SIMBAD	simbad	https://simbad.cds.unistra.fr/simbad/sim-tap/
PGC/HYPERLEDA	pgc	https://cdsarc.cds.unistra.fr/viz-bin/cat/VII/237
Exoplanet archive	exo	https://exoplanetarchive.ipac.caltech.edu
AAVSO VSP	aavso_chart	https://app.aavso.org/vsp/
IMCCE Solar system skybot	solsys	https://vo.imcce.fr/webservices/skybot/?conesearch

The following queries are brought to you thanks to:

• Vizier (through CDS Vizier TAP query service)

• Simbad (through CDS Simbad TAP query service)

• IMCCE (through its skybot conesearch service)

• NASA exoplanet archive (though its TAP query service)

For solar system object queries, you may pass an additional parameter -obscode=, the 3-symbol code for an IAU observatory close by to your observing location. This will improve annotations accuracy. Please note that results may still slightly differ from those obtained by making a direct ephemerides query for a specific object, which uses the exact observing location (if present in the FITS header).

Tip

A preferred observatory code may be set in the Astrometry tab in the Preferences dialog. If set, this will be used for the Solar System Objects GUI tool and will also be used in the conesearch command unless the -obscode= argument is provided.

These additional annotations will be displayed in RED, to differentiate them from offline annotations, shown in GREEN. These annotations will be erased as soon as the Show Objects names button is toggled.

Result of a Search Solar System process

Extra catalogues

You may want to display your own user catalogues. This can be done with the command show. This command can also be used to display, for instance, csv files created with the feature to find comparison stars.

Siril command line

show [-clear] [{ -list=file.csv | [name] RA Dec }] [-nolog] [-notag]

Shows a point on the loaded plate solved image using the temporary user annotations catalogue, based on its equatorial coordinates. The -clear option clears this catalogue first and can be used alone.

Several points can be passed using a CSV file with the option -list= containing at least ra and dec columns. If the passed file also contains a column name, names will be used as tags in the image and listed in the Console, unless toggled off with the options -notag and -nolog.

This is only available from the GUI of Siril

These catalogues may be any csv (comma-separated) file, respecting the following rules:

• comments lines if any, should start with a # sign

• a line should be present at the top with the column names, comma separated

• at least ra and dec columns should be provided, in decimal degrees.

• the columns can be written in no particular order

• other columns can be passed:

  • name (str)

  • diameter (double), the object diameter in arcmin

  • mag (double), the object magnitude

  • type (str), which will be appended between () after the name in the Console

Other columns than those listed above may be passed but they will not be used.

List of known user catalogues:

Sometimes, users create their own catalogues, we can try to link them here to help everybody.

• Variable stars, extracted from GCVS 5.1, discussed here in French, (file link).

Warning

Contrarily to the instructions discussed in the linked topic, it is not recommended to replace the user-DSO catalogue with such files. The usage is discouraged as some of them could be particularly big and would slow down tremendously every annotation redraw.

Search for a known object

If you know a specific object is somewhere in the image (if not, see the search for an unknown object section), it is possible to add it to annotations.

Deep-sky objects

Load a plate-solved image and type Ctrl+Shift+/ or Search Object... in the menu Tools ‣ Astrometry.

A small search dialog will appear where object names can be entered. Pressing Enter will first search for this name the existing annotation catalogues in case it already exists under another name. If not it will send an online request to SIMBAD to get the coordinates of an object with such a name. If found, and not already in any catalogue, the object will be added to the Deep Sky user catalogue.

The items of this catalogue are displayed in ORANGE while the objects from the predefined catalogues are displayed in GREEN.

Deep sky objects from user and predefined catalogues

Examples of valid input (not case sensitive):

• HD 86574 or HD86574 are both valid for this star

Solar-system objects

From Siril version 1.2, objects from the solar system can also be searched for, using the Miriade ephemcc service. This is done in the same manner as for Deep Sky Objects, but prefixing the name of the object to be searched by some keyword representing the type of object: a: for asteroids, c: for comets, p: for planets, dp: for dwarf planets and s: for natural satellites. If you query an image taken from a close enough date and time (same night) than another image already annotated with SSOs, their cached positions will be used and corrected by each object velocity as returned by the ephemerids. The items of this catalogue are displayed in YELLOW.

Examples of valid inputs (not case sensitive):

• c:67p or c:C/2017 T2 are valid forms for comets

• a:1 and a:ceres are both valid for (1) Ceres

• a:2000 BY4 is valid for 103516 2000 BY4

• p:4 or p:mars are both valid for Mars

• dp:Pluto is valid for Pluto

• s:Moon or s:Io is valid for natural satellites.

Warning

Images that do not have a DATE-OBS header key cannot be annotated for SSOs. Images that do not have observer location information (SITELAT, SITELONG and SITEELEV header keys) will still be annotated, but assuming a geocentric observer position, i.e. as if observing from center of the Earth. Depending on objects distance wrt. Earth, this may result in positions being slightly offset from their real positions.

Command catsearch

The same feature is accessible through the command catsearch:

Siril command line

catsearch name

Searches an object by name and adds it to the user annotation catalog. The object is first searched in the annotation catalogs, if not found a request is made to SIMBAD.

The object can be a solar system object, in which case a prefix, 'a:' for asteroid, 'p:' for planet, 'c:' for comet, 'dp:' for dwarf planet or 's:' for natural satellite, is required before the object name. The search is done for the date, time and observing location found in the image header, using the IMCCE Miriade service

Search for an unknown object

Especially useful for photometry works, it is possible to identify a star or other objects in the image by drawing a selection around them, right clicking to bring up the context menu, and selecting the PSF entry.

This will open the PSF window, and if it is a star it will display the Gaussian fit parameters, but it will also display a Web link at the bottom left of the window. Opening it will bring you to the SIMBAD page for the coordinates of the object and in many cases will give you the name of the object.

SIMBAD does not have all known objects, but the coordinates from the page can still be used as a starting point to look for the object in other online catalogues, for example Gaia DR3 (VizieR).