Package org.apache.commons.imaging.formats.tiff

# Class AbstractTiffRasterData

java.lang.Object
org.apache.commons.imaging.formats.tiff.AbstractTiffRasterData

Direct Known Subclasses:
  `TiffRasterDataFloat`, `TiffRasterDataInt`

public abstract class AbstractTiffRasterData extends Object
Provides a simple container for numeric-raster data. Some TIFF files are used to store floating-point or integer data rather than images. This class is intended to support access to those TIFF files.

Note: The getData() and getIntData() methods can return direct references to the internal arrays stored in instances of this class. Because these are not safe copies of the data, an application that modified the arrays returned by these methods will change the content of the associated instance. This approach is used for purposes of efficiency when dealing with very large TIFF images.

Data layout: The elements in the returned array are stored in row-major order. In cases where the data contains multiple samples per raster cell (pixel), the data is organized into blocks of data one sample at a time. The first block contains width*height values for the first sample for each cell, the second block contains width*height values for the second sample for each cell, etc. Thus, the array index for a particular value is computed as

     index = y * width + x + iSample * width * height;

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `protected final int`
  `height`
  `protected final int`
  `nCells`
  `protected final int`
  `planarOffset`
  `protected final int`
  `samplesPerPixel`
  `protected final int`
  `width`

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `AbstractTiffRasterData(int width, int height, int samplesPerPixel)`
  Constructs an instance allocating memory for the specified dimensions.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `protected final int`
  `checkCoordinatesAndComputeIndex(int x, int y, int i)`
  `abstract float[]`
  `getData()`
  Returns the content stored as an array in this instance.
  `abstract TiffRasterDataType`
  `getDataType()`
  Gets the raster data type from the instance.
  `final int`
  `getHeight()`
  Gets the height (number of rows) of the raster.
  `abstract int[]`
  `getIntData()`
  Returns the content stored as an array in this instance.
  `abstract int`
  `getIntValue(int x, int y)`
  Gets the value stored at the specified raster coordinates.
  `abstract int`
  `getIntValue(int x, int y, int i)`
  Gets the value stored at the specified raster coordinates.
  `final int`
  `getSamplesPerPixel()`
  Gets the number of samples per pixel.
  `abstract TiffRasterStatistics`
  `getSimpleStatistics()`
  Tabulates simple statistics for the raster and returns an instance containing general metadata.
  `abstract TiffRasterStatistics`
  `getSimpleStatistics(float valueToExclude)`
  Tabulates simple statistics for the raster excluding the specified value and returns an instance containing general metadata.
  `abstract float`
  `getValue(int x, int y)`
  Gets the value stored at the specified raster coordinates.
  `abstract float`
  `getValue(int x, int y, int i)`
  Gets the value stored at the specified raster coordinates.
  `final int`
  `getWidth()`
  Gets the width (number of columns) of the raster.
  `abstract void`
  `setIntValue(int x, int y, int value)`
  Sets the value stored at the specified raster coordinates.
  `abstract void`
  `setIntValue(int x, int y, int i, int value)`
  Sets the value stored at the specified raster coordinates.
  `abstract void`
  `setValue(int x, int y, float value)`
  Sets the value stored at the specified raster coordinates.
  `abstract void`
  `setValue(int x, int y, int i, float value)`
  Sets the value stored at the specified raster coordinates.

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

  `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- ## Field Details

  - ### width

    protected final int width

  - ### height

    protected final int height

  - ### samplesPerPixel

    protected final int samplesPerPixel

  - ### nCells

    protected final int nCells

  - ### planarOffset

    protected final int planarOffset

- ## Constructor Details

  - ### AbstractTiffRasterData

    public AbstractTiffRasterData(int width, int height, int samplesPerPixel)
    Constructs an instance allocating memory for the specified dimensions.
    Parameters:
      `width` - a value of 1 or greater
      `height` - a value of 1 or greater
      `samplesPerPixel` - a value of 1 or greater

- ## Method Details

  - ### checkCoordinatesAndComputeIndex

    protected final int checkCoordinatesAndComputeIndex(int x, int y, int i)

  - ### getData

    public abstract float[] getData()
    Returns the content stored as an array in this instance. Note that in many cases, the returned array is not a safe copy of the data but a direct reference to the member element. In such cases, modifying it would directly affect the content of the instance. While this design approach carries some risk in terms of data security, it was chosen for reasons of performance and memory conservation. TIFF images that contain floating-point data are often quite large. Sizes of 100 million raster cells are common. Making a redundant copy of such a large in-memory object might exceed the resources available to a Java application.

    See the class API documentation above for notes on accessing array elements.

    Returns:
      the data content stored in this instance.

  - ### getDataType

    public abstract TiffRasterDataType getDataType()
    Gets the raster data type from the instance.
    Returns:
      a valid enumeration value.

  - ### getHeight

    public final int getHeight()
    Gets the height (number of rows) of the raster.
    Returns:
      the height of the raster.

  - ### getIntData

    public abstract int[] getIntData()
    Returns the content stored as an array in this instance. Note that in many cases, the returned array is not a safe copy of the data but a direct reference to the member element. In such cases, modifying it would directly affect the content of the instance. While this design approach carries some risk in terms of data security, it was chosen for reasons of performance and memory conservation. TIFF images that contain floating-point data are often quite large. Sizes of 100 million raster cells are common. Making a redundant copy of such a large in-memory object might exceed the resources available to a Java application.

    See the class API documentation above for notes on accessing array elements.

    Returns:
      the data content stored in this instance.

  - ### getIntValue

    public abstract int getIntValue(int x, int y)
    Gets the value stored at the specified raster coordinates.
    Parameters:
      `x` - integer coordinate in the columnar direction
      `y` - integer coordinate in the row direction
    Returns:
      the value stored at the specified location

  - ### getIntValue

    public abstract int getIntValue(int x, int y, int i)
    Gets the value stored at the specified raster coordinates.
    Parameters:
      `x` - integer coordinate in the columnar direction
      `y` - integer coordinate in the row direction
      `i` - integer sample index (for data sets giving multiple samples per raster cell).
    Returns:
      the value stored at the specified location

  - ### getSamplesPerPixel

    public final int getSamplesPerPixel()
    Gets the number of samples per pixel.
    Returns:
      a value of 1 or greater.

  - ### getSimpleStatistics

    public abstract TiffRasterStatistics getSimpleStatistics()
    Tabulates simple statistics for the raster and returns an instance containing general metadata.
    Returns:
      a valid instance containing a safe copy of the current simple statistics for the raster.

  - ### getSimpleStatistics

    public abstract TiffRasterStatistics getSimpleStatistics(float valueToExclude)
    Tabulates simple statistics for the raster excluding the specified value and returns an instance containing general metadata.
    Parameters:
      `valueToExclude` - exclude samples with this specified value.
    Returns:
      a valid instance.

  - ### getValue

    public abstract float getValue(int x, int y)
    Gets the value stored at the specified raster coordinates.
    Parameters:
      `x` - integer coordinate in the columnar direction
      `y` - integer coordinate in the row direction
    Returns:
      the value stored at the specified location; potentially a Float.NaN.

  - ### getValue

    public abstract float getValue(int x, int y, int i)
    Gets the value stored at the specified raster coordinates.
    Parameters:
      `x` - integer coordinate in the columnar direction
      `y` - integer coordinate in the row direction
      `i` - integer sample index
    Returns:
      the value stored at the specified location; potentially a Float.NaN.

  - ### getWidth

    public final int getWidth()
    Gets the width (number of columns) of the raster.
    Returns:
      the width of the raster

  - ### setIntValue

    public abstract void setIntValue(int x, int y, int value)
    Sets the value stored at the specified raster coordinates.
    Parameters:
      `x` - integer coordinate in the columnar direction
      `y` - integer coordinate in the row direction
      `value` - the value to be stored at the specified location.

  - ### setIntValue

    public abstract void setIntValue(int x, int y, int i, int value)
    Sets the value stored at the specified raster coordinates.
    Parameters:
      `x` - integer coordinate in the columnar direction
      `y` - integer coordinate in the row direction
      `i` - integer sample index (for data sets giving multiple samples per raster cell).
      `value` - the value to be stored at the specified location.

  - ### setValue

    public abstract void setValue(int x, int y, float value)
    Sets the value stored at the specified raster coordinates.
    Parameters:
      `x` - integer coordinate in the columnar direction
      `y` - integer coordinate in the row direction
      `value` - the value to be stored at the specified location; potentially a Float.NaN.

  - ### setValue

    public abstract void setValue(int x, int y, int i, float value)
    Sets the value stored at the specified raster coordinates.
    Parameters:
      `x` - integer coordinate in the columnar direction
      `y` - integer coordinate in the row direction
      `i` - integer sample index (for data sets giving multiple samples per raster cell).
      `value` - the value to be stored at the specified location; potentially a Float.NaN.