Isis 3 Programmer Reference
Isis::CubeTileHandler Class Reference

IO Handler for Isis Cubes using the tile format. More...

#include <CubeTileHandler.h>

Inheritance diagram for Isis::CubeTileHandler:
Inheritance graph
Collaboration diagram for Isis::CubeTileHandler:
Collaboration graph

Public Member Functions

 CubeTileHandler (QFile *dataFile, const QList< int > *virtualBandList, const Pvl &label, bool alreadyOnDisk)
 Construct a tile handler. More...
 
 ~CubeTileHandler ()
 Writes all data from memory to disk. More...
 
void updateLabels (Pvl &label)
 Update the cube labels so that this cube indicates what tile size it used. More...
 
void read (Buffer &bufferToFill) const
 Read cube data from disk into the buffer. More...
 
void write (const Buffer &bufferToWrite)
 Write buffer data into the cube data on disk. More...
 
void addCachingAlgorithm (CubeCachingAlgorithm *algorithm)
 This will add the given caching algorithm to the list of attempted caching algorithms. More...
 
void clearCache (bool blockForWriteCache=true) const
 Free all cube chunks (cached cube data) from memory and write them to disk. More...
 
BigInt getDataSize () const
 
void setVirtualBands (const QList< int > *virtualBandList)
 This changes the virtual band list. More...
 
QMutex * dataFileMutex ()
 Get the mutex that this IO handler is using around I/Os on the given data file. More...
 

Protected Member Functions

virtual void readRaw (RawCubeChunk &chunkToFill)
 This needs to populate the chunkToFill with unswapped raw bytes from the disk. More...
 
virtual void writeRaw (const RawCubeChunk &chunkToWrite)
 This needs to write the chunkToWrite directly to disk with no modifications to the data itself. More...
 
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. More...
 
BigInt getDataStartByte () const
 
QFile * getDataFile ()
 
int lineCount () const
 
int getLineCountInChunk () const
 
PixelType pixelType () const
 
int sampleCount () const
 
int getSampleCountInChunk () const
 
void setChunkSizes (int numSamples, int numLines, int numBands)
 This should be called once from the child constructor. More...
 

Private Member Functions

 CubeTileHandler (const CubeTileHandler &other)
 Disallow copying of this object. More...
 
CubeTileHandleroperator= (const CubeTileHandler &other)
 Disallow assignments of this object. More...
 
int findGoodSize (int maxSize, int dimensionSize) const
 This is a helper method that tries to compute a good tile size for one of the cube's dimensions (sample or line). More...
 
BigInt getTileStartByte (const RawCubeChunk &chunk) const
 This is a helper method that goes from chunk to file position. More...
 

Detailed Description

IO Handler for Isis Cubes using the tile format.

This class is used to open, create, read, and write data from Isis cube files.

Author
2003-02-14 Jeff Anderson
History:

2007-09-14 Stuart Sides - Fixed bug where pixels from a buffer outside the ns/nl were being transfered to the right most and bottom most tiles

2011-06-16 Jai Rideout and Steven Lambright - Refactored to work with the new parent.

2011-07-18 Jai Rideout and Steven Lambright - Added unimplemented copy constructor and assignment operator.

Definition at line 52 of file CubeTileHandler.h.

Constructor & Destructor Documentation

◆ CubeTileHandler() [1/2]

Isis::CubeTileHandler::CubeTileHandler ( QFile *  dataFile,
const QList< int > *  virtualBandList,
const Pvl labels,
bool  alreadyOnDisk 
)

Construct a tile handler.

This will determine a good chunk size to put into the output cube.

Parameters
dataFileThe file with cube DN data in it
virtualBandListThe mapping from virtual band to physical band, see CubeIoHandler's description.
labelsThe Pvl labels for the cube
alreadyOnDiskTrue if the cube is allocated on the disk, false otherwise

Definition at line 48 of file CubeTileHandler.cpp.

References findGoodSize(), Isis::PvlObject::findObject(), Isis::PvlObject::hasKeyword(), Isis::CubeIoHandler::lineCount(), Isis::CubeIoHandler::pixelType(), Isis::CubeIoHandler::sampleCount(), Isis::CubeIoHandler::setChunkSizes(), and Isis::SizeOf().

◆ ~CubeTileHandler()

Isis::CubeTileHandler::~CubeTileHandler ( )

Writes all data from memory to disk.

Definition at line 72 of file CubeTileHandler.cpp.

References Isis::CubeIoHandler::clearCache().

◆ CubeTileHandler() [2/2]

Isis::CubeTileHandler::CubeTileHandler ( const CubeTileHandler other)
private

Disallow copying of this object.

Parameters
otherThe object to copy.

Member Function Documentation

◆ addCachingAlgorithm()

void Isis::CubeIoHandler::addCachingAlgorithm ( CubeCachingAlgorithm algorithm)
inherited

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

Definition at line 384 of file CubeIoHandler.cpp.

◆ bandCount()

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

Definition at line 482 of file CubeIoHandler.cpp.

◆ clearCache()

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

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.

Definition at line 399 of file CubeIoHandler.cpp.

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

◆ dataFileMutex()

QMutex * Isis::CubeIoHandler::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

Definition at line 475 of file CubeIoHandler.cpp.

◆ findGoodSize()

int Isis::CubeTileHandler::findGoodSize ( int  maxSize,
int  dimensionSize 
) const
private

This is a helper method that tries to compute a good tile size for one of the cube's dimensions (sample or line).

Band tile size is always 1 for this format currently.

Parameters
maxSizeThe largest allowed size
dimensionSizeThe cube's size in the dimension we're figuring out (that is, number of samples or number of lines).
Returns
The tile size that should be used for the dimension

