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
 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


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