Module org.hdfgroup.object
Package hdf.object

# Class ScalarDS

Object
hdf.object.HObject
hdf.object.Dataset
hdf.object.ScalarDS

All Implemented Interfaces:
  `DataFormat`, `MetaDataContainer`, `Serializable`

Direct Known Subclasses:
  `FitsDataset`, `H4GRImage`, `H4SDS`, `H5ScalarDS`, `NC2Dataset`

public abstract class ScalarDS extends Dataset
A scalar dataset is a multiple dimension array of scalar points. The Datatype of a scalar dataset must be an atomic datatype. Common datatypes of scalar datasets include char, byte, short, int, long, float, double and string.

A ScalarDS can be an image or spreadsheet data. ScalarDS defines methods to deal with both images and spreadsheets.

ScalarDS is an abstract class. Current implementing classes are the H4SDS, H5GRImage and H5ScalarDS.

Version:
  1.1 9/4/2007
Author:
  Peter X. Cao
See Also:
  Serialized Form

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `protected Object`
  `fillValue`
  The fill value of the dataset.
  `protected double[]`
  `imageDataRange`
  The min-max range of image data values.
  `protected int`
  `interlace`
  The interlace mode of the stored raster image data.
  `static int`
  `INTERLACE_LINE`
  Indicates that each pixel component of RGB is stored as a scan line.
  `static int`
  `INTERLACE_PIXEL`
  Indicates that the pixel RGB values are contiguous.
  `static int`
  `INTERLACE_PLANE`
  Indicates that each pixel component of RGB is stored as a plane.
  `protected boolean`
  `isDefaultImageOrder`
  Flag to indicate if the dataset is displayed as an image with default order of dimensions.
  `boolean`
  `isFillValueConverted`
  Flag to indicate if the FillValue is converted from unsigned C.
  `protected boolean`
  `isImage`
  True if this dataset is an image.
  `protected boolean`
  `isImageDisplay`
  Flag to indicate if the dataset is displayed as an image.
  `protected boolean`
  `isText`
  True if this dataset is ASCII text.
  `protected boolean`
  `isTrueColor`
  True if this dataset is a true color image.
  `protected byte[][]`
  `palette`
  The indexed RGB color model with 256 colors.
  `protected boolean`
  `unsignedConverted`
  Flag to indicate is the original unsigned C data is converted.

  ### Fields inherited from class hdf.object.Dataset

  `chunkSize, compression, COMPRESSION_GZIP_TXT, convertByteToString, convertedBuf, data, datatype, dimNames, dims, filters, inited, isDataLoaded, maxDims, nPoints, originalBuf, rank, selectedDims, selectedIndex, selectedStride, startDims, storage, storageLayout`

  ### Fields inherited from class hdf.object.HObject

  `fileFormat, linkTargetObjName, oid, SEPARATOR`

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `ScalarDS​(FileFormat theFile, String theName, String thePath)`
  Constructs an instance of a ScalarDS with specific name and path.
  `ScalarDS​(FileFormat theFile, String theName, String thePath, long[] oid)`
  Deprecated.
  Not for public use in the future.
  Using `ScalarDS(FileFormat, String, String)`

