Using the Pixinsight Annotate Script; Custom Catalogues - Brief Guide

[coatesg]

At @swag72's request, I'm putting together a quick guide as to how to use the Pixinsight annotate script, including how to produce and use custom catalogues.  [Mods - please feel free to move as needed if this isn't the right place to put this!]

I'll use an image to demonstrate this - this is the (unprocessed!) L channel from an image of the region containing and to the north of the Coathanger. First step is to solve the image - most of the time, this is simple to do using the Image Solver script. 

The Image Solver needs some initial coordinates to setup the search. You can search for the image coordinates using the Search function if they aren't already set - if they are being dragged through from the image (eg from SGP) they will already be populated (or at least be close). The coordinates don't need to be accurate, but the closer the better - at the least, make sure the image contains the seed coordinates. Here, I've searched for "Collinder 399" and it returns the coordinates of the Coathanger (at the bottom of the image). Set the focal length, pixel size, and hit OK - you shouldn't need to change params unless it fails to solve (beyond the scope of this guide!). 

If it all goes OK, then you'll get a set of coordinates, image size displayed in the Process Console. (HINT: It's sometimes easier to solve a linear image if a non-linear refuses to solve).

At this point, the image has a solution, and it will be retained as long as you don't crop, rotate, scale, resize, etc the image. (it'll warn you if the action you are performing will affect the solution). 

At this point, we can move onto the annotation. 

The default settings for the Annotate script (Script > Render) are shown - this is a very simple set of parameters (though, the NamedStars and Tycho catalogues will result in a very busy annotated image!!). 

The options available for each of the catalogues allows the user to set options such as the colour of the marker/text, the size of the text and the relative position of the text with regards to the centre of the object. 

The user can also choose to include other catalogues in the routine - there are quite a few catalogues available to the user by default - these can be found by using the "+" button below the "Layers" list of catalogues:

At this point, hitting "OK" is usually good enough to get an annotated image produced - the result of using the script with the VdB and Sharpless catalogues added, and with the Tycho/Named stars catalogues off. 

Next up is how to create new catalogues for more obscure targets....

Edited August 29, 2018 by coatesg

[steppenwolf]

Thank you for posting this workflow - excellent information!

[coatesg]

Quite often, you'd like to use the Annotate script to use custom catalogues to annotate your images. If you can't find the catalogue to download online, then you can make your own for use in the script. The script uses tab separated files with the following headers:

RA
DEC
NAME
DIAMETER

RA and DEC are set in the file as decimal values - RA going from 0 to 360, DEC from 90 to -90. NAME is freetext (and what is used in the annotation), and the DIAMETER is in arcmin.

If you only have a couple of objects you want to add onto an image, you can create the file by hand - here is an example of a file as viewed in Notepad++ (with the tabs visible in the file to make it clear how the file is constructed):

You might feel that copying this out for large catalogues is beyond your patience in data entry (!) - at this point, we need a way of downloading and manipulating the data on a computer. Here, I'm going to use the web site "VizieR" (http://vizier.u-strasbg.fr/viz-bin/VizieR) to grab a catalogue in computer format to allow me to get it into PI. 

VizieR has what appears to be a rather complicated interface, but you simply need to search for the catalogue you are after - most of the time, the prefix is fairly easy to sort out - here I'm searching for the LBN (Lynd's Bright Nebula) catalogue. The search feature will also search for Author as a keyword:

Hitting "Find..." results in the following result:

From this screen we can choose what information we'd like to return from the search. We don't need to return all the columns to be sufficient to feed Annotate. VixieR will calculate RA/Dec coordinates in J2000 epoch from the data in the catalogue (here the catalogue is in J1950 epoch, so this is very handy...) - the checkbox for this is in Preferences on the left and set by default. From the main section, we need to deselect everything and then select "Seq" (Running number) and "Diam1" (Largest dimension - already in arcmin). Make sure you change the Dropdowns in preferences to "ascii text plain" (to force text output rather than a web page), and set "max:" to "Unlimited" once you're happy you have the correct parameters [NB: I have a feeling there is a hard limit on the size of result set that can be returned - there's something in the VizieR FAQ about this - I've not hit it yet myself....]. Also ensure the position is calculated in decimal using the option at the bottom of the Preferences box. 

