org.esa.snap.core.datamodel

Class Band

java.lang.Object

com.bc.ceres.core.ExtensibleObject

org.esa.snap.core.datamodel.ProductNode

org.esa.snap.core.datamodel.DataNode

org.esa.snap.core.datamodel.RasterDataNode

org.esa.snap.core.datamodel.AbstractBand

org.esa.snap.core.datamodel.Band

All Implemented Interfaces:

Extensible, Scaling, SceneTransformProvider

Direct Known Subclasses:

FilterBand, Mask, VirtualBand

public class Band
extends AbstractBand

A band contains the data for geophysical parameter in remote sensing data products. Bands are two-dimensional images which hold their pixel values (samples) in a buffer of the type ProductData. The band class is just a container for attached metadata of the band, currently:

• the flag coding FlagCoding
• the band index at which position the band is stored in the associated product
• the center wavelength of the band
• the bandwidth of the band
• the solar spectral flux of the band
• the width and height of the band

The band can contain a buffer to the real data, but this buffer must be read explicitely, to keep the memory fingerprint small, the data is not read automatically.

The several getPixel and readPixel methods of this class do not necessarily return the values contained in the data buffer of type ProductData. If the scalingFactor, scalingOffset or log10Scaled are set a conversion of the form scalingFactor * rawSample + scalingOffset is applied to the raw samples before the getPixel and @ readPixel methods return the actual pixel values. If the log10Scaled property is true then the conversion is pow(10, scalingFactor * rawSample + scalingOffset). The several setPixel and writePixel perform the inverse operations in this case.

Version:

$Revision$ $Date$

See Also:

ProductData

Nested Class Summary

Nested classes/interfaces inherited from class org.esa.snap.core.datamodel.RasterDataNode

RasterDataNode.RasterDataProcessor

Field Summary

Fields

Modifier and Type	Field and Description
static String	PROPERTY_NAME_SAMPLE_CODING
static String	PROPERTY_NAME_SOLAR_FLUX
static String	PROPERTY_NAME_SPECTRAL_BAND_INDEX
static String	PROPERTY_NAME_SPECTRAL_BANDWIDTH
static String	PROPERTY_NAME_SPECTRAL_WAVELENGTH

Fields inherited from class org.esa.snap.core.datamodel.RasterDataNode

INVALID_POS_TEXT, IO_ERROR_TEXT, NO_DATA_TEXT, PROPERTY_NAME_ANCILLARY_RELATIONS, PROPERTY_NAME_ANCILLARY_VARIABLES, PROPERTY_NAME_GEO_CODING, PROPERTY_NAME_IMAGE_INFO, PROPERTY_NAME_IMAGE_TO_MODEL_TRANSFORM, PROPERTY_NAME_LOG_10_SCALED, PROPERTY_NAME_MODEL_TO_SCENE_TRANSFORM, PROPERTY_NAME_NO_DATA_VALUE, PROPERTY_NAME_NO_DATA_VALUE_USED, PROPERTY_NAME_SCALING_FACTOR, PROPERTY_NAME_SCALING_OFFSET, PROPERTY_NAME_SCENE_TO_MODEL_TRANSFORM, PROPERTY_NAME_STX, PROPERTY_NAME_TIME_CODING, PROPERTY_NAME_VALID_PIXEL_EXPRESSION

Fields inherited from class org.esa.snap.core.datamodel.DataNode

PROPERTY_NAME_DATA, PROPERTY_NAME_READ_ONLY, PROPERTY_NAME_SYNTHETIC, PROPERTY_NAME_UNIT

Fields inherited from class org.esa.snap.core.datamodel.ProductNode

PROPERTY_NAME_DESCRIPTION, PROPERTY_NAME_NAME

Fields inherited from interface org.esa.snap.core.datamodel.Scaling

IDENTITY

Constructor Summary

Constructors

Constructor and Description
Band(String name, int dataType, int width, int height) Constructs a new Band.

Method Summary