- ## Method Summary

  Modifier and Type
  Method
  Description
  `void`
  `addFilteredImageValue​(Number x)`
  Add a value that will be filtered out in an image.
  `void`
  `clearData()`
  Clears the current data buffer in memory and forces the next read() to load the data from file.
  `Object`
  `convertFromUnsignedC()`
  Converts the data values of this dataset to appropriate Java integer if they are unsigned integers.
  `Object`
  `convertToUnsignedC()`
  Converts Java integer data of this dataset back to unsigned C-type integer data if they are unsigned integers.
  `Object`
  `getFillValue()`
  Returns the fill values for the dataset.
  `List<Number>`
  `getFilteredImageValues()`
  Get a list of values that will be filtered out in an image.
  `double[]`
  `getImageDataRange()`
  Returns the (min, max) pair of image data range.
  `int`
  `getInterlace()`
  Returns the interlace mode of a true color image (RGB).
  `abstract byte[][]`
  `getPalette()`
  Returns the palette of this scalar dataset or null if palette does not exist.
  `String`
  `getPaletteName​(int idx)`
  Get the name of a specific image palette from file.
  `abstract byte[]`
  `getPaletteRefs()`
  Returns the byte array of palette refs.
  `boolean`
  `isDefaultImageOrder()`
  Returns true if this dataset is displayed as an image with default image order.
  `boolean`
  `isImage()`
  Returns true if this dataset is an image.
  `boolean`
  `isImageDisplay()`
  Returns true if this dataset is displayed as an image.
  `boolean`
  `isTrueColor()`
  `abstract byte[][]`
  `readPalette​(int idx)`
  Reads a specific image palette from file.
  `void`
  `setImageDataRange​(double min, double max)`
  Sets data range for an image.
  `void`
  `setIsImage​(boolean b)`
  Sets the flag to indicate this dataset is an image.
  `void`
  `setIsImageDisplay​(boolean b)`
  Sets the flag to display the dataset as an image.
  `void`
  `setPalette​(byte[][] pal)`
  Sets the palette for this dataset.

  ### Methods inherited from class hdf.object.Dataset

  `byteToString, clear, convertFromUnsignedC, convertFromUnsignedC, convertToUnsignedC, convertToUnsignedC, copy, getChunkSize, getCompression, getConvertByteToString, getData, getDatatype, getDimNames, getDims, getFilters, getHeight, getMaxDims, getOriginalClass, getRank, getSelectedDims, getSelectedIndex, getSize, getStartDims, getStorage, getStorageLayout, getStride, getVirtualFilename, getVirtualMaps, getWidth, isInited, isString, isVirtual, readBytes, setConvertByteToString, setData, stringToByte, write`

  ### Methods inherited from class hdf.object.HObject

  `close, createFullname, debug, equals, equals, equalsOID, getFID, getFile, getFileFormat, getFullName, getLinkTargetObjName, getName, getOID, getPath, hashCode, open, setFullname, setLinkTargetObjName, setName, setPath, toString`

  ### Methods inherited from class java.lang.Object

  `clone, finalize, getClass, notify, notifyAll, wait, wait, wait`

  ### Methods inherited from interface hdf.object.DataFormat

  `init, read, write`

  ### Methods inherited from interface hdf.object.MetaDataContainer

  `getMetadata, hasAttribute, removeMetadata, updateMetadata, writeMetadata`

- ## Field Details

  - ### INTERLACE_PIXEL

    public static final int INTERLACE_PIXEL
    Indicates that the pixel RGB values are contiguous.
    See Also:
      Constant Field Values

  - ### INTERLACE_LINE

    public static final int INTERLACE_LINE
    Indicates that each pixel component of RGB is stored as a scan line.
    See Also:
      Constant Field Values

  - ### INTERLACE_PLANE

    public static final int INTERLACE_PLANE
    Indicates that each pixel component of RGB is stored as a plane.
    See Also:
      Constant Field Values

  - ### interlace

    protected int interlace
    The interlace mode of the stored raster image data. Valid values are INTERLACE_PIXEL, INTERLACE_LINE and INTERLACE_PLANE.

  - ### imageDataRange

    protected double[] imageDataRange
    The min-max range of image data values. For example, [0, 255] indicates the min is 0, and the max is 255.

  - ### palette

    protected byte[][] palette
    The indexed RGB color model with 256 colors.

    The palette values are stored in a two-dimensional byte array and arrange by color components of red, green and blue. palette[][] = byte[3][256], where, palette[0][], palette[1][] and palette[2][] are the red, green and blue components respectively.

  - ### isImage

    protected boolean isImage
    True if this dataset is an image.

  - ### isTrueColor

    protected boolean isTrueColor
    True if this dataset is a true color image.

  - ### isText

    protected boolean isText
    True if this dataset is ASCII text.

  - ### unsignedConverted

    protected boolean unsignedConverted
    Flag to indicate is the original unsigned C data is converted.

  - ### fillValue

    protected Object fillValue
    The fill value of the dataset.

  - ### isImageDisplay

    protected boolean isImageDisplay
    Flag to indicate if the dataset is displayed as an image.

  - ### isDefaultImageOrder

    protected boolean isDefaultImageOrder
    Flag to indicate if the dataset is displayed as an image with default order of dimensions.

  - ### isFillValueConverted

    public boolean isFillValueConverted
    Flag to indicate if the FillValue is converted from unsigned C.

