File failed to load: https://isis.astrogeology.usgs.gov/dev/Object/assets/jax/output/NativeMML/config.js
Isis Developer Reference
Isis::CubeIoHandler Class Referenceabstract

Handles converting buffers to and from disk. More...

#include <CubeIoHandler.h>

Inheritance diagram for Isis::CubeIoHandler:
Inheritance graph
Collaboration diagram for Isis::CubeIoHandler:
Collaboration graph

Public Member Functions

 CubeIoHandler (QFile *dataFile, const QList< int > *virtualBandList, const Pvl &label, bool alreadyOnDisk)
 Creates a new CubeIoHandler using a RegionalCachingAlgorithm.
 
virtual ~CubeIoHandler ()
 Cleans up all allocated memory.
 
virtual void read (Buffer &bufferToFill) const
 Read cube data from disk into the buffer.
 
virtual void write (const Buffer &bufferToWrite)
 Write buffer data into the cube data on disk.
 
virtual void addCachingAlgorithm (CubeCachingAlgorithm *algorithm)
 This will add the given caching algorithm to the list of attempted caching algorithms.
 
virtual void clearCache (bool blockForWriteCache=true) const
 Free all cube chunks (cached cube data) from memory and write them to disk.
 
virtual BigInt getDataSize () const
 
virtual void updateLabels (Pvl &labels)=0
 Function to update the labels with a Pvl object.
 
int bandCount () const
 
int getBandCountInChunk () const
 
BigInt getBytesPerChunk () const
 
int getChunkCountInBandDimension () const
 
int getChunkCountInLineDimension () const
 
int getChunkCountInSampleDimension () const
 
int getChunkIndex (const RawCubeChunk &) const
 Given a chunk, what's its index in the file.
 
BigInt getDataStartByte () const
 
int lineCount () const
 
int getLineCountInChunk () const
 
PixelType pixelType () const
 
int sampleCount () const
 
int getSampleCountInChunk () const
 
void setVirtualBands (const QList< int > *virtualBandList)
 This changes the virtual band list.
 
QMutex * dataFileMutex ()
 Get the mutex that this IO handler is using around I/Os on the given data file.
 

Protected Member Functions

QFile * getDataFile ()
 
void setChunkSizes (int numSamples, int numLines, int numBands)
 This should be called once from the child constructor.
 
virtual void readRaw (RawCubeChunk &chunkToFill)=0
 This needs to populate the chunkToFill with unswapped raw bytes from the disk.
 
virtual void writeRaw (const RawCubeChunk &chunkToWrite)=0
 This needs to write the chunkToWrite directly to disk with no modifications to the data itself.
 

Protected Attributes

QMutex * m_writeThreadMutex
 This enables us to block while the write thread is working.
 
QList< int > * m_virtualBands
 Converts from virtual band to physical band.
 

Detailed Description

Handles converting buffers to and from disk.

This class handles converting buffers to and from disk. This class holds the cube chunks in memory and is capable of reading and writing them. It asks the caching algorithms to recommend cube chunks to not keep in memory. Children need to call setChunkSizes() in their constructor.

This class handles all of the virtual band conversions. This class also guarantees that unwritten cube data ends up read and written as NULLs. The default caching algorithm is a RegionalCachingAlgorithm.

Author
2011-??-?? Jai Rideout and Steven Lambright

Constructor & Destructor Documentation

◆ CubeIoHandler()

Isis::CubeIoHandler::CubeIoHandler ( QFile * dataFile,
const QList< int > * virtualBandList,
const Pvl & label,
bool alreadyOnDisk )

Creates a new CubeIoHandler using a RegionalCachingAlgorithm.

The chunk sizes must be set by a child in its constructor.

