Package uk.ac.starlink.ast

Provides an interface to the Starlink AST library.

See:
          Description

Interface Summary
Grf Interface for specifying graphics implementations used by Plots.
NeedsChannelizing Declares that an AstObject requires object-specific preparation before writing to and/or after reading from a Channel.
Ukern1Calculator Interface for user-provided 1-d kernel interpolation functions.
 

Class Summary
AstObject Java interface to the AST Object class - base class for all AST Objects.
AstPackage Provides information about the status of the JNIAST package.
AstroCoords Represents an AstroCoords element from the Space-Time Coordinate (STC) metadata.
Axis Java interface to the AST Axis class.
Box Java interface to the AST Box class - a box region with sides parallel to the axes of a Frame.
Channel Java interface to the AST Channel class - basic (textual) I/O channel.
Circle Java interface to the AST Circle class - a circular or spherical region within a Frame.
CmpFrame Java interface to the AST CmpFrame class - compound Frame.
CmpMap Java interface to the AST CmpMap class - compound Mapping.
CmpRegion Java interface to the AST CmpRegion class - a combination of two regions within a single Frame.
DSBSpecFrame Java interface to the AST DSBSpecFrame class - dual sideband spectral coordinate system description.
DssMap Java interface to the AST DssMap class.
Ellipse Java interface to the AST Ellipse class - an elliptical region within a 2-dimensional Frame.
FitsChan Java interface to the AST FitsChan class - I/O Channel using FITS header cards to represent Objects.
FluxFrame Java interface to the AST FluxFrame class - measured flux description.
Frame Java interface to the AST Frame class - coordinate system description.
FrameSet Java interface to the AST FrameSet class - set of inter-related coordinate systems.
GrismMap Java interface to the AST GrismMap class - transform 1-dimensional coordinates using a grism dispersion equation.
Interval Java interface to the AST Interval class - a region representing an interval on one or more axes of a Frame.
IntraMap Java interface to the AST IntraMap class - map points using a private transformation function.
KeyMap Java interface to the AST KeyMap class - store a set of key/value pairs.
LutMap Java interface to the AST LutMap class - transform 1-dimensional coordinates using a lookup table.
Mapping Java interface to the AST Mapping class - inter-relate two coordinate systems.
Mapping.Interpolator Controls the interpolation scheme used by Mapping's resampling methods.
Mapping.Spreader Controls the spreading scheme used by Mapping's rebinning methods.
MathMap Java interface to the AST MathMap class - transform coordinates using mathematical expressions.
MatrixMap Java interface to the AST MatrixMap class - map coordinates by multiplying by a matrix.
NullRegion Java interface to the AST NullRegion class - a boundless region within a Frame.
PcdMap Java interface to the AST PcdMap class - apply 2-dimensional pincushion/barrel distortion.
PermMap Java interface to the AST PermMap class - coordinate permutation Mapping.
Plot Java interface to the AST Plot class - provide facilities for 2D graphical output.
PointList Java interface to the AST PointList class - a collection of points in a Frame.
Polygon Java interface to the AST Polygon class - a polygonal region within a 2-dimensional Frame.
PolyMap Java interface to the AST PolyMap class - map coordinates using polynomial functions.
Prism Java interface to the AST Prism class - an extrusion of a region into higher dimensions.
RateMap Java interface to the AST RateMap class - mapping which represents differentiation.
Region Java interface to the AST Region class - represents a region within a coordinate system.
ResampleFlags Aggregates flags which influence how Mapping.resample* methods operate.
SelectorMap Java interface to the AST SelectorMap class - a Mapping that locates positions within one of a set of alternate Regions.
ShiftMap Java interface to the AST ShiftMap class - add a constant value to each coordinate.
SkyAxis Java interface to the AST SkyAxis class.
SkyFrame Java interface to the AST SkyFrame class - celestial coordinate system description.
SlaMap Java interface to the AST SlaMap class - sequence of celestial coordinate conversions.
SpecFluxFrame Java interface to the AST SpecFluxFrame class - compound spectrum/flux Frame.
SpecFrame Java interface to the AST SpecFrame class - spectral coordinate system description.
SpecMap Java interface to the AST SpecMap class - sequence of spectral coordinate conversions.
SphMap Java interface to the AST SphMap class - map 3-d Cartesian to 2-d spherical coordinates.
Stc Java interface to the AST Stc class - represents an instance of the IVOA STC class.
StcCatalogEntryLocation Java interface to the AST StcCatalogEntryLocation class - correspond to the IVOA STCCatalogEntryLocation class.
StcObsDataLocation Java interface to the AST StcObsDataLocation class - correspond to the IVOA ObsDataLocation class.
StcResourceProfile Java interface to the AST StcResourceProfile class - correspond to the IVOA STCResourceProfile class.
StcSearchLocation Java interface to the AST StcSearchLocation class - correspond to the IVOA SearchLocation class.
SwitchMap Java interface to the AST SwitchMap class - a Mapping that encapsulates a set of alternate Mappings.
TimeFrame Java interface to the AST TimeFrame class - time coordinate system description.
TimeMap Java interface to the AST TimeMap class - sequence of time coordinate conversions.
TranMap Java interface to the AST TranMap class - mapping with specified forward and inverse transformations.
Transformer Defines a custom general coordinate transformation function.
Transformer1 Defines a custom one-dimensional coordinate transformation function.
Transformer2 Defines a custom two-dimensional coordinate transformation function.
UinterpCalculator Abstract class for user-provided general interpolation functions.
UnitMap Java interface to the AST UnitMap class - unit (null) Mapping.
WcsMap Java interface to the AST WcsMap class - implement a FITS-WCS sky projection.
WinMap Java interface to the AST WinMap class - map one window on to another by scaling and shifting each axis.
XmlChan Java interface to the AST XmlChan class - I/O Channel using XML to represent Objects.
ZoomMap Java interface to the AST ZoomMap class - zoom coordinates about the origin.
 

