Class ImageData
- All Implemented Interfaces:
FitsElement
- Direct Known Subclasses:
NullData
,StreamingTileImageData
Image data. Essentially these data are a primitive multi-dimensional array, such as a double[]
,
float[][]
, or short[][][]
. Or, as of version 1.20, they may also be ComplexValue
types also.
Starting in version 0.9 of the FITS library, this class allows users to defer the reading of images if the FITS data
is being read from a file. An ImageTiler
object is supplied which can return an arbitrary subset of the image
as a one dimensional array -- suitable for manipulation by standard Java libraries. The image data may not be read
from the input until the user calls a method that requires the actual data (e.g. the Data.getData()
/
Data.getKernel()
, convertTo(Class)
or write(ArrayDataOutput)
methods).
- See Also:
-
Nested Class Summary
Nested ClassesModifier and TypeClassDescriptionprotected static class
This class describes an arrayprotected class
This inner class allows the ImageTiler to see if the user has read in the data. -
Field Summary
Fields inherited from class nom.tam.fits.Data
dataSize, fileOffset, input
-
Constructor Summary
Constructors -
Method Summary
Modifier and TypeMethodDescriptionConverts this image HDU to another image HDU of a different type, possibly using a qunatizer for the integer-decimal conversion of the data elements.protected void
fillHeader
(Header head) Describe the structure of this data object in the supplied header.static ImageData
Creates a new FITS image using the specified primitive numerical Java array containing data.protected Object
Returns the data content that is currently in memory.final int[]
Returns the dimensions of this image.final Quantizer
Returns the conversion between decimal and integer data representations.getTiler()
Returns the class that can be used to divide this image into tiles that may be processed separately (and in parallel).protected long
Returns the calculated byte size of the data, regardless of whether the data is currently in memory or not.final Class<?>
getType()
Returns the element type of this image in its current representation.final boolean
Checks if the image data is explicitly designated as a complex-valued image.protected void
Load data from the current position of the input into memory.static void
overrideHeaderAxes
(Header header, int... sizes) (for expert users) Overrides the image size description in the header to the specified Java array dimensions.protected ImageData.ArrayDesc
Returns the image specification based on its description in a FITS header.void
read
(ArrayDataInput in) Reads the data or skips over it for reading later, depending on whether reading from a stream or a random acessible input, respectively.void
Sets the buffer that may hold a serialized version of the data for this image.void
setQuantizer
(Quantizer quant) Sets the conversion between decimal and integer data representations.toHDU()
Returns an approprotae HDU object that encapsulates this FITS data, and contains the minimal mandatory header description for that data.void
Writes the contents of the element to a data sink, adding padding as necessary if the element (such as a header or data segment) is expected to complete the FITS block of 2880 bytes.Methods inherited from class nom.tam.fits.Data
calcChecksum, detach, ensureData, getData, getFileOffset, getKernel, getRandomAccessInput, getSize, isDeferred, isEmpty, reset, rewrite, rewriteable, setFileOffset
-
Constructor Details
-
ImageData
public ImageData()Create the equivalent of a null data element. -
ImageData
(for internal use) Create an array from a header description. This is typically how data will be created when reading FITS data from a file where the header is read first. This creates an empty array.- Parameters:
h
- header to be used as a template.- Throws:
FitsException
- if there was a problem with the header description.
-
ImageData
Create an ImageData object using the specified object to initialize the data array.- Parameters:
x
- The initial data array. This should be a primitive array but this is not checked currently.- Throws:
IllegalArgumentException
- if x is not a suitable primitive array
-
-
Method Details
-
loadData
Description copied from class:Data
Load data from the current position of the input into memory. This may be triggered immediately when calling
Data.read(ArrayDataInput)
if called on a non random accessible input, or else later when data is accessed viaData.ensureData()
, for example as a result of aData.getData()
call. This method will not be called unless there is actual data of non-zero size to be read.Implementations should create appropriate data structures and populate them from the specified input.
- Specified by:
loadData
in classData
- Parameters:
in
- The input from which to load data- Throws:
IOException
- if the data could not be loaded from the input.FitsException
- if the data is garbled.- See Also:
-
read
Description copied from class:Data
Reads the data or skips over it for reading later, depending on whether reading from a stream or a random acessible input, respectively.
In case the argument is a an instance of
RandomAccess
input (such as aFitsFile
, the call will simply note where in the file the data segment can be found for reading at a later point, only when the data content is accessed. This 'deferred' reading behavior make it possible to process large HDUs even with small amount of RAM, and can result in a significant performance boost when inspectring large FITS files, or using only select content from large FITS files.- Specified by:
read
in interfaceFitsElement
- Overrides:
read
in classData
- Parameters:
in
- The input data stream- Throws:
PaddingException
- if there is missing padding between the end of the data segment and the enf-of-file.FitsException
- if the data appears to be corrupted.- See Also:
-
getCurrentData
Description copied from class:Data
Returns the data content that is currently in memory. In case of a data object in deferred read state (that is its prescription has been parsed from the header, but no data content was loaded yet from a random accessible input), this call may returnnull
or an object representing empty data.- Specified by:
getCurrentData
in classData
- Returns:
- The current data content in memory.
- See Also:
-
getTiler
Returns the class that can be used to divide this image into tiles that may be processed separately (and in parallel).- Returns:
- image tiler for this image instance.
-
setBuffer
Sets the buffer that may hold a serialized version of the data for this image.- Parameters:
data
- the buffer that may hold this image's data in serialized form.
-
write
Description copied from interface:FitsElement
Writes the contents of the element to a data sink, adding padding as necessary if the element (such as a header or data segment) is expected to complete the FITS block of 2880 bytes.- Specified by:
write
in interfaceFitsElement
- Specified by:
write
in classData
- Parameters:
o
- The data sink.- Throws:
FitsException
- if the write was unsuccessful.
-
fillHeader
Description copied from class:Data
Describe the structure of this data object in the supplied header.- Specified by:
fillHeader
in classData
- Parameters:
head
- header to fill with the data from the current data object- Throws:
FitsException
- if the operation fails
-
getTrueSize
protected long getTrueSize()Description copied from class:Data
Returns the calculated byte size of the data, regardless of whether the data is currently in memory or not.- Specified by:
getTrueSize
in classData
- Returns:
- the calculated byte size for the data.
-
parseHeader
Returns the image specification based on its description in a FITS header.- Parameters:
h
- the FITS header that describes this image with the standard keywords for an image HDU.- Returns:
- an object that captures the description contained in the header for internal use.
- Throws:
FitsException
- If there was a problem accessing or interpreting the required header values.
-
overrideHeaderAxes
public static void overrideHeaderAxes(Header header, int... sizes) throws FitsException, IllegalArgumentException (for expert users) Overrides the image size description in the header to the specified Java array dimensions. Typically users should not call this method, unless they want to define the image dimensions in the absence of the actual complete image data. For example, to describe the dimensions when using low-level writes of an image row-by-row, without ever storing the entire image in memory.- Parameters:
header
- A FITS image headersizes
- The array dimensions in Java order (fastest varying index last)- Throws:
FitsException
- if the size has negative values, or the header is not that for an imageIllegalArgumentException
- should not actually happen- Since:
- 1.18
- See Also:
-
from
Creates a new FITS image using the specified primitive numerical Java array containing data.- Parameters:
data
- A regulatly shaped primitive numerical Java array, which can be multi-dimensional.- Returns:
- A new FITS image that encapsulates the specified array data.
- Throws:
IllegalArgumentException
- if the argument is not a primitive numerical Java array.- Since:
- 1.19
-
toHDU
Description copied from class:Data
Returns an approprotae HDU object that encapsulates this FITS data, and contains the minimal mandatory header description for that data.- Specified by:
toHDU
in classData
- Returns:
- a HDU object ocntaining the data and its minimal required header description
- Throws:
FitsException
- If the data cannot be converted to an HDU for some reason.
-
setQuantizer
Sets the conversion between decimal and integer data representations. The quantizer for the image is set automatically if the image was read from a FITS input, and if any of the associated BSCALE, BZERO, or BLANK keywords were defined in the HDU's header. User may use this methods to set a different quantization or to use no quantization at all when converting between floating-point and integer representations.- Parameters:
quant
- the quantizer that converts between floating-point and integer data representations, ornull
to not use quantization and instead rely on simple rounding for decimal-ineger conversions..- Since:
- 1.20
- See Also:
-
getQuantizer
Returns the conversion between decimal and integer data representations.- Returns:
- the quantizer that converts between floating-point and integer data representations, which may be
null
- Since:
- 1.20
- See Also:
-
getType
Returns the element type of this image in its current representation.- Returns:
- The element type of this image, such as
int.class
,double.class
orComplexValue
.class
. - Since:
- 1.20
- See Also:
-
getDimensions
public final int[] getDimensions()Returns the dimensions of this image.- Returns:
- An array containing the sizes along each data dimension, in Java indexing order. The returned array is not used internally, and therefore modifying it will not damage the integrity of the image data.
- Since:
- 1.20
- See Also:
-
isComplexValued
public final boolean isComplexValued()Checks if the image data is explicitly designated as a complex-valued image. An image may be designated as complex-valued either because it was created withComplexValue
type data, or because it was read from a FITS file in which one image axis of dimension 2 was designated as an axis containing complex-valued components with the corresponding CTYPEn header keyword set to 'COMPLEX'. The complex-valued deignation checked by this method is not the same asgetType()
, as it does not necesarily mean that the data itself is currently inComplexValue
type representation. Rather it simply means that this data can be represented asComplexValue
type, possibly after an appropriate conversion to aComplexValue
type.- Returns:
true
if the data is complex valued or has been explicitly designated as complex valued. Otherwisefalse
.- Since:
- 1.20
- See Also:
-
convertTo
Converts this image HDU to another image HDU of a different type, possibly using a qunatizer for the integer-decimal conversion of the data elements. In all other respects, the returned image is identical to the the original. If th conversion is th indetity, it will return itself and the data may remain in deferred mode.- Parameters:
type
- The primitive numerical type (e.g.int.class
ordouble.class
), or else aComplexValue
type in which data should be represented. Complex representations are normally available for data whose first or last CTYPEn axis was described as 'COMPLEX' by the FITS header with a dimensionality is 2 corresponfing to a pair of real and imaginary data elements. Even without the CTYPEn designation, it is always possible to convert to complex all arrays that have a trailing Java dimension (NAXIS1 in FITS) equal to 2.- Returns:
- An image HDU containing the same data in the chosen representation by another type. (It may be the same as this HDU if the type is unchanged from the original).
- Throws:
FitsException
- if the data cannot be read from the input.- Since:
- 1.20
- See Also:
-