The STILTS package provides some capabilities,
for instance plotting, that might be useful
as part of other Java applications.
The code that forms STILTS is fully documented at the API level;
there are comprehensive javadocs throughout for the
uk.ac.starlink.ttools package, its subpackages,
and most of the other classes in the
tree on which it relies.
Anybody is welcome to use these classes at their own risk,
but the code does not form a stable API intended for public use:
the javadocs are not distributed as part of the package
(though you may be able to find them
tutorial documentation is not provided, and there is no commitment
to API stability between releases.
With this in mind, there are facilities for invoking the
STILTS commands programmatically from third-party java code.
Of course it is possible to do this by just calling the
main(String) method of the application
but we document here how it can be done in a way which
allows more control, using the
parameter handling framework.
Each of the STILTS tasks listed in Appendix B
is represented by a class implementing the
these all have no-arg constructors.
To run it, you need to create an instance of the class,
pass it an
object which can acquire values for parameters by name, and then execute it.
class, based on a Map containing name/value pairs,
is provided for this purpose.
As well as managing parameter values, MapEnvironment captures
table and text output in a way that lets you retrieve it after
the task has executed.
Here is a simple example for invoking the calc task
to perform a simple calcation:
MapEnvironment env = new MapEnvironment(); env.setValue( "expression", "sqrt(3*3+4*4)" ); Task calcTask = new uk.ac.starlink.ttools.task.Calc(); calcTask.createExecutable( env ).execute(); String result = env.getOutputText();The execution corresponds exactly to the command-line:
stilts calc expression="sqrt(3*3+4*4)"The Usage section for the
task notes that the corresponding Task subclass is
Also in the usage section, each parameter reports the data type that
it may take, and objects of this type may be used as the parameter
value passed in the
MapEnvironment as an alternative
to passing string values.
For the case of the input table parameters,
so in a task like
if you want to read a file "data.fits",
you can either write
env.setValue( "in", "data.fits" );or
StarTable table = new StarTableFactory().readStarTable( "data.fits" ); env.setValue( "in", table );That doesn't buy you much, but the table could equally be obtained from any other source, including being a user-defined iterable over existing data structures. See SUN/252 for more information on
For some short examples of programs which invoke STILTS tasks
in this way, see the source code of some of the examples in the
Some commands provide additional methods for use with parameter-based invocation. In particular the plotting commands can be used to create JComponent objects that can be incorporated into an existing GUI. A working example of this can be found in the source code for the example EnvPlanePlotter class. For some more tutorial introductions to using the plotting classes programmatically, see also the example classes SinePlot, ApiPlanePlotter, and BasicPlotGui in the same place.