Exception Summary
AstException Thrown to indicate that there has been an AST error of some description.
 

Package uk.ac.starlink.ast Description

Provides an interface to the Starlink AST library.

AST library vs. uk.ac.starlink.ast package

The classes and methods here provide, via classes comprising native code which calls the underlying AST library, a complete interface to AST V1.8-3. The following sections discuss differences between the AST library and this interface to it.

Class hierarchy

The class hierarchy of the AST library is exactly replicated in this package, though this package contains some additional classes and interfaces used in the implementation which are not subclasses of AstObject. The classes are named the same, but without the 'Ast' prefix, except for AstObject, as a convenience to prevent a clash with java.lang.Object (should the same apply to Frame to prevent a clash with java.awt.Frame?)

Methods

The methods are named the same as in the AST library except without the 'Ast' prefix. In almost all classes there is a one-to-one correspondence between AST functions and methods in this package (though see the list below for omissions). In a few cases extra methods are provided here as conveniences. In particular, specific getter/setter methods are provided for each attribute of AstObject and all its subclasses. The generic set and set<type> methods may be used to set attributes, but using the specific methods provides better type safety.

Method arguments

Method arguments broadly follow their specifications in the AST library, but there are differences: Thus for instance:
   void astTran1( AstMapping *this, int npoint, const double xin[], 
                  int forward, double xout[] )
becomes
   public double[] tran1( int npoint, double[] xin, boolean forward )
(this is implicit, forward is of type boolean rather than int, and xout is the return value rather than a pre-allocated array into which the result can be written), and
   int astGQch( float *chv, float *chh )
becomes
   public float[] qch() throws Exception
(failure is indicated by throwing an Exception rather than by a zero return value, and the result is a returned array consisting of the two calculated values, rather than writing new values into locations pointed to by the arguments).

It is therefore recommended that programming is done with reference to the documentation of this package rather than of SUN/211. However, because of the strict type-checking of java compilers, it is unlikely that misconceptions about method signatures arising from familiarity with the C or Fortran versions of AST will result in compilable but incorrect code.

