bionic (1) stilts-pixfoot.1.gz

NAME

       stilts-pixfoot - Generates Multi-Order Coverage maps

SYNOPSIS

       stilts pixfoot [ifmt=<in-format>] [istream=true|false] [in=<table>] [icmd=<cmds>] [order=<int-value>]
                      [ra=<expr>] [dec=<expr>] [radius=<expr>] [mocfmt=fits|json] [out=<out-file>]

DESCRIPTION

       pixfoot takes a list of sky positions from an input table and generates a  pixel  map  describing  a  sky
       region  which  includes them all. Currently the output is to a format known as a Multi-Order Coverage map
       (MOC), which is a HEALPix-based format composed of a list of HEALPix pixels of different sizes, which can
       efficiently describe complex regions. Other output formats may be introduced in the future.

       See also the Coverage class for MOC-related functions.

OPTIONS

       ifmt=<in-format>
              Specifies the format of the input table as specified by parameter in. The known formats are listed
              in SUN/256. This flag can be used if you know what format your table is in. If it has the  special
              value  (auto)  (the  default),  then  an  attempt  will  be made to detect the format of the table
              automatically. This cannot always be done correctly however, in which case the program  will  exit
              with an error explaining which formats were attempted.

       istream=true|false
              If  set  true,  the  input  table  specified  by  the in parameter will be read as a stream. It is
              necessary to give the ifmt parameter in this  case.  Depending  on  the  required  operations  and
              processing mode, this may cause the read to fail (sometimes it is necessary to read the table more
              than once). It is not normally necessary to set this flag; in most cases the data will be streamed
              automatically  if  that  is the best thing to do. However it can sometimes result in less resource
              usage when processing large files in certain formats (such as VOTable).

       in=<table>
              The location of the input table. This may take one of the following forms:

                * A filename.

                * A URL.

                * The special value "-", meaning standard input. In this case the input  format  must  be  given
                  explicitly using the ifmt parameter. Note that not all formats can be streamed in this way.

                * A  system command line with either a "<" character at the start, or a "|" character at the end
                  ("<syscmd" or "syscmd|"). This executes the given pipeline and reads from its standard output.
                  This will probably only work on unix-like systems.
               In  any case, compressed data in one of the supported compression formats (gzip, Unix compress or
              bzip2) will be decompressed transparently.

       icmd=<cmds>
              Specifies processing to be performed on the input table as specified by parameter in,  before  any
              other  processing  has  taken  place.  The  value  of  this parameter is one or more of the filter
              commands described in SUN/256. If more than one is given, they  must  be  separated  by  semicolon
              characters  (";"). This parameter can be repeated multiple times on the same command line to build
              up a list of processing steps. The sequence of commands given in this way defines  the  processing
              pipeline which is performed on the table.

              Commands may alteratively be supplied in an external file, by using the indirection character '@'.
              Thus a value of "@filename" causes the file filename to be read for a list of filter  commands  to
              execute. The commands in the file may be separated by newline characters and/or semicolons.

       order=<int-value>
              Maximum HEALPix order for the MOC. This defines the maximum resolution of the output coverage map.
              The angular resolution corresponding to order k  is  approximately  180/sqrt(3.Pi)/2^k  (3520*2^-k
              arcmin).

       ra=<expr>
              Right  ascension  in degrees for the position of each row of the input table. This may simply be a
              column name, or it may be an algebraic expression calculated from columns as explained in SUN/256.
              If  left  blank,  an  attempt  is  made to guess from UCDs, column names and unit annotations what
              expression to use.

       dec=<expr>
              Declination in degrees for the position of each row of the input  table.  This  may  simply  be  a
              column name, or it may be an algebraic expression calculated from columns as explained in SUN/256.
              If left blank, an attempt is made to guess from UCDs,  column  names  and  unit  annotations  what
              expression to use.

       radius=<expr>
              Expression  which  evaluates  to the radius in degrees of the cone at each row of the input table.
              The default is "0", which treats each position as a point rather than a cone, but a constant or an
              expression as described in SUN/256 may be used instead.

       mocfmt=fits|json
              Determines the output format for the MOC file.

       out=<out-file>
              The  location  of  the  output file. This is usually a filename to write to. If it is equal to the
              special value "-" the output will be written to standard output.

SEE ALSO

       stilts(1)

       If the package stilts-doc is installed, the full documentation SUN/256 is available in HTML format:
       file:///usr/share/doc/stilts-doc/sun256/index.html

VERSION

       STILTS version 3.1-2-debian

       This is the Debian version of Stilts, which lack the support of some file formats and network  protocols.
       For differences see
       file:///usr/share/doc/stilts/README.Debian

AUTHOR

       Mark Taylor (Bristol University)

                                                    Mar 2017                                   STILTS-PIXFOOT(1)