Parameters
dataFileThe file that contains cube data. This should be a valid, opened QFile and may not be NULL. The file should have at least read permissions.
virtualBandListA list where the indices are the vbands and the values are the physical bands. The values are 1-based. This can be specified as NULL, in which case the vbands are the physical bands. The virtual band list is copied (the pointer provided isn't remembered).
labelThe label which contains the "Pixels" and "Core" groups.
alreadyOnDiskTrue if the cube exists; false ensures all NULLs are initialized into the file before this object is destructed.

References _FILEINFO_, Isis::IString::DownCase(), Isis::PvlObject::findGroup(), Isis::PvlContainer::findKeyword(), Isis::PvlObject::findKeyword(), Isis::PvlObject::findObject(), Isis::ImageIoHandler::ImageIoHandler(), Isis::ImageIoHandler::m_writeThreadMutex, Isis::PixelTypeEnumeration(), Isis::Preference::Preferences(), and Isis::IException::Programmer.

Referenced by clearCache(), Isis::CubeBsqHandler::CubeBsqHandler(), Isis::CubeTileHandler::CubeTileHandler(), and writeRaw().

◆ ~CubeIoHandler()

Isis::CubeIoHandler::~CubeIoHandler ( )
virtual

Cleans up all allocated memory.

Child destructors must call clearCache() because we can no longer do IO by the time this destructor is called.

Member Function Documentation

◆ addCachingAlgorithm()

void Isis::CubeIoHandler::addCachingAlgorithm ( CubeCachingAlgorithm * algorithm)
virtual

This will add the given caching algorithm to the list of attempted caching algorithms.

The algorithms are tried in the opposite order that they were added - the first algorithm added is the last algorithm tried.

This method takes ownership of algorithm.

Parameters
algorithmThe caching algorithm to add to the Cube for I/O

Reimplemented from Isis::ImageIoHandler.

◆ bandCount()

int Isis::CubeIoHandler::bandCount ( ) const
Returns
the number of physical bands in the cube.

◆ clearCache()

void Isis::CubeIoHandler::clearCache ( bool blockForWriteCache = true) const
virtual

Free all cube chunks (cached cube data) from memory and write them to disk.

Child destructors need to call this method.

This method should only be called otherwise when lots of cubes are in memory and the many caches cause problems with system RAM limitations.

Parameters
blockForWriteCacheThis should be true unless this method is called from the write thread.

Reimplemented from Isis::ImageIoHandler.

References CubeIoHandler(), and writeRaw().

Referenced by Isis::CubeBsqHandler::~CubeBsqHandler(), and Isis::CubeTileHandler::~CubeTileHandler().

◆ dataFileMutex()

QMutex * Isis::ImageIoHandler::dataFileMutex ( )
inherited

Get the mutex that this IO handler is using around I/Os on the given data file.

A lock should be acquired before doing any reads/writes on the data file externally.

Returns
A mutex that can guarantee exclusive access to the data file

References m_writeThreadMutex.

◆ getBandCountInChunk()

int Isis::CubeIoHandler::getBandCountInChunk ( ) const
Returns
the number of bands per chunk for this cube.

Referenced by getChunkIndex(), and read().

◆ getBytesPerChunk()

BigInt Isis::CubeIoHandler::getBytesPerChunk ( ) const
Returns
the byte size of each chunk in the cube. Currently they must be constant size, but this is planned to be changed at some point in time.
Number of bytes in a cube chunk

References Isis::SizeOf().

Referenced by getDataSize().

◆ getChunkCountInBandDimension()

int Isis::CubeIoHandler::getChunkCountInBandDimension ( ) const
Returns
the total number of chunks in the band (Z) dimension. This is always enough to contain every band in the cube.

Referenced by getDataSize().

◆ getChunkCountInLineDimension()

int Isis::CubeIoHandler::getChunkCountInLineDimension ( ) const
Returns
the total number of chunks in the line (Y) dimension. This is always enough to contain every line in the cube.

Referenced by getChunkIndex(), getDataSize(), and read().

◆ getChunkCountInSampleDimension()

int Isis::CubeIoHandler::getChunkCountInSampleDimension ( ) const
Returns
the total number of chunks in the sample (X) dimension. This is always enough to contain every sample in the cube.

Referenced by getChunkIndex(), getDataSize(), and read().

◆ getChunkIndex()

int Isis::CubeIoHandler::getChunkIndex ( const RawCubeChunk & chunk) const

Given a chunk, what's its index in the file.

Chunks are ordered from left to right, then top to bottom, then front to back (BSQ). The first chunk is at the top left of band 1 and is index 0, for example. In other words, this is going from the value of m_rawData to the key.

Chunks which sit outside of the cube entirely must not be passed into this method; the results will be wrong.

Returns
The chunk's index into the file

References getBandCountInChunk(), getChunkCountInLineDimension(), getChunkCountInSampleDimension(), getLineCountInChunk(), getSampleCountInChunk(), Isis::RawCubeChunk::getStartBand(), Isis::RawCubeChunk::getStartLine(), and Isis::RawCubeChunk::getStartSample().

◆ getDataFile()

QFile * Isis::CubeIoHandler::getDataFile ( )
protected
Returns
the QFile containing cube data. This is what should be read from and written to.
The data file for I/O

Referenced by Isis::CubeBsqHandler::readRaw(), Isis::CubeTileHandler::readRaw(), Isis::CubeBsqHandler::writeRaw(), and Isis::CubeTileHandler::writeRaw().

◆ getDataSize()

BigInt Isis::CubeIoHandler::getDataSize ( ) const
virtual
Returns
the number of bytes that the cube DNs will take up. This includes padding caused by the cube chunks not aligning with the cube dimensions.

Implements Isis::ImageIoHandler.

References getBytesPerChunk(), getChunkCountInBandDimension(), getChunkCountInLineDimension(), and getChunkCountInSampleDimension().

Referenced by setChunkSizes().

◆ getDataStartByte()

BigInt Isis::CubeIoHandler::getDataStartByte ( ) const
Returns
the byte offset to the beginning of the cube data.

Referenced by setChunkSizes().

◆ getLineCountInChunk()

int Isis::CubeIoHandler::getLineCountInChunk ( ) const
Returns
the number of lines in each chunk of the cube.

Referenced by getChunkIndex(), read(), and Isis::CubeTileHandler::updateLabels().

◆ getSampleCountInChunk()

int Isis::CubeIoHandler::getSampleCountInChunk ( ) const
Returns
the number of samples in each chunk of the cube.

Referenced by getChunkIndex(), read(), and Isis::CubeTileHandler::updateLabels().

◆ lineCount()

int Isis::CubeIoHandler::lineCount ( ) const
Returns
the number of lines in the cube. This does not include lines created by the chunk overflowing the line dimension.

Referenced by Isis::CubeBsqHandler::CubeBsqHandler().

◆ pixelType()

PixelType Isis::CubeIoHandler::pixelType ( ) const
Returns
the physical cube DN format.

Referenced by Isis::CubeBsqHandler::CubeBsqHandler().

◆ read()

void Isis::CubeIoHandler::read ( Buffer & bufferToFill) const
virtual

◆ readRaw()

virtual void Isis::CubeIoHandler::readRaw ( RawCubeChunk & chunkToFill)
protectedpure virtual

This needs to populate the chunkToFill with unswapped raw bytes from the disk.

See also
CubeTileHandler::readRaw()
Parameters
chunkToFillThe container that needs to be filled with cube data.

Implemented in Isis::CubeBsqHandler, and Isis::CubeTileHandler.

◆ sampleCount()

int Isis::CubeIoHandler::sampleCount ( ) const
Returns
the number of samples in the cube. This does not include samples created by the chunk overflowing the sample dimension.

Referenced by Isis::CubeBsqHandler::CubeBsqHandler().

◆ setChunkSizes()

void Isis::CubeIoHandler::setChunkSizes ( int numSamples,
int numLines,
int numBands )
protected

This should be called once from the child constructor.

This determines the chunk sizes used for the cube and often should remain constant for a particular cube (BSQ, for example, doesn't need it to be constant but Tile does). These being large can cause excessive use of disk space that stores no cube data. These being large can also drastically increase the amount of RAM consumed.

Parameters
numSamplesThe chunk size in the sample dimension
numLinesThe chunk size in the line dimension
numBandsThe chunk size in the band dimension

References _FILEINFO_, getDataSize(), getDataStartByte(), and Isis::IException::Programmer.

Referenced by Isis::CubeBsqHandler::CubeBsqHandler().

◆ setVirtualBands()

void Isis::ImageIoHandler::setVirtualBands ( const QList< int > * virtualBandList)
inherited

This changes the virtual band list.

Parameters
virtualBandListA list where the indices are the vbands and the values are the physical bands. The values are 1-based. This can be specified as NULL, in which case the vbands are the physical bands. The virtual band list is copied (the pointer provided isn't remembered).

References m_virtualBands.

Referenced by ImageIoHandler().

◆ updateLabels()

virtual void Isis::CubeIoHandler::updateLabels ( Pvl & labels)
pure virtual

Function to update the labels with a Pvl object.

Parameters
labelsPvl object to update with

Implements Isis::ImageIoHandler.

Implemented in Isis::CubeBsqHandler, and Isis::CubeTileHandler.

◆ write()

void Isis::CubeIoHandler::write ( const Buffer & bufferToWrite)
virtual

Write buffer data into the cube data on disk.

This could do no IO if the cube chunks required are already in memory and our caching algorithms say to not free any of the cube chunks afterwards.

Parameters
bufferToWriteThe buffer to get cube data from.

Implements Isis::ImageIoHandler.

References Isis::ImageIoHandler::m_writeThreadMutex.

◆ writeRaw()

virtual void Isis::CubeIoHandler::writeRaw ( const RawCubeChunk & chunkToWrite)
protectedpure virtual

This needs to write the chunkToWrite directly to disk with no modifications to the data itself.

See also
CubeTileHandler::writeRaw()
Parameters
chunkToWriteThe container that needs to be put on disk.

Implemented in Isis::CubeBsqHandler, and Isis::CubeTileHandler.

References CubeIoHandler().

Referenced by clearCache().

Member Data Documentation

◆ m_virtualBands

QList<int>* Isis::ImageIoHandler::m_virtualBands
protectedinherited

◆ m_writeThreadMutex

QMutex* Isis::ImageIoHandler::m_writeThreadMutex
protectedinherited

The documentation for this class was generated from the following files: