The usage of mocshape is
stilts <stilts-flags> mocshape ifmt=<in-format> istream=true|false
icmd=<cmds> moctype=SMOC|TMOC|STMOC
order=0..29
shape=point|circle|polygon|moc-ascii|uniq|stc-s
coords=<expr> torder=0..61
tshape=point|range|day-extent|day-radius|sec-extent|sec-radius
ttype=DecYear|MJD|JD|Unix|Iso8601
t0=<time-expr> t1=<expr>
mocfmt=ascii|fits|json|raw|summary|cds_ascii|cds_json|cds_fits
mocimpl=auto|cds|cds-batch|bits|lists
out=<out-file>
[in=]<table>
If you don't have the stilts script installed,
write "java -jar stilts.jar" instead of
"stilts" - see Section 3.
The available <stilts-flags> are listed
in Section 2.1.
For programmatic invocation,
the Task class for this
command is uk.ac.starlink.ttools.task.MocShape.
Parameter values are assigned on the command line as explained in Section 2.3. They are as follows:
coords = <expr> (String)
shape parameter.
Note the value of this parameter is a single expression
not a list of expressions, so if you need to supply an
array value from a list of scalar values you may need to use
array construction functions
from the Arrays class,
e.g. write
"coords=array(ra,dec)"
and not
"coords=ra,dec".
This parameter is only used if there is a Space component
of the output MOC
(moctype=smoc or stmoc).
icmd = <cmds> (ProcessingStep[])
in,
before any other processing has taken place.
The value of this parameter is one or more of the filter
commands described in Section 6.1.
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 alternatively 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,
and lines which are blank or which start with a
'#' character are ignored.
A backslash character '\' at the end of a line
joins it with the following line.
ifmt = <in-format> (String)
in.
The known formats are listed in Section 5.1.1.
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.
This parameter is ignored for scheme-specified tables.
[Default: (auto)]
in = <table> (StarTable)
-",
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.:<scheme-name>:<scheme-args>.<" 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.istream = true|false (Boolean)
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).
This parameter is ignored for scheme-specified tables.
[Default: false]
mocfmt = ascii|fits|json|raw|summary|cds_ascii|cds_json|cds_fits (MocStreamFormat)
[Default: ascii]
mocimpl = auto|cds|cds-batch|bits|lists (MocImpl)
auto: Chooses a suitable implementation
cds: Uses cds.moc classes
cds-batch: Uses cds.moc classes with batching
bits: Uses BitSets
lists: Uses BitSets and lists
[Default: auto]
moctype = SMOC|TMOC|STMOC (MocType)
SMOC: Space MOC
TMOC: Time MOC
STMOC: Space-Time MOC
[Default: SMOC]
order = 0..29 (Integer)
This parameter is only used if there is a Space component
of the output MOC
(moctype=smoc or stmoc).
[Default: 10]
out = <out-file> (uk.ac.starlink.util.Destination)
[Default: -]
shape = point|circle|polygon|moc-ascii|uniq|stc-s (AreaMapper)
coords parameter,
i.e. the type of shape defined by the supplied coordinates.
The options are:
point: 2-element array (ra,dec)
circle: 3-element array (ra, dec, r)
polygon: 2n-element array (ra1,dec1, ra2,dec2,...);
a NaN,NaN pair can be used to delimit distinct polygons.
moc-ascii: Region description using ASCII MOC syntax;
see MOC 2.0 sec 4.3.2.
Note there are currently a few issues
with MOC plotting, especially for large pixels.
uniq: Region description representing a single HEALPix cell
as defined by an UNIQ value, see
MOC 2.0
sec 4.3.1.
stc-s: Region description using STC-S syntax;
see TAP 1.0, section 6.
Note there are some restrictions:
<frame>, <refpos> and <flavor> metadata are ignored,
polygon winding direction is ignored (small polygons are assumed)
and the INTERSECTION and NOT constructions are not supported.
The non-standard MOC construction is supported.
This parameter is only used if there is a Space component
of the output MOC
(moctype=smoc or stmoc).
t0 = <time-expr> (String)
t1
parameter, is determined by the value of the
tshape parameter.
The specified epoch is interpreted according to the value
of the ttype parameter.
This parameter is only used if there is a Time component
of the output MOC
(moctype=tmoc or stmoc).
t1 = <expr> (String)
t0 parameter,
is determined by the value of the
tshape parameter;
for some values of tshape
it is not required.
If this quantity represents an epoch
(for instance the end of a time range rather than a duration)
it is interpreted according to the value of the
ttype parameter.
This parameter is only used if there is a Time component
of the output MOC
(moctype=tmoc or stmoc).
torder = 0..61 (Integer)
This parameter is only used if there is a Time component
of the output MOC
(moctype=tmoc or stmoc).
[Default: 31]
tshape = point|range|day-extent|day-radius|sec-extent|sec-radius (TimeIntervalType)
t0 and perhaps
t1 parameters are interpreted
to define a time interval.
The options are:
point: zero-extent interval; t0 gives the epoch and t1 is not used
range: interval between two given epochs, given by t0 and t1
day-extent: interval starting at epoch t0 with an extent given in units of day by t1
day-radius: interval centered on epoch t0 with a half-extent given in units of day by t1
sec-extent: interval starting at epoch t0 with an extent given in units of second by t1
sec-radius: interval centered on epoch t0 with a half-extent given in units of second by t1
This parameter is only used if there is a Time component
of the output MOC
(moctype=tmoc or stmoc).
[Default: point]
ttype = DecYear|MJD|JD|Unix|Iso8601 (TimeMapper)
t0
and possibly the t1 parameters.
The options are:
DecYear: Years since 0 AD
MJD: Modified Julian Date
JD: Julian Day
Unix: Seconds since midnight 1 Jan 1970
Iso8601: ISO 8601 string
t0 parameter.
This parameter is only used if there is a Time component
of the output MOC
(moctype=tmoc or stmoc).