- ## Constructor Details

  - ### ScalarDS

    public ScalarDS​(FileFormat theFile, String theName, String thePath)
    Constructs an instance of a ScalarDS with specific name and path. An HDF data object must have a name. The path is the group path starting from the root.

    For example, in H5ScalarDS(h5file, "dset", "/arrays/"), "dset" is the name of the dataset, "/arrays" is the group path of the dataset.

    Parameters:
      `theFile` - the file that contains the data object.
      `theName` - the name of the data object, e.g. "dset".
      `thePath` - the full path of the data object, e.g. "/arrays/".

  - ### ScalarDS

    @Deprecated public ScalarDS​(FileFormat theFile, String theName, String thePath, long[] oid)
    Deprecated.
    Not for public use in the future.
    Using `ScalarDS(FileFormat, String, String)`
    Parameters:
      `theFile` - the file that contains the data object.
      `theName` - the name of the data object, e.g. "dset".
      `thePath` - the full path of the data object, e.g. "/arrays/".
      `oid` - the v of the data object.

- ## Method Details

  - ### clearData

    public void clearData()
    Description copied from class: `Dataset`
    Clears the current data buffer in memory and forces the next read() to load the data from file.

    The function read() loads data from file into memory only if the data is not read. If data is already in memory, read() just returns the memory buffer. Sometimes we want to force read() to re-read data from file. For example, when the selection is changed, we need to re-read the data.

    Specified by:
      `clearData` in interface `DataFormat`
    Overrides:
      `clearData` in class `Dataset`
    See Also:
      `Dataset.getData()`, `DataFormat.read()`

  - ### convertFromUnsignedC

    public Object convertFromUnsignedC()
    Converts the data values of this dataset to appropriate Java integer if they are unsigned integers.
    Returns:
      the converted data buffer.
    See Also:
      `Dataset.convertToUnsignedC(Object)`, `Dataset.convertFromUnsignedC(Object, Object)`

  - ### convertToUnsignedC

    public Object convertToUnsignedC()
    Converts Java integer data of this dataset back to unsigned C-type integer data if they are unsigned integers.
    Returns:
      the converted data buffer.
    See Also:
      `Dataset.convertToUnsignedC(Object)`, `Dataset.convertToUnsignedC(Object, Object)`, `Dataset.convertFromUnsignedC(Object data_in)`

  - ### getPalette

    public abstract byte[][] getPalette()
    Returns the palette of this scalar dataset or null if palette does not exist.

    A Scalar dataset can be displayed as spreadsheet data or an image. When a scalar dataset is displayed as an image, the palette or color table may be needed to translate a pixel value to color components (for example, red, green, and blue). Some scalar datasets have no palette and some datasets have one or more than one palettes. If an associated palette exists but is not loaded, this interface retrieves the palette from the file and returns the palette. If the palette is loaded, it returns the palette. It returns null if there is no palette associated with the dataset.

    Current implementation only supports palette model of indexed RGB with 256 colors. Other models such as YUV", "CMY", "CMYK", "YCbCr", "HSV will be supported in the future.

    The palette values are stored in a two-dimensional byte array and are arranges by color components of red, green and blue. palette[][] = byte[3][256], where, palette[0][], palette[1][] and palette[2][] are the red, green and blue components respectively.

    Sub-classes have to implement this interface. HDF4 and HDF5 images use different libraries to retrieve the associated palette.

    Returns:
      the 2D palette byte array.

  - ### setPalette

    public final void setPalette​(byte[][] pal)
    Sets the palette for this dataset.
    Parameters:
      `pal` - the 2D palette byte array.

  - ### readPalette

    public abstract byte[][] readPalette​(int idx)
    Reads a specific image palette from file.

    A scalar dataset may have multiple palettes attached to it. readPalette(int idx) returns a specific palette identified by its index.

    Parameters:
      `idx` - the index of the palette to read.
    Returns:
      the image palette

  - ### getPaletteName

    public String getPaletteName​(int idx)
    Get the name of a specific image palette from file.

    A scalar dataset may have multiple palettes attached to it. getPaletteName(int idx) returns the name of a specific palette identified by its index.

    Parameters:
      `idx` - the index of the palette to retrieve the name.
    Returns:
      The name of the palette

  - ### getPaletteRefs

    public abstract byte[] getPaletteRefs()
    Returns the byte array of palette refs.

    A palette reference is an object reference that points to the palette dataset.

    For example, Dataset "Iceberg" has an attribute of object reference "Palette". The arrtibute "Palette" has value "2538" that is the object reference of the palette data set "Iceberg Palette".

    Returns:
      null if there is no palette attribute attached to this dataset.

  - ### isImage

    public final boolean isImage()
    Returns true if this dataset is an image.

    For all Images, they must have an attribute called "CLASS". The value of this attribute is "IMAGE". For more details, read HDF5 Image and Palette Specification

    Returns:
      true if the dataset is an image; otherwise, returns false.

  - ### isImageDisplay

    public final boolean isImageDisplay()
    Returns true if this dataset is displayed as an image.

    A ScalarDS can be displayed as an image or a spreadsheet in a table.

    Returns:
      true if this dataset is displayed as an image; otherwise, returns false.

  - ### isDefaultImageOrder

    public final boolean isDefaultImageOrder()
    Returns true if this dataset is displayed as an image with default image order.

    A ScalarDS can be displayed as an image with different orders of dimensions.

    Returns:
      true if this dataset is displayed as an image with default image order; otherwise, returns false.

  - ### setIsImageDisplay

    public final void setIsImageDisplay​(boolean b)
    Sets the flag to display the dataset as an image.
    Parameters:
      `b` - if b is true, display the dataset as an image

  - ### setIsImage

    public final void setIsImage​(boolean b)
    Sets the flag to indicate this dataset is an image.
    Parameters:
      `b` - if b is true, the dataset is an image.

  - ### setImageDataRange

    public final void setImageDataRange​(double min, double max)
    Sets data range for an image.
    Parameters:
      `min` - the data range start.
      `max` - the data range end.

  - ### addFilteredImageValue

    public void addFilteredImageValue​(Number x)
    Add a value that will be filtered out in an image.
    Parameters:
      `x` - value to be filtered

  - ### getFilteredImageValues

    public List<Number> getFilteredImageValues()
    Get a list of values that will be filtered out in an image.
    Returns:
      the list of Image values

  - ### isTrueColor

    public final boolean isTrueColor()
    Returns:
      true if this dataset is a true color image.

  - ### getInterlace

    public final int getInterlace()
    Returns the interlace mode of a true color image (RGB). Valid values:

             INTERLACE_PIXEL -- RGB components are contiguous, i.e. rgb, rgb, rgb, ...
             INTERLACE_LINE -- each RGB component is stored as a scan line
             INTERLACE_PLANE -- each RGB component is stored as a plane

    Returns:
      the interlace mode of a true color image (RGB).

  - ### getImageDataRange

    public double[] getImageDataRange()
    Returns the (min, max) pair of image data range.
    Returns:
      the (min, max) pair of image data range.

  - ### getFillValue

    public final Object getFillValue()
    Returns the fill values for the dataset.
    Returns:
      the fill values for the dataset.