Modifier and Type	Method and Description
void	acceptVisitor(ProductVisitor visitor) Accepts the given visitor.
protected Stx	computeStxImpl(int level, ProgressMonitor pm) Computes the statistics.
ImageInfo	createDefaultImageInfo(double[] histoSkipAreas, ProgressMonitor pm) Creates a default image information instance.
protected RenderedImage	createSourceImage() Creates the source image associated with this RasterDataNode.
void	dispose() Releases all of the resources used by this object instance and all of its owned children.
FlagCoding	getFlagCoding() Gets the flag coding for this band.
IndexCoding	getIndexCoding() Gets the index coding for this band.
long	getRawStorageSize(ProductSubsetDef subsetDef) Gets an estimated raw storage size in bytes of this product node.
SampleCoding	getSampleCoding() Gets the sample coding.
float	getSolarFlux() Gets the solar flux in mW/(m^2 nm) (milli-watts per square metre per nanometer) units for the wavelength of this band.
int	getSpectralBandIndex() Gets the (zero-based) spectral band index.
float	getSpectralBandwidth() Gets the spectral bandwidth in nm (nanomater) units.
float	getSpectralWavelength() Gets the spectral wavelength in nm (nanometer) units.
boolean	isFlagBand() Tests whether or not this band is a flag band (getFlagCoding() !
boolean	isIndexBand() Tests whether or not this band is an index band (getIndexCoding() !
void	readRasterData(int offsetX, int offsetY, int width, int height, ProductData rasterData, ProgressMonitor pm) Reads raster data from its associated data source into the given data buffer.
void	readRasterDataFully(ProgressMonitor pm) Reads the complete underlying raster data.
void	removeFromFile(ProductWriter productWriter) Physically remove this node from the file associated with the given product writer.
void	setSampleCoding(SampleCoding sampleCoding) Sets the sample coding for this band.
void	setSolarFlux(float solarFlux) Sets the solar flux in mW/(m^2 nm) (milli-watts per square metre per nanometer) units for the wavelength of this band.
void	setSpectralBandIndex(int spectralBandIndex) Sets the (zero-based) spectral band index.
void	setSpectralBandwidth(float spectralBandwidth) Sets the spectral bandwidth in nm (nanomater) units.
void	setSpectralWavelength(float spectralWavelength) Sets the spectral wavelength in nm (nanomater) units.
String	toString() Creates a string defining this band object.
void	writeRasterData(int offsetX, int offsetY, int width, int height, ProductData rasterData, ProgressMonitor pm) Writes data from this product raster into the specified region of the user-supplied raster.
void	writeRasterDataFully(ProgressMonitor pm) Writes the complete underlying raster data.

Methods inherited from class org.esa.snap.core.datamodel.AbstractBand

ensureMinLengthArray, ensureMinLengthArray, ensureMinLengthArray, ensureRasterData, getPixelDouble, getPixelFloat, getPixelInt, getPixels, getPixels, getPixels, getRasterHeight, getRasterWidth, loadRasterData, readPixels, readPixels, readPixels, setPixelDouble, setPixelFloat, setPixelInt, setPixels, setPixels, setPixels, unloadRasterData, writePixels, writePixels, writePixels

Methods inherited from class org.esa.snap.core.datamodel.RasterDataNode

addAncillaryVariable, canBeOrthorectified, checkCompatibleRasterData, clearNoDataValue, createColorIndexedImage, createCompatibleRasterData, createCompatibleRasterData, createCompatibleSceneRasterData, createDefaultImageInfo, createMultiLevelModel, createPointing, createRgbImage, createTransectProfileData, fireImageInfoChanged, getAncillaryRelations, getAncillaryVariable, getAncillaryVariables, getGeoCoding, getGeophysicalDataType, getGeophysicalImage, getGeophysicalNoDataValue, getImageInfo, getImageInfo, getImageInfo, getImageToModelTransform, getModelToSceneTransform, getMultiLevelModel, getNoDataValue, getOverlayMaskGroup, getPixels, getPixels, getPixels, getPixelString, getPointing, getRasterData, getRasterSize, getSampleFloat, getSampleInt, getScalingFactor, getScalingOffset, getSceneToModelTransform, getSourceImage, getStx, getStx, getTimeCoding, getValidMaskExpression, getValidMaskImage, getValidPixelExpression, getValidShape, hasIntPixels, hasRasterData, isCompatibleRasterData, isFloatingPointType, isGeophysicalImageSet, isLog10Scaled, isNoDataValueSet, isNoDataValueUsed, isPixelValid, isPixelValid, isPixelValid, isScalingApplied, isSourceImageSet, isStxSet, isValidMaskImageSet, isValidMaskProperty, isValidMaskUsed, loadRasterData, processRasterData, quantizeRasterData, quantizeRasterData, readPixels, readPixels, readPixels, readRasterData, readRasterDataFully, readValidMask, removeAncillaryVariable, resetValidMask, scale, scaleInverse, setAncillaryRelations, setGeoCoding, setGeophysicalNoDataValue, setImageInfo, setImageInfo, setImageToModelTransform, setLog10Scaled, setModelToSceneTransform, setModified, setNoDataValue, setNoDataValueUsed, setRasterData, setScalingFactor, setScalingOffset, setSceneToModelTransform, setSourceImage, setSourceImage, setStx, setTimeCoding, setValidPixelExpression, updateExpression, writePixels, writePixels, writePixels, writeRasterData, writeRasterDataFully

Methods inherited from class org.esa.snap.core.datamodel.DataNode

checkDataCompatibility, createCompatibleProductData, fireProductNodeDataChanged, getData, getDataElems, getDataElemSize, getDataType, getNumDataElems, getUnit, isReadOnly, isSynthetic, setData, setDataElems, setReadOnly, setSynthetic, setUnit

Methods inherited from class org.esa.snap.core.datamodel.ProductNode

fireProductNodeChanged, fireProductNodeChanged, getDescription, getDisplayName, getName, getOwner, getProduct, getProductReader, getProductReaderSafe, getProductRefString, getProductSafe, getProductWriter, getProductWriterSafe, getRawStorageSize, isModified, isPartOfSubset, isValidNodeName, setDescription, setName, setOwner

Methods inherited from class com.bc.ceres.core.ExtensibleObject

getExtension

Methods inherited from class java.lang.Object

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

Field Detail

PROPERTY_NAME_SAMPLE_CODING

public static final String PROPERTY_NAME_SAMPLE_CODING

See Also:

Constant Field Values

PROPERTY_NAME_SOLAR_FLUX

public static final String PROPERTY_NAME_SOLAR_FLUX

See Also:

Constant Field Values

PROPERTY_NAME_SPECTRAL_BAND_INDEX

public static final String PROPERTY_NAME_SPECTRAL_BAND_INDEX

See Also:

Constant Field Values

PROPERTY_NAME_SPECTRAL_BANDWIDTH

public static final String PROPERTY_NAME_SPECTRAL_BANDWIDTH

See Also:

Constant Field Values

PROPERTY_NAME_SPECTRAL_WAVELENGTH

public static final String PROPERTY_NAME_SPECTRAL_WAVELENGTH

See Also:

Constant Field Values

Constructor Detail

Band

public Band(String name,
            int dataType,
            int width,
            int height)

Constructs a new Band.

Parameters:

name - the name of the new object

dataType - the raster data type, must be one of the multiple ProductData.TYPE_X constants, with the exception of ProductData.TYPE_UINT32

width - the width of the raster in pixels

height - the height of the raster in pixels

Method Detail

getFlagCoding

public FlagCoding getFlagCoding()

Gets the flag coding for this band.

Returns:

a non-null value if this band is a flag dataset, null otherwise

isFlagBand

public boolean isFlagBand()

Tests whether or not this band is a flag band (getFlagCoding() != null).

Returns:

true if so

getIndexCoding

public IndexCoding getIndexCoding()

Gets the index coding for this band.

Returns:

a non-null value if this band is a flag dataset, null otherwise

isIndexBand

public boolean isIndexBand()

Tests whether or not this band is an index band (getIndexCoding() != null).

Returns:

true if so

getSampleCoding

public SampleCoding getSampleCoding()

Gets the sample coding.

Returns:

the sample coding, or null if not set.

setSampleCoding

public void setSampleCoding(SampleCoding sampleCoding)

Sets the sample coding for this band.

Parameters:

sampleCoding - the sample coding

Throws:

IllegalArgumentException - if this band does not contain integer pixels

getSpectralBandIndex

public int getSpectralBandIndex()

Gets the (zero-based) spectral band index.

Returns:

the (zero-based) spectral band index or -1 if it is unknown

setSpectralBandIndex

public void setSpectralBandIndex(int spectralBandIndex)

Sets the (zero-based) spectral band index.

Parameters:

spectralBandIndex - the (zero-based) spectral band index or -1 if it is unknown

getSpectralWavelength

public float getSpectralWavelength()

Gets the spectral wavelength in nm (nanometer) units.

Returns:

the wave length in nanometers of this band, or zero if this is not a spectral band or the wave length is not known.

setSpectralWavelength

public void setSpectralWavelength(float spectralWavelength)

Sets the spectral wavelength in nm (nanomater) units.

Parameters:

spectralWavelength - the wavelength in nanometers of this band, or zero if this is not a spectral band or the wavelength is not known.

getSpectralBandwidth

public float getSpectralBandwidth()

Gets the spectral bandwidth in nm (nanomater) units.

Returns:

the bandwidth in nanometers of this band, or zero if this is not a spectral band or the bandwidth is not known.

setSpectralBandwidth

public void setSpectralBandwidth(float spectralBandwidth)

Sets the spectral bandwidth in nm (nanomater) units.

Parameters:

spectralBandwidth - the spectral bandwidth in nanometers of this band, or zero if this is not a spectral band or the spectral bandwidth is not known.

getSolarFlux

public float getSolarFlux()

Gets the solar flux in mW/(m^2 nm) (milli-watts per square metre per nanometer) units for the wavelength of this band.

Returns:

the solar flux for the wavelength of this band, or zero if this is not a spectral band or the solar flux is not known.

setSolarFlux

public void setSolarFlux(float solarFlux)

Sets the solar flux in mW/(m^2 nm) (milli-watts per square metre per nanometer) units for the wavelength of this band.

Parameters:

solarFlux - the solar flux for the wavelength of this band, or zero if this is not a spectral band or the solar flux is not known.

createSourceImage

protected RenderedImage createSourceImage()

Description copied from class: RasterDataNode

Creates the source image associated with this RasterDataNode. This shall preferably be a MultiLevelImage instance which recognises this raster data node's imageToModelTransform property, if set.

Specified by:

createSourceImage in class RasterDataNode

Returns:

A new source image instance.

readRasterData

public void readRasterData(int offsetX,
                           int offsetY,
                           int width,
                           int height,
                           ProductData rasterData,
                           ProgressMonitor pm)
                    throws IOException

Reads raster data from its associated data source into the given data buffer.

Specified by:

readRasterData in class RasterDataNode

Parameters:

offsetX - the X-offset in the band's pixel co-ordinates where reading starts

offsetY - the Y-offset in the band's pixel co-ordinates where reading starts

width - the width of the raster data buffer

height - the height of the raster data buffer

rasterData - a raster data buffer receiving the pixels to be read

pm - a monitor to inform the user about progress

Throws:

IOException - if an I/O error occurs

IllegalArgumentException - if the raster is null

IllegalStateException - if this product raster was not added to a product so far, or if the product to which this product raster belongs to, has no associated product reader

See Also:

ProductReader.readBandRasterData(Band, int, int, int, int, ProductData, com.bc.ceres.core.ProgressMonitor)

readRasterDataFully

public void readRasterDataFully(ProgressMonitor pm)
                         throws IOException

Reads the complete underlying raster data.

After this method has been called successfully, hasRasterData() should always return true and getRasterData() should always return a valid ProductData instance with at least getRasterWidth()*getRasterHeight() elements (samples).

In opposite to the loadRasterData method, the readRasterDataFully method always reloads the data of this product raster, independently of whether its has already been loaded or not.

Specified by:

readRasterDataFully in class RasterDataNode

Parameters:

pm - a monitor to inform the user about progress

Throws:

IOException - if an I/O error occurs

See Also:

RasterDataNode.loadRasterData(), RasterDataNode.readRasterData(int, int, int, int, ProductData, com.bc.ceres.core.ProgressMonitor)

writeRasterData

public void writeRasterData(int offsetX,
                            int offsetY,
                            int width,
                            int height,
                            ProductData rasterData,
                            ProgressMonitor pm)
                     throws IOException

Writes data from this product raster into the specified region of the user-supplied raster.

It is important to know that this method does not change this product raster's internal state nor does it write into this product raster's internal raster.

Specified by:

writeRasterData in class RasterDataNode

Parameters:

offsetX - the X-offset in raster co-ordinates where reading starts

offsetY - the Y-offset in raster co-ordinates where reading starts

width - the width of the raster data buffer

height - the height of the raster data buffer

rasterData - a raster data buffer receiving the pixels to be read

pm - a monitor to inform the user about progress

Throws:

IOException - if an I/O error occurs

See Also:

ProductReader.readBandRasterData(Band, int, int, int, int, ProductData, com.bc.ceres.core.ProgressMonitor)

writeRasterDataFully

public void writeRasterDataFully(ProgressMonitor pm)
                          throws IOException

Writes the complete underlying raster data.

Specified by:

writeRasterDataFully in class RasterDataNode

Parameters:

pm - a monitor to inform the user about progress

Throws:

IOException - if an I/O error occurs

getRawStorageSize

public long getRawStorageSize(ProductSubsetDef subsetDef)

Gets an estimated raw storage size in bytes of this product node.

Specified by:

getRawStorageSize in class AbstractBand

Parameters:

subsetDef - if not null the subset may limit the size returned

Returns:

the size in bytes.

acceptVisitor

public void acceptVisitor(ProductVisitor visitor)

Accepts the given visitor. This method implements the well known 'Visitor' design pattern of the gang-of-four. The visitor pattern allows to define new operations on the product data model without the need to add more code to it. The new operation is implemented by the visitor.

The method simply calls visitor.visit(this).

Specified by:

acceptVisitor in class RasterDataNode

Parameters:

visitor - the visitor, must not be null

toString

public String toString()

Creates a string defining this band object.

Overrides:

toString in class ProductNode

removeFromFile

public void removeFromFile(ProductWriter productWriter)

Description copied from class: ProductNode

Physically remove this node from the file associated with the given product writer. The default implementation does nothing.

Overrides:

removeFromFile in class ProductNode

Parameters:

productWriter - the product writer to be used to remove this node from the underlying file.

createDefaultImageInfo

public ImageInfo createDefaultImageInfo(double[] histoSkipAreas,
                                        ProgressMonitor pm)

Description copied from class: RasterDataNode

Creates a default image information instance.

An IllegalStateException is thrown in the case that this raster data node has no raster data.

Overrides:

createDefaultImageInfo in class RasterDataNode

Parameters:

histoSkipAreas - the left (at index 0) and right (at index 1) normalized areas of the raster data histogram to be excluded when determining the value range for a linear constrast stretching. Can be null, in this case {0.01, 0.04} resp. 5% of the entire area is skipped.

pm - a monitor to inform the user about progress

Returns:

a valid image information instance, never null.

computeStxImpl

protected Stx computeStxImpl(int level,
                             ProgressMonitor pm)

Description copied from class: RasterDataNode

Computes the statistics. May be overridden. This method belongs to preliminary API and may be removed or changed in the future.

Overrides:

computeStxImpl in class RasterDataNode

Parameters:

level - The resolution level.

pm - A progress monitor.

Returns:

The statistics.

dispose

public void dispose()

Releases all of the resources used by this object instance and all of its owned children. Its primary use is to allow the garbage collector to perform a vanilla job.

This method should be called only if it is for sure that this object instance will never be used again. The results of referencing an instance of this class after a call to dispose() are undefined.

Overrides of this method should always call super.dispose(); after disposing this instance.

Overrides:

dispose in class RasterDataNode