Where an array argument needs to be of a certain length the native code checks that it is at least of that length. If it is not, an exception is thrown to that effect. However, supplying an array which is longer than required in such cases is not regarded as an error.

Symbolic constants

Relevant AST symbolic constants are made available by public static final fields of the same name in the class to which they are relevant. These are guaranteed to have the same value as their AST library counterparts (the implementation obtains them at runtime using the definitions in the "ast.h" header file). Access is also available by name using the AstObject's getAstConstant<type> methods, though this is intended mainly for use within this package, and somewhat deprecated for user code. Thus the FrameSet class contains the declaration:
   public static final int AST__CURRENT = getAstCurrentI( "AST__CURRENT" );

API documentation

API Documentation has largely been generated by extracting comments wholesale from the AST source code and turning it into doc comments, which have then been processed by javadoc in the usual way. Although comments about a given argument ought to apply to the the correct argument, some of the language will be incorrect (e.g. 'pointer' where it should say 'reference'), and some comments will be irrelevant or possibly misleading. In the future, some (actually, quite a lot of) work will be required if the comments are to read like they were written for java.

Error conditions

Errors are handled in a robust way using Exceptions. If any call in the underlying AST library sets the AST Status to a non-zero value, this will be indicated to the calling java code by the throwing of an AstException. AstException provides a getStatus method (and defines the corresponding status values) so that the exact nature of the error which caused the trouble can be determined if desired. In a few cases, the java or native code will throw an AstException not generated by the AST library too; in this case the status will have the value AstException.SAI__ERROR. AstException extends RuntimeException, so that declaring and catching such throwables is not enforced by the compiler. Efforts have been made to ensure that Exceptions will be thrown in all cases rather than causing a JVM crash, but the JNI is a bit tricky in some circumstances, and there may be cases I haven't thought of. Please report JVM crashes (which will almost certainly be a result of JNI code in this package rather than an error in the JVM as they tend to report).

Synchronization

All calls to the underlying AST library itself (though not to the various methods of the classes which form this package) are effectively synchronized - a lock is obtained on an object maintained by the JNI code for this purpose. This implementation detail is required so that AST calls from different threads do not interfere with each other, by overwriting one or two C globals. In most cases this should not be noticeable, but it may have response time implications for multithreaded applications which invoke the the few time-consuming AST calls such as the resample<type> methods of Mapping.

Unimplemented functions

Here is a list of the AST functions which are not implemented because they are not appropriate in a Java context in one way or another:
astBegin, astEnd, astExempt, astExport
Objects are garbage collected in the usual way when references expire
astClearStatus, astSetStatus, astStatus, astWatch, astOK
Status handling is managed by throwing an AstException when an error occurs in native AST code
astIsA<Class>
Use instanceof instead - the class hierarchy in this package is identical to that of AST (for the classes which appear in AST)
astGrfPop, astGrfPush
The setGrf and getGrf methods of Plots provide this functionality.

Tolerance of absent native code

Being substantially an interface to native code, this package breaks java's platform independence. Client code may wish to invoke the package in such a way that it can tolerate being used on a platform where the native code (shared library) is not available. Of course the JNIAST functionality will be lost, but if that is not a fundamental part of the client code's functionality, it may be better to do this than to throw a fatal error. This can make it possible to run (albeit with reduced functionality) on a wider range of platforms than would otherwise be possible.

To do this, code can use the AstPackage.isAvailable() method, which indicates whether the requisite native code is available for use. If it is, then AST processing can take place as usual, but if not then as long as code avoids attempting to create or dereference any instance of AstObject or its subclasses it should run without errors (I think). Attempting to create or dereference an AstObject when AstPackage.isAvailable returns false will normally result in a LinkageError of some sort.

Package status

This package is a temporary measure; in due course it will be superceded by the pure java WCS package. WCS is being actively worked on now (mid 2002), but the timescale for completion is uncertain.



Copyright © 2017 Central Laboratory of the Research Councils. All Rights Reserved.