[NB: it may not always be this easy - sometimes the diameter is missing (this is OK for the annotations  as it produces a cross) or you have something else like diameter so you'll have to convert.)]

Result is as follows:

From here, we need just the data in the table after the headers - copying this out into a text file is sufficient to allow its import into Excel using the option to import delimited data (with a space as the delimiter). At this point, we need to add the headers into the file as per the file example above, and add the catalogue prefix onto the data in the Seq (ie the NAME) column.  Here's an example of the file in excel after the fiddling around with the name column (HINT: the CONCATENATE() function is useful here). 

The final step here is to save the file in the right format - Excel does it fo you by choosing "Text (Tab delimited)" as the format option in the save as dialog:

Next up is how to use the custom catalogues.

 

Edited August 29, 2018 by coatesg

[coatesg]

So by this stage, we should have a tab separated file with the catalogue we want to include in the annotate script. 

To add this catalogue into the Annotate script, we use the "+" button on the Annotate script window, and then choose "Custom Catalogue" towards the bottom of the list in the Add Layer dialog.

Once the "Custom Catalog" option is selected and added, you have to then choose the Catalog Path (where you saved the tab separated txt file), set the colours, and then hit OK again to re-run the annotation using the new catalog.

With the final result (note the two LBN objects):

And that's the basics of obtaining a custom catalogue from VizieR and using it - here's a few catalogues I've already made:

Lynd's Bright Nebulae : lbn.txt
Lynd's Dark Nebulae: ldn.txt
Bologna Catalogue of M31 Globular clusters: revised_bologna.txt

 

Edited August 29, 2018 by coatesg

[coatesg]

Hints/Notes:

There are instances where the catalogue isn't present in VizieR -  mainly older obscure catalogues - I offer the Bernes catalogue (Bernes, 1977) as an example here. Bernes 100 (written in Aladin/CDS speak as: "[B77] 100") is a small bright neb just to the north of M78. In these instances, you might be able to find it in a separate catalogue, or if not (as in Bernes 100!) just be better off making the data file by hand! This is equally the case if there's only a couple of items you want to add onto the image. You can look up the items by loading a Simbad layer in Aladin - this allows you to click on known items and get the details you need. In Aladin desktop, this is available under the tree on the left under Collections > Database. 

Note that catalogues get added into VizieR on a regular basis as long as the catalogue is in a standard format. Details are in the news items on the VizieR homepage: http://vizier.u-strasbg.fr/vizier/index.gml

=====

If the image fails to solve (or you have a non-linear version that won't solve for example - I had this problem with a processed version of the Coathanger; the non-linear nature appears to upset the star matching algorithms in use). In this instance, check your parameters first - the closer the params, the easier the solve is.

If this still fails, you could try doing a solve on a linear version of the image, and then transfer the coordinates using the DynamicAlignment process, followed by the ManualImageSolver script in Pixinsight. The PI documentation is quite good for this: https://pixinsight.com/doc/scripts/ManualImageSolver/ManualImageSolver.html . The first stage is to solve the linear image. Then start DynamicAlignment - choose the solved image as source, with the other image as target. Then, if the geometry is the same/similar, clicking on source stars all over the source image should produce matching stars in the target. Choose tens of stars all over the image, and then drag the DynamicAlignment window onto the desktop to make a process icon for the alignment. After this, fire up the Manual Solver script and, choosing the linear image as the source, and the icon you created as the Control Points Icon, you can get PI to apply a solution across from one image to another. This should then allow Annotate to run. 

 

Hope this has all helped!

Edited August 28, 2018 by coatesg

[swag72]

Wow! This is a great post!! Thank you! I'm going to give it a go and see how it works. I can get the PI annotating to work, it's the catalogues that have me scratching my head...... I'll report back  

[swag72]

@coatesg - Mmmm... I've come up with some interesting quirks!!! But I hope I can work around them somehow

Edited August 29, 2018 by swag72

[coatesg]

1 hour ago, swag72 said:

@coatesg - Mmmm... I've come up with some interesting quirks!!! But I hope I can work around them somehow

Let us know if you hit a block and we'll see if we can work round it! The catalogues aren't always consistent, and that can cause a hiccup or two.

[swag72]

7 minutes ago, coatesg said:

Let us know if you hit a block and we'll see if we can work round it! The catalogues aren't always consistent, and that can cause a hiccup or two.

How did you get the diameters on the LDN catalogue as I can't see it in Vizier ?

[coatesg]

7 minutes ago, swag72 said:

How did you get the diameters on the LDN catalogue as I can't see it in Vizier ?

Ha! I think I converted the square area in degrees to a diameter  (Not that accurate, but probably close enough).

As I said, old catalogues are quite inconsistent!! ?

 

Edited August 29, 2018 by coatesg

[coatesg]

(Also note, diameter isn't a required field - it produces a cross on the annotation if null)

Edited August 29, 2018 by coatesg

[swag72]

I've just been doing some cross referencing between catalogues..... They're not very accurate in some places, so not sure what should be believed.

[coatesg]

Always errors - even Messier had a couple of errors...

Catalogues will also always vary in values (eg comparing Sh2 to NGC/IC will always give slightly different values for the same object) - the VizieR catalogues are (should be!) straight copies of catalogues from papers and they have the publication reference in the search results. You'll also find that a lot of deep amateur images show a lot more than professional catalogues indicate.

Remember as well, if the paper is reasonably old, the original coords will be in J1950, so that's why you need the J2000 coords to account for precession.

[Aramcheck]

Many thanks @coatesg - I'd been wanting to annotate an image of NGC185 to see if I had captured any globular clusters, and this was just the ticket!

Cheers
Ivor