Next Previous Up Contents
Next: keepcols
Up: Processing Filters
Previous: head

#### 6.1.18 `healpixmeta`

Usage:

       healpixmeta [-level <n>] [-implicit|-column <col-id>] [-csys C|G|E] [-nested|-ring]

Adjusts the table metadata items that describe how HEALPix pixel data is encoded in the table.

Zero or more of the following flags may be supplied:

- `-level <n>`: Defines the HEALPix level; the sky is split into 12*4^n pixels. This quantity is equal to logarithm base 2 of NSIDE.
- `-implicit`: Declares that pixel indices are implicit, so that row i represents HEALPix pixel index i. The table should have 12*4^level rows in this case. Not to be used with `-column`.
- `-column <col-id>`: Declares that the column identified contains the (0-based) HEALPix pixel index. Not to be used with `-implicit`.
- `-csys C|G|E`: Declares the sky coordinate system to which the HEALPix pixels apply: Celestial(=equatorial), Galactic or Ecliptic. Some applications assume Galactic if this is not specified.
- `-nested`: Declares that the NESTED ordering scheme is in use. Not to be used with `-ring`.
- `-ring`: Declares that the RING ordering scheme is in use. Not to be used with `-nested`.

The effect of this filter is to write, or overwrite, certain special table parameters (per-table metadata) that STIL uses to describe how HEALPix pixel information is encoded in a table, specifically the HEALPix level, the column containing pixel index, the ordering scheme, and the sky coordinate system. Adding these parameters doesn't do anything on its own, but some of the STIL I/O handlers recognise these parameters, and they affect how the table will be formatted for output. In particular, if you set these parameters and then output to FITS format, the output table will contain headers defined by the HEALPix-FITS serialization format which is understood by several other applications to describe HEALPix maps. If you write to VOTable format, the metadata will only be recognised by other STIL-based applications but it means that if you, e.g., load the table into TOPCAT and then write it out again as FITS, the HEALPix information should be preserved.

When writing tables marked up like this to FITS, you have two options. If you write to one of the "normal" FITS formats (e.g. `fits`, `fits-basic`) then suitable headers will be added; in this case if an explicit pixel index column is used it must be the first column, and should be named "PIXEL". This may be enough for other applications to recognise the HEALPix metadata. However, if you use the special `fits-healpix` format more efforts will be made to conform to the HEALPix-FITS convention, for instance moving and renaming the explicit pixel index column if required.

The table parameters affected by this filter are: `STIL_HPX_LEVEL`, `STIL_HPX_ISNEST`, `STIL_HPX_COLNAME`, `STIL_HPX_CSYS`. Note these are not defined by any standard, they are defined and used only by STILTS and related applications (TOPCAT).

Syntax for the `<col-id>` argument is described in Section 6.2.

Next Previous Up Contents
Next: keepcols
Up: Processing Filters
Previous: head

STILTS - Starlink Tables Infrastructure Library Tool Set
Starlink User Note256
STILTS web page: http://www.starlink.ac.uk/stilts/
Author email: m.b.taylor@bristol.ac.uk
Mailing list: topcat-user@jiscmail.ac.uk