Definition at line 151 of file CubeTileHandler.cpp.

Referenced by CubeTileHandler().

◆ getBandCountInChunk()

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

Definition at line 490 of file CubeIoHandler.cpp.

◆ getBytesPerChunk()

BigInt Isis::CubeIoHandler::getBytesPerChunk ( ) const
protectedinherited
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

Definition at line 502 of file CubeIoHandler.cpp.

References Isis::SizeOf().

Referenced by Isis::CubeBsqHandler::getChunkStartByte(), and getTileStartByte().

◆ getChunkCountInBandDimension()

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

Definition at line 512 of file CubeIoHandler.cpp.

◆ getChunkCountInLineDimension()

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

Definition at line 521 of file CubeIoHandler.cpp.

◆ getChunkCountInSampleDimension()

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

Definition at line 530 of file CubeIoHandler.cpp.

◆ getChunkIndex()

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

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

Definition at line 546 of file CubeIoHandler.cpp.

References Isis::RawCubeChunk::getStartBand(), Isis::RawCubeChunk::getStartLine(), and Isis::RawCubeChunk::getStartSample().

Referenced by Isis::CubeBsqHandler::getChunkStartByte(), and getTileStartByte().

◆ getDataFile()

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

Definition at line 578 of file CubeIoHandler.cpp.

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

◆ getDataSize()

BigInt Isis::CubeIoHandler::getDataSize ( ) const
inherited
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.

Definition at line 441 of file CubeIoHandler.cpp.

◆ getDataStartByte()

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

Definition at line 567 of file CubeIoHandler.cpp.

Referenced by Isis::CubeBsqHandler::getChunkStartByte(), and getTileStartByte().

◆ getLineCountInChunk()

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

Definition at line 595 of file CubeIoHandler.cpp.

Referenced by updateLabels().

◆ getSampleCountInChunk()

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

Definition at line 620 of file CubeIoHandler.cpp.

Referenced by updateLabels().

◆ getTileStartByte()

BigInt Isis::CubeTileHandler::getTileStartByte ( const RawCubeChunk chunk) const
private

This is a helper method that goes from chunk to file position.

Parameters
chunkThe chunk to locate in the file.
Returns
The position to start reading or writing at

Definition at line 179 of file CubeTileHandler.cpp.

References Isis::CubeIoHandler::getBytesPerChunk(), Isis::CubeIoHandler::getChunkIndex(), and Isis::CubeIoHandler::getDataStartByte().

Referenced by readRaw(), and writeRaw().

◆ lineCount()

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

Definition at line 587 of file CubeIoHandler.cpp.

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

◆ operator=()

CubeTileHandler& Isis::CubeTileHandler::operator= ( const CubeTileHandler other)
private

Disallow assignments of this object.

Parameters
otherThe CubeTileHandler on the right-hand side of the assignment that we are copying into *this.
Returns
A reference to *this.

◆ pixelType()

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

Definition at line 603 of file CubeIoHandler.cpp.

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

◆ read()

void Isis::CubeIoHandler::read ( Buffer bufferToFill) const
inherited

Read cube data from disk into the buffer.

This is not const because it caches the read cube chunks from the disk.

Parameters
bufferToFillThe buffer to populate with cube data.

Definition at line 246 of file CubeIoHandler.cpp.

References Isis::Buffer::Band(), Isis::Buffer::BandDimension(), Isis::Buffer::Line(), Isis::Buffer::LineDimension(), Isis::Null, Isis::Buffer::Sample(), Isis::Buffer::SampleDimension(), and Isis::Buffer::size().

◆ readRaw()

void Isis::CubeTileHandler::readRaw ( RawCubeChunk chunkToFill)
protectedvirtual

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.

Implements Isis::CubeIoHandler.

Definition at line 93 of file CubeTileHandler.cpp.

References _FILEINFO_, Isis::RawCubeChunk::getByteCount(), Isis::CubeIoHandler::getDataFile(), getTileStartByte(), Isis::IException::Io, and Isis::RawCubeChunk::setRawData().

◆ sampleCount()

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

Definition at line 612 of file CubeIoHandler.cpp.

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

◆ setChunkSizes()

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

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

Definition at line 637 of file CubeIoHandler.cpp.

References _FILEINFO_.

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

◆ setVirtualBands()

void Isis::CubeIoHandler::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).

Definition at line 458 of file CubeIoHandler.cpp.

◆ updateLabels()

void Isis::CubeTileHandler::updateLabels ( Pvl labels)
virtual

Update the cube labels so that this cube indicates what tile size it used.

Parameters
labelsThe "Core" object in this Pvl will be updated

Implements Isis::CubeIoHandler.

Definition at line 82 of file CubeTileHandler.cpp.

References Isis::PvlContainer::addKeyword(), Isis::PvlObject::findObject(), Isis::CubeIoHandler::getLineCountInChunk(), Isis::CubeIoHandler::getSampleCountInChunk(), and Isis::toString().

◆ write()

void Isis::CubeIoHandler::write ( const Buffer bufferToWrite)
inherited

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.

Definition at line 354 of file CubeIoHandler.cpp.

◆ writeRaw()

void Isis::CubeTileHandler::writeRaw ( const RawCubeChunk chunkToWrite)
protectedvirtual

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.

Implements Isis::CubeIoHandler.

Definition at line 118 of file CubeTileHandler.cpp.

References _FILEINFO_, Isis::RawCubeChunk::getByteCount(), Isis::CubeIoHandler::getDataFile(), Isis::RawCubeChunk::getRawData(), getTileStartByte(), and Isis::IException::Io.


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