uk.ac.starlink.ndx

Interface Ndx

All Known Subinterfaces:

MutableNdx

All Known Implementing Classes:

BridgeNdx, DefaultMutableNdx

public interface Ndx

N-dimensional astronomical data. An Ndx represents an N-dimensional hypercuboid of pixels (the image data), plus associated auxiliary information, in particular an optional array of pixel variances, and of pixel quality flags. Metadata such as history information and coordinate system information may also be included, as well as user-defined extension data of unrestricted scope, represented in XML.

Version:

$Id$

Author:

Norman Gray, Mark Taylor, Peter W. Draper.

Method Summary

Modifier and Type	Method and Description
FrameSet	getAst() Get the world coordinate system of the NDX as an AST FrameSet.
int	getBadBits() Gets the value of the badBits mask.
Source	getEtc() Returns the XML containing extension information for this NDX.
HdxFacade	getHdxFacade() Obtains a HdxFacade, which enables us to examine and manipulate the Ndx in a DOM-like way.
NDArray	getImage() Returns the image component of this NDX.
String	getLabel() Returns the label string for this Ndx.
NDArray	getQuality() Returns the quality component of this NDX.
String	getTitle() Returns the title of this Ndx.
String	getUnits() Returns the units string for this Ndx.
NDArray	getVariance() Returns the variance component of this NDX.
boolean	hasEtc() Find out if the NDX contains user-defined extension information.
boolean	hasLabel() Indicates whether there is a label component.
boolean	hasQuality() Indicates whether there is a quality component.
boolean	hasTitle() Indicates whether there is a title component.
boolean	hasUnits() Indicates whether there is a units component.
boolean	hasVariance() Indicates whether there is a variance component.
boolean	hasWCS() Find out if the NDX has World Coordinate System information.
boolean	isPersistent() Indicates whether this Ndx represents a persistent object.
Source	toXML(URL base) Deprecated. replaced by getHdxFacade().getSource(base)

Method Detail

getImage

NDArray getImage()

Returns the image component of this NDX.

Note that this returns the raw image NDArray object, which should not in general be used directly for reading image data, since it has not been masked by a quality component if present. To obtain a properly masked version of the image data for read access, use the Ndxs.getMaskedImage(Ndx) method.

Returns:

the NDArray representing the image component

hasVariance

boolean hasVariance()

Indicates whether there is a variance component.

Returns:

true if getVariance() may be called

getVariance

NDArray getVariance()

Returns the variance component of this NDX.

Note that this returns the raw variance NDArray object, which should not in general be used directly for reading variance data, since it has not been masked by a quality component if present. To obtain a properly masked version of the variance data for read access, use the Ndxs.getMaskedVariance(Ndx) method.

May only be called if hasVariance() returns true.

Returns:

an NDArray representing the variance component,

Throws:

UnsupportedOperationException - if hasVariance returns false

hasQuality

boolean hasQuality()

Indicates whether there is a quality component.

Returns:

true if getQuality() may be called

getQuality

NDArray getQuality()

Returns the quality component of this NDX.

May only be called if hasQuality() returns true.

Returns:

an NDArray of integer type representing the quality component,

Throws:

UnsupportedOperationException - if hasQuality returns false

hasTitle

boolean hasTitle()

Indicates whether there is a title component.

Returns:

true if getTitle() may be called

getTitle

String getTitle()

Returns the title of this Ndx. May only be called if hasTitle() returns true.

Returns:

the title

Throws:

UnsupportedOperationException - if hasTitle returns false

hasLabel

boolean hasLabel()

Indicates whether there is a label component.

Returns:

true if getLabel() may be called

getLabel

String getLabel()

Returns the label string for this Ndx. This describes the quantity held in the data array. May only be called if hasLabel() returns true.

Returns:

the label string

Throws:

UnsupportedOperationException - if hasLabel returns false

hasUnits

boolean hasUnits()

Indicates whether there is a units component.

Returns:

true if getUnits() may be called

getUnits

String getUnits()

Returns the units string for this Ndx. This indicates the units of the values in the data array. May only be called if hasUnits() returns true.

Returns:

the units string

Throws:

UnsupportedOperationException - if hasUnits returns false

hasEtc

boolean hasEtc()

Find out if the NDX contains user-defined extension information.

Returns:

true if getEtc() may be called

getEtc

Source getEtc()

Returns the XML containing extension information for this NDX. The base element of the returned Source is an element of type <etc> which contains an element for each extension. May only be called if hasEtc() returns true.

Returns:

an XML Source containing any user-defined extension information.

Throws:

UnsupportedOperationException - if hasEtc returns false

See Also:

SourceReader

hasWCS

boolean hasWCS()

Find out if the NDX has World Coordinate System information.

If it exists, then the getAst() method may be called to access it as an AST FrameSet.

Note: in due course, when the uk.ac.starlink.wcs package has been released a getWCS method will be provided to access it as a WCS object.

Returns:

true if getAst() (and in due course getWCS can be called

getAst

FrameSet getAst()

Get the world coordinate system of the NDX as an AST FrameSet.

Note: This method is intended as a temporary measure until the uk.ac.starlink.wcs package has been released. At that time a getWCS method will be provided, and this one will be deprecated.

Returns:

the AST FrameSet representing the world coordinate system information

Throws:

UnsupportedOperationException - if hasWCS returns false

See Also:

hasWCS()

getBadBits

int getBadBits()

Gets the value of the badBits mask. This value is used in conjunction with the quality array to determine which pixels are bad; a pixel is bad if the logical AND of its quality value and the bad bits mask is not zero; hence a value of zero has no effect. Has no effect if there is no quality array.

Returns:

the bad bits mask

isPersistent

boolean isPersistent()

Indicates whether this Ndx represents a persistent object. If this returns true, then the array components in the XML source generated by the toXML(java.net.URL) method all contain URLs referencing genuine resources. If false, then this Ndx is in some sense virtual, and one or more of the array elements in the the XML generated by toXML will reference phantom resources.

Returns:

true if an XML representation capable of containing the full state of this Ndx can be generated

toXML

Source toXML(URL base)

Deprecated. replaced by getHdxFacade().getSource(base)

Generates an XML view of this Ndx object as a Source. Note that the array components (image, variance, quality) of this Ndx will only be recoverable from the returned XML in the case that the isPersistent() method returns true.

The XML in general may contain URLs, for instance referencing the array components of the NDX. How these are written is determined by the base parameter; URLs will be written as relative URLs relative to base if this is possible (e.g. if they share a part of their path). If there is no common part of the path, including the case in which base is null, then an absolute reference will be written.

Does not currently throw HdxException if the XML cannot be generated, but it should.

Parameters:

base - the base URL against which URLs written within the XML are considered relative. If null, all are written absolute.

Returns:

an XML Source representation of this Ndx

See Also:

SourceReader

getHdxFacade

HdxFacade getHdxFacade()

Obtains a HdxFacade, which enables us to examine and manipulate the Ndx in a DOM-like way.

Returns:

a HdxFacade representing the Ndx