With the options described in this section, you can draw marks over your to-be-published images (for example, in PDF). Each mark can be highly customized so they can have different shapes, colors, line widths, text, text size, etc. The properties of the marks should be stored in a table that is given to the --marks option described below. A fully working demo on adding marks is provided in Marking objects for publication.
An important factor to consider when drawing vector graphics is that vector graphics standards (the PostScript standard in this case) use a “point” as the primary unit of line thickness or font size. Such that 72 points correspond to 1 inch (or 2.54 centimeters). In other words, there are roughly 3 PostScript points in every millimeter. On the other hand, the pixels of the images you plan to show as the background do not have any real size! Pixels are abstract and can be associated with any print-size.
In ConvertType, the print-size of your final image is set with the --widthincm option (see ConvertType input and output). The value to --widthincm is the to-be width of the image in centimeters. It therefore defines the thickness of lines or font sizes for your vector graphics features (like the image border or marks). Just recall that we are not talking about resolution! Vector graphics have infinite resolution! We are talking about the relative thickness of the lines (or font sizes) in relation to the pixels in your background image.
The width of the border to be put around the EPS and PDF outputs in units of PostScript points. If you are planning on adding a border, its thickness in relation to your image pixel sizes is highly correlated with the value you give to the --widthincm parameter. See the description at the start of this section for more.
Unfortunately in the document structuring convention of the PostScript language, the “bounding box” has to be in units of PostScript points with no fractions allowed.
So the border values only have to be specified in integers.
To have a final border that is thinner than one PostScript point in your document, you can ask for a larger width in ConvertType and then scale down the output EPS or PDF file in your document preparation program.
For example, by setting width in your includegraphics command in TeX or LaTeX to be larger than the value to --widthincm.
Since it is vector graphics, the changes of size have no effect on the quality of your output (pixels do not get different values).
The name of the color to use for border that will be put around the EPS and PDF outputs. The list of available colors, along with their name and an example can be seen with the following command (also see Vector graphics colors):
$ astconvertt --listcolors
This option only accepts the name of the color, not the numeric identifier.
Draw vector graphics (infinite resolution) marks over the image. The value to this option should be the file name of a table containing the mark information. The table given to this option can have various properties for each mark in each column. You can specify which column contains which property of the marks using the options below that start with --mark. Only two property columns are mandatory (--markcoords), the rest are optional.
The table can be in any of the Gnuastro’s Recognized table formats. For more on the difference between vector and raster graphics, see Raster and Vector graphics. For example, if your table with mark information is called my-marks.fits, you can use the command below to draw red circles of radius 5 pixels over the coordinates.
$ astconvertt image.fits --output=image.pdf \
--marks=marks.fits --mode=wcs \
--markcoords=RA,DEC
You can highly customize each mark with different columns in marks.fits using the --mark* options below (for example, using different colors, different shapes, different sizes, text, and the rest on each mark).
The HDU (or extension) name or number of the table containing mark properties (file given to --marks). This is only relevant if the table is in the FITS format and there is more than one HDU in the FITS file.
The column names (or numbers) containing the coordinates of each mark (in table given to --marks). Only two values should be given to this option (one for each coordinate). They can either be given to one call (--markcoords=RA,DEC) or in separate calls (--markcoords=RA --markcoords=DEC).
When --mode=image the columns will be associated to the horizontal/vertical coordinates of the image, and interpreted in units of pixels. In --mode=wcs, the columns will be associated to the WCS coordinates (typically Right Ascension and Declination, in units of degrees).
The coordinate mode for interpreting the values in the columns given to the --markcoord1 and --markcoord2 options.
The acceptable values are either img (for image or pixel coordinates), and wcs for World Coordinate System (typically RA and Dec).
For the WCS-mode, the input image should have the necessary WCS keywords, otherwise ConvertType will crash.
The column name(s), or number(s), containing the shapes of each mark (in table given to --marks). The shapes can either be identified by their name, or their numerical identifier. If identifying them by name in a plain-text table, you need to define a string column (see Gnuastro text table format). The full list of names is shown below, with their numerical identifier in parenthesis afterwards. For each shape, you can also specify properties such as the size, line width, rotation, and color. See the description of the relevant --mark* option below.
circle (1)A circular circumference. It’s radius is defined by a single size element (the first column given to --marksize). Any value in the second size column (if given for other shapes in the same call) are ignored by this shape.
plus (2)The plus sign (\(+\)). The length of its lines is defined by a single size element (the first column given to --marksize). Such that the intersection of its lines is on the central coordinate of the mark. Any value in the second size column (if given for other shapes in the same call) are ignored by this shape.
cross (3)A multiplication sign (\(\times\)). The length of its lines is defined by a single size element (the first column given to --marksize). Such that the intersection of its lines is on the central coordinate of the mark. Any value in the second size column (if given for other shapes in the same call) are ignored by this shape.
ellipse (4)An elliptical circumference. Its major axis radius is defined by the first size element (first column given to --marksize), and its axis ratio is defined through the second size element (second column given to --marksize).
point (5)A point (or a filled circle). Its radius is defined by a single size element (the first column given to --marksize). Any value in the second size column (if given for other shapes in the same call) are ignored by this shape.
This filled circle mark is defined as a “point” because it is usually relevant as a small size (or point in the whole image). But there is no limit on its size, so it can be arbitrarily large.
square (6)A square circumference. Its edge length is defined by a single size element (the first column given to --marksize). Any value in the second size column (if given for other shapes in the same call) are ignored by this shape.
rectangle (7)A rectangular circumference. Its length along the horizontal image axis is defined by first size element (first column given to --marksize), and its length along the vertical image axis is defined through the second size element (second column given to --marksize).
line (8)A line. The line’s length is defined by a single size element (the first column given to --marksize. The line will be centered on the given coordinate. Like all shapes, you can rotate the line about its center using the --markrotate column. Any value in the second size column (if given for other shapes in the same call) are ignored by this shape.
Column name or number that contains the mark’s rotation angle. The rotation angle should be in degrees and be relative to the horizontal axis of the image.
The column name(s), or number(s), containing the size(s) of each mark (in table given to --marks). All shapes need at least one “size” parameter and some need two. For the interpretation of the size column(s) for each shape, see the --markshape option’s description. Since the size column(s) is (are) optional, when not specified, default values will be used (which may be too small in larger images, so you need to change them).
By default, the values in the size column are assumed to be in the same units as the coordinates (defined by the --mode option, described above). However, when the coordinates are in WCS-mode, some special cases may occur for the size.
In WCS-mode, assume that the sizes are in units of pixels. By default, when in WCS-mode, the sizes are assumed to be in the units of the WCS coordinates (usually degrees).
In WCS-mode, assume that the sizes are in units of arc-seconds. By default, when in WCS-mode, the sizes are assumed to be in the units of the WCS coordinates (usually degrees).
In WCS-mode, assume that the sizes are in units of arc-seconds. By default, when in WCS-mode, the sizes are assumed to be in the units of the WCS coordinates (usually degrees).
Column containing the width (thickness) of the line to draw each mark. The line width is measured in units of “points” (where 72 points is one inch), and it can be any positive floating point number. Therefore, the thickness (in relation to the pixels of your image) depends on --widthincm option. For more, see the description at the start of this section.
Column containing the color of the mark. This column can be either a string or an integer. As a string, the color name can be written directly in your table (this greatly helps in human readability). For more on string columns see Gnuastro text table format. As an integer, you can simply use the numerical identifier of the column. You can see the list of colors with their names and numerical identifiers in Gnuastro by running ConvertType with --listcolors, or see Vector graphics colors.
The list of acceptable color names, their codes and their representation can be seen with the --listcolors option. By “representation” we mean that the color will be shown on the terminal as the background in that column. But this will only be properly visible with “true color” or 24-bit terminals, see ANSI escape sequence standard. Most modern GNU/Linux terminals support 24-bit colors natively, and no modification is necessary. For macOS, see the box below.
The printed text in standard output is in the Gnuastro text table format, so if you want to store this table, you can simply pipe the output to Gnuastro’s Table program and store it as a FITS table:
$ astconvertt --listcolors | astttable -ocolors.fits
|
macOS terminal colors: as of August 2022, the default macOS terminal (iTerm) does not support 24-bit colors! The output of --listlines therefore does not display the actual colors (you can only use the color names). One tested solution is to install and use iTerm2, which is free software and available in Homebrew. iTerm2 is described as a successor for iTerm and works on macOS 10.14 (released in September 2018) or newer. |
Column name or number that contains the text that should be printed under the mark. If the column is numeric, the number will be printed under the mark (for example, if you want to write the magnitude or redshift of the object under the mark showing it). For the precision of writing floating point columns, see --marktextprecision. But if the column has a string format (for example, the name of the object like an NGC1234), you need to define the column as a string column (see Gnuastro text table format).
For text with different lengths, set the length in the definition of the column to the maximum length of the strings to be printed. If there are some rows or marks that don’t require text, set the string in this column to n/a (not applicable; the blank value for strings in Gnuastro). When having strings with different lengths, make sure to have enough white spaces (for the shorter strings) so the adjacent columns are not taken as part of the string (see Gnuastro text table format).
The number of decimal digits to print after the floating point. This is only relevant when --marktext is given, and the selected column has a floating point format.
Column name or number that contains the font for the displayed text under the mark. This is only relevant if --marktext is called. The font should be accessible by Ghostscript.
If you are not familiar with the available fonts on your system’s Ghostscript, you can use the --showfonts option to see all the fonts in a custom PDF file (one page per font). If you are already familiar with the font you want, but just want to make sure about its presence (or spelling!), you can get a list (on standard output) of all the available fonts with the --listfonts option. Both are described below.
It is possible to add custom fonts to Ghostscript as described in the Fonts section of the Ghostscript manual.
Column name or number that contains the font size to use. This is only relevant if a text column has been defined (with --marktext, described above). The font size is in units of “point”s, see description at the start of this section for more.
Create a special PDF file that shows the name and shape of all available fonts in your system’s Ghostscript. You can use this for selecting the best font to put in the --markfonts column. The available fonts can differ from one system to another (depending on how Ghostscript was configured in that system). The PDF file’s name is constructed by appending a -fonts.pdf to the file name given to the --output option.
The PDF file will have one page for each font, and the sizes of the pages are customized for showing the fonts (each page is horizontally elongated). This helps to better check the files by disable “continuous” mode in your PDF viewer, and setting the zoom such that the width of the page corresponds to the width of your PDF viewer. Simply pressing the left/right keys will then nicely show each fonts separately.
Print (to standard output) the names of all available fonts in Ghostscript that you can use for the --markfonts column. The available fonts can differ from one system to another (depending on how Ghostscript was configured in that system). If you are not already familiar with the shape of each font, please use --showfonts (described above).
JavaScript license information
GNU Astronomy Utilities 0.23 manual, July 2024.