Isis 3 Programmer Reference
Isis::Cube Class Reference

IO Handler for Isis Cubes. More...

#include <Cube.h>

Collaboration diagram for Isis::Cube:
Collaboration graph

Public Types

enum  Format { Bsq , Tile }
 These are the possible storage formats of ISIS cubes. More...
 

Public Member Functions

 Cube ()
 Constructs a Cube object.
 
 Cube (const FileName &fileName, QString access="r")
 Construct a cube and open it for reading or reading/writing.
 
virtual ~Cube ()
 Destroys the Cube object.
 
void fromIsd (const FileName &fileName, Pvl &label, nlohmann::json &isd, QString access)
 Initialize Cube data from a PVL label and JSON ISD.
 
void fromIsd (const FileName &fileName, FileName &labelFile, FileName &isdFile, QString access)
 Initialize Cube data from a PVL label and JSON ISD.
 
void fromLabel (const FileName &fileName, Pvl &label, QString access)
 Initialize Cube data from a PVL label.
 
bool isOpen () const
 Test if a cube file has been opened/created.
 
bool isProjected () const
 Returns true if the labels of the cube appear to have a valid mapping group.
 
bool isReadOnly () const
 Test if the opened cube is read-only, that is write operations will fail if this is true.
 
bool isReadWrite () const
 Test if the opened cube is read-write, that is read and write operations should succeed if this is true.
 
bool labelsAttached () const
 Test if labels are attached.
 
void attachSpiceFromIsd (nlohmann::json Isd)
 
void close (bool remove=false)
 Closes the cube and updates the labels.
 
Cubecopy (FileName newFile, const CubeAttributeOutput &newFileAttributes)
 Copies the cube to the new fileName.
 
void create (const QString &cfile)
 This method will create an isis cube for writing.
 
void create (const QString &cfile, const CubeAttributeOutput &att)
 This method will create an isis cube for writing.
 
void open (const QString &cfile, QString access="r")
 This method will open an existing isis cube for reading or reading/writing.
 
void reopen (QString access="r")
 This method will reopen an isis sube for reading or reading/writing.
 
void read (Blob &blob, const std::vector< PvlKeyword > keywords=std::vector< PvlKeyword >()) const
 This method will read data from the specified Blob object.
 
void read (Buffer &rbuf) const
 This method will read a buffer of data from the cube as specified by the contents of the Buffer object.
 
OriginalLabel readOriginalLabel (const QString &name="IsisCube") const
 Read the original PDS3 label from a cube.
 
CubeStretch readCubeStretch (QString name="CubeStretch", const std::vector< PvlKeyword > keywords=std::vector< PvlKeyword >()) const
 Read a Stretch from a cube.
 
OriginalXmlLabel readOriginalXmlLabel () const
 Read the original PDS4 label from a cube.
 
History readHistory (const QString &name="IsisCube") const
 Read the History from the Cube.
 
ImagePolygon readFootprint () const
 Read the footprint polygon for the Cube.
 
Table readTable (const QString &name)
 Read a Table from the cube.
 
void write (Blob &blob, bool overwrite=true)
 This method will write a blob of data (e.g.
 
void write (const Table &table)
 Write a Table to the Cube.
 
void write (const CubeStretch &cubeStretch)
 Write a Stretch to the Cube.
 
void write (OriginalLabel &lab)
 This method will write an OriginalLabel object.
 
void write (const OriginalXmlLabel &lab)
 This method will write an OriginalXmlLabel object.
 
void write (History &history, const QString &name="IsisCube")
 Write an updated History to the Cube.
 
void write (const ImagePolygon &polygon)
 Write a polygon to the Cube.
 
void write (Buffer &wbuf)
 This method will write a buffer of data from the cube as specified by the contents of the Buffer object.
 
void setBaseMultiplier (double base, double mult)
 Used prior to the Create method, this will specify the base and multiplier for converting 8-bit/16-bit back and forth between 32-bit:
 
void setMinMax (double min, double max)
 Used prior to the Create method, this will compute a good base and multiplier value given the minimum/maximum range of the 32bit data.
 
void setByteOrder (ByteOrder byteOrder)
 Used prior to the Create method, this will specify the byte order of pixels, either least or most significant byte.
 
void setDimensions (int ns, int nl, int nb)
 Used prior to the Create method to specify the size of the cube.
 
void setExternalDnData (FileName cubeFileWithDnData)
 Used to set external dn data to cube.
 
void setFormat (Format format)
 Used prior to the Create method, this will specify the format of the cube, either band, sequential or tiled.
 
void setLabelsAttached (bool attached)
 Use prior to calling create, this sets whether or not to use separate label and data files.
 
void setLabelSize (int labelBytes)
 Used prior to the Create method, this will allocate a specific number of bytes in the label area for attached files.
 
void setPixelType (PixelType pixelType)
 Used prior to the Create method, this will specify the output pixel type.
 
void setVirtualBands (const QList< QString > &vbands)
 This allows the programmer to specify a subset of bands to work with.
 
void setVirtualBands (const std::vector< QString > &vbands)
 This is a deprecated version of setVirtualBands(const QList<QString> &).
 
void relocateDnData (FileName dnDataFile)
 Relocates the DN data for a cube to an external cube label file.
 
virtual int bandCount () const
 Returns the number of virtual bands for the cube.
 
double base () const
 Returns the base value for converting 8-bit/16-bit pixels to 32-bit.
 
ByteOrder byteOrder () const
 Returns the byte order/endian-ness of the cube file.
 
Cameracamera ()
 Return a camera associated with the cube.
 
FileName externalCubeFileName () const
 If this is an external cube label file, this will give you the cube dn file that this label references.
 
virtual QString fileName () const
 Returns the opened cube's filename.
 
Format format () const
 
virtual Histogramhistogram (const int &band=1, QString msg="Gathering histogram")
 This method returns a pointer to a Histogram object which allows the program to obtain and use various statistics and histogram information from the cube.
 
virtual Histogramhistogram (const int &band, const double &validMin, const double &validMax, QString msg="Gathering histogram")
 This method returns a pointer to a Histogram object which allows the program to obtain and use various statistics and histogram information from the cube.
 
Pvllabel () const
 Returns a pointer to the IsisLabel object associated with the cube.
 
int labelSize (bool actual=false) const
 Returns the number of bytes used by the label.
 
int lineCount () const
 
double multiplier () const
 Returns the multiplier value for converting 8-bit/16-bit pixels to 32-bit.
 
PixelType pixelType () const
 
virtual int physicalBand (const int &virtualBand) const
 This method will return the physical band number given a virtual band number.
 
Projectionprojection ()
 
int sampleCount () const
 
Statisticsstatistics (const int &band=1, QString msg="Gathering statistics")
 This method returns a pointer to a Statistics object which allows the program to obtain and use various statistics from the cube.
 
Statisticsstatistics (const int &band, const double &validMin, const double &validMax, QString msg="Gathering statistics")
 This method returns a pointer to a Statistics object which allows the program to obtain and use various statistics from the cube.
 
bool storesDnData () const
 This method returns a boolean value.
 
void addCachingAlgorithm (CubeCachingAlgorithm *)
 This will add the given caching algorithm to the list of attempted caching algorithms.
 
void clearIoCache ()
 This will clear excess RAM used for quicker IO in the cube.
 
bool deleteBlob (QString BlobName, QString BlobType)
 This method will delete a blob label object from the cube as specified by the Blob type and name.
 
void deleteGroup (const QString &group)
 Deletes a group from the cube labels.
 
PvlGroupgroup (const QString &group) const
 Read a group from the cube into a Label.
 
bool hasGroup (const QString &group) const
 Return if the cube has a specified group in the labels.
 
bool hasTable (const QString &name)
 Check to see if the cube contains a pvl table by the provided name.
 
bool hasBlob (const QString &name, const QString &type)
 Check to see if the cube contains a BLOB.
 
void putGroup (const PvlGroup &group)
 Adds a group in a Label to the cube.
 
void latLonRange (double &minLatitude, double &maxLatitude, double &minLongitude, double &maxLongitude)
 Returns the latitude and longitude range for the Cube.
 

Private Member Functions

void applyVirtualBandsToLabel ()
 Applies virtual bands to label.
 
void cleanUp (bool remove)
 This clears all of the allocated memory associated with an open cube.
 
void construct ()
 Initialize members from their initial undefined states.
 
QFile * dataFile () const
 This returns the QFile with cube DN data in it.
 
FileName realDataFileName () const
 This gets the file name of the file which actually contains the DN data.
 
void initialize ()
 This sets Cube to its default state: Native byte order Format = Tile PixelType = Real (4 bytes per pixel) Attached labels Label size = 65536 bytes.
 
void initCoreFromLabel (const Pvl &label)
 This function initializes the Cube core from a Pvl Label passed as a parameter.
 
void initLabelFromFile (FileName labelFileName, bool readWrite)
 This function initializes the Cube label from a file passed as a parameter.
 
void openCheck ()
 Throw an exception if the cube is not open.
 
Pvl realDataFileLabel () const
 Function to read data from a cube label and return it as a PVL object.
 
void reformatOldIsisLabel (const QString &oldCube)
 This is a helper, used by open(...), that handles opening Isis 2 cubes as if they were Isis cubes.
 
void writeLabels ()
 Write the Pvl labels to the cube's label file.
 

Private Attributes

QFile * m_labelFile
 This is the file that contains the labels always; if labels are attached then this contains the file data also.
 
QFile * m_dataFile
 This is only sometimes allocated.
 
CubeIoHandlerm_ioHandler
 This does the heavy lifting for cube DN IO and is always allocated when isOpen() is true.
 
ByteOrder m_byteOrder
 The byte order of the opened cube; if there is no open cube then this is the byte order that will be used when a new cube is created.
 
Format m_format
 If isOpen() then this is the IO format that the cube uses.
 
PixelType m_pixelType
 This is the pixel type on disk.
 
QMutex * m_mutex
 Basic thread-safety mutex; this class is not optimized for threads.
 
Cameram_camera
 Camera allocated from the camera() method.
 
Projectionm_projection
 Projection allocated from the projection() method.
 
FileNamem_labelFileName
 The full filename of the label file (.lbl or .cub)
 
FileNamem_dataFileName
 The full filename of the data file (.cub)
 
FileNamem_tempCube
 If open was called with an Isis 2 cube, then this will be the name of the imported ISIS cube.
 
FileNamem_formatTemplateFile
 Label pvl format template file (describes how to format labels)
 
bool m_attached
 True if labels are attached.
 
bool m_storesDnData
 True (most common case) when the cube DN data is inside the file we're writing to.
 
Pvlm_label
 The label if IsOpen(), otherwise NULL.
 
int m_labelBytes
 The maximum allowed size of the label; the allocated space.
 
int m_samples
 The sample count of the open cube or the cube that will be created.
 
int m_lines
 The line count of the open cube or the cube that will be created.
 
int m_bands
 The band count of the open cube or the cube that will be created.
 
double m_base
 The base of the open cube or the cube that will be created; does not apply if m_pixelType is Real.
 
double m_multiplier
 The multiplier of the open cube or the cube that will be created; does not apply if m_pixelType is Real.
 
QList< int > * m_virtualBandList
 If allocated, converts from physical on-disk band # to virtual band #.
 

Detailed Description

IO Handler for Isis Cubes.

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

Author
2003-02-14 Jeff Anderson
Todo
There are undocumented methods and private variables in the Cube class. Also, it needs an example.
History

2003-03-31 Jeff Anderson - updated unitTest truth file.

2003-05-16 Stuart Sides - modified schema from astrogeology...isis.astrogeology

2003-05-21 Jeff Anderson - added read/write methods to improve speed for IsisLine buffer managers. Also added error checks on reads, writes, and seeks.

2003-05-30 Jeff Anderson - added PhysicalBand method and updated unitTest.

2003-10-06 Jeff Anderson - added PVL to create method to allow for propagation of Pixel specifications.

2003-10-15 Jeff Anderson - fixed bad error check in PhysicalBand method.

2004-01-30 Jeff Anderson - added many Set methods. Major refractor of the class.

2004-02-12 Jeff Anderson - added pruning of the band bin group given the virtual band list.

2004-02-17 Jeff Anderson - modified the number of bands in the label if a virtual band list was given.

2004-03-01 Jeff Anderson - added ability to read Isis 2.1 cube format.

2004-04-01 Jeff Anderson - fixed bug swapping NULL cache tile for non-native cubes in move method.

2005-03-24 Jeff Anderson - Added methods to return a camera or projection associated with the cube.

2005-07-18 Elizabeth Ribelin - Fixed bug in method that returns a projection associated with the cube

2005-10-03 Elizabeth Miller - Added error check to Write(blob)

2006-02-24 Kris Becker - Made the destructor virtual to properly allow the class to be inherited.

2006-04-21 Jacob Danton - Modified the WriteLabel method to use the Pvl's format template abilities.

2006-05-17 Elizabeth Miller - Depricated CameraManger to CameraFactory

2006-07-10 Elizabeth Miller - Added max size preference

2006-11-28 Jeff Anderson - Fixed detached blob bug

2007-01-05 Jeff Anderson - Fixed bug when reading/writing outside cube

2007-02-07 Tracie Sucharski - Added ReOpen method

2008-05-09 Steven Lambright - Added Statistics, Histogram, PutGroup, GetGroup, DeleteGroup, HasGroup conveinience methods. Removed excess references to CubeInfo.

2008-05-27 Jeff Anderson - Fixed bug in open method where virtual bands were not handled correctly if a BandBin group did not exist

2008-06-09 Christopher Austin - Improved maximum cube size error message.

2008-06-11 Steven Lambright - Changed prototype for SetVirtualBands

2008-06-18 Christopher Austin - Fixed documentation errors

2008-08-11 Steven Lambright - Added another Statistics method which accepts a valid range – also added another Histogram method which accepts a bin/valid range (applies both).

2008-08-11 Steven Lambright - Fixed definition of IsisCubeDef, problem pointed out by "novas0x2a" (Support Board Member)

2008-12-15 Steven Koechle - Added a method to delete blobs from a cube

2008-12-17 Steven Koechle - BlobDelete method was broken, fixed

2009-06-30 Steven Lambright - Added "HasProjection" for uniform projection existance test

2010-03-22 Steven Lambright - Added a mutex for reading and writing, which makes these methods thread safe.

2011-03-23 Steven Lambright - Added ClearCache method.

2011-06-01 Jai Rideout and Steven Lambright - Updated API to conform to new Isis standards, re-implemented IO handler and implemented new caching algorithms that can automatically apply themselves when the behavior of the caller changes.

2011-06-27 Steven Lambright - Added addCachingAlgorithm

2011-07-08 Steven Lambright - projection() and camera() will now return NULL if the cube is not open, instead of crashing, references #161

2012-02-17 Steven Lambright - Made the read() method const. Added mutex lock calls around data file accesses.

2012-04-05 Stuart Sides and Steven Lambright - Added new constructor which immediately open the cube.

2012-07-02 Steven Lambright and Stuart Sides - Added copy() and added support for external cube label files (.ecub). This was done so that cubes can be imported into projects without copying the DN data. Also, multiple versions of SPICE will be save-able for one cube (multiple ecubs... again, not copying DN data). Fixes #961.

2012-09-06 Steven Lambright - Improved parsing of ^DnFile in the ecub format and simplified/optimized writeLabels().

2012-09-17 Steven Lambright - Fixed ASSERT in getRealDataFileName() to be in the correct place.

2012-10-26 Steven Lambright and Stuard Sides - Externel cube label files no longer allocate disk space for DN data when writing out blobs.

2012-11-06 Steven Lambright and Mathew Eis - Fixed (the lack of) deletion of temporary files in the unit test. Fixes #1009.

2012-12-31 Steven Lambright - Removed 'get' prefix from accessors. Fixes #1356.

2014-06-20 Ian Humphrey - Added checks to statistics() and histogram() to throw an error if the cube is unopened. Fixes #2085.

2014-10-06 Ian Humphrey - Added case to unittest when chunk dimensions are the same as the buffer shape to ensure virtual bands accessed correctly. Added cases to test creating bsq and large bsq cubes. References #1689.

2015-01-30 Ian Humphrey - Deallocated copied cubes in unittest. References #2082.

2015-06-22 Makayla Shepherd - Using putGroup() a group on the label of a read-only cube now throws an error.

2015-09-02 Tyler Wilson - Commented out first call to SetValidRange in the call to the historgram function. Also commented out a call to Histogram::SetBinRange() because this function no longer exists in Histogram. See Ref. #2188.

2017-06-08 Chris Combs - Made "Failed to create" error messages more descriptive. Fixes #833.

2017-09-22 Cole Neubauer - Fixed documentation. References #4807

2018-01-04 Tracie Sucharski - Allow relative paths that are not "." in the DnFile keyword for ecubs. Changes to open to set m_dataFileName for ecubs, and changed realDataFileName() to return the absolute path if it is relative. Changed realDataFileLabel to call realDataFileName to make sure we get absolute path. Fixes #5276.

2018-01-18 Summer Stapleton - Updated error message in create() to address when an IsisPreference file cannot be found. Fixes #5145.

2018-11-16 Jesse Mapel - Made several methods virtual for mocking.

2019-06-15 Kristin Berry - Added latLonRange method to return the valid lat/lon rage of the cube. The values in the mapping group are not sufficiently accurate for some purposes.

2021-02-17 Jesse Mapel - Added hasBlob method to check for any type of BLOB.

2021-10-18 Evin Dunn - Switch to single quotes for 'Environment and Preferences' in Cube::create() exception

Definition at line 168 of file Cube.h.

Member Enumeration Documentation

◆ Format

These are the possible storage formats of ISIS cubes.

There is an internal IO handler for each one of these.

Enumerator
Bsq 

Cubes are stored in band-sequential format, that is the order of the pixels in the file (on disk) is:

    S1,L1,B1
    S2,L1,B1
    and so on until ...
    SN,L1,B1
    S1,L2,B1
    and so on until ...
    S1,LN,B1
    S1,L1,B2
    S2,L1,B2
    and so on until ...
    S1,L1,BN
  

The idea is the cubes are stored left-to-right, top-to-bottom, then front-to-back.

Tile 

Cubes are stored in tile format, that is the order of the pixels in the file (on disk) is BSQ within a given sub-area defined by the Tile IO handler.

Typically these tiles are around 1MB for efficiency.

The idea is the cubes are stored left-to-right, top-to-bottom inside the tiles (which have 1 band). The tiles are themselves in BSQ order also. Please note that this can cause cubes to be larger on disk due to the tile size not being evenly divisible into the cube size.

Cube:

------------------------------
|Tile *Tile *Tile *Tile *Tile|*
|  0  *  1  *  2  *  3  *  4 |*
|     *     *     *     *    |*
|****************************|*
|Tile *Tile *Tile *Tile *Tile|*
|  5  *  6  *  7  *  8  *  9 |*
|     *     *     *     *    |*
|****************************|*
|Tile *Tile *Tile *Tile *Tile|*
------------------------------*
* 10  * 11  * 12  * 13  * 14  *
*******************************

The symbol '*' denotes tile boundaries. The symbols '-' and '|' denote cube boundaries.

Definition at line 179 of file Cube.h.

Constructor & Destructor Documentation

◆ Cube() [1/2]

Isis::Cube::Cube ( )

Constructs a Cube object.

Definition at line 49 of file Cube.cpp.

References construct().

Referenced by copy().

◆ Cube() [2/2]

Isis::Cube::Cube ( const FileName & fileName,
QString access = "r" )

Construct a cube and open it for reading or reading/writing.

Parameters
fileNameName of the cube file to open. Environment variables in the filename will be automatically expanded.
accessDefines how the cube will be opened. Either read-only "r" or read-write "rw".

Definition at line 61 of file Cube.cpp.

References construct(), fileName(), and open().

◆ ~Cube()

Isis::Cube::~Cube ( )
virtual

Destroys the Cube object.

Definition at line 159 of file Cube.cpp.

References close(), m_camera, m_formatTemplateFile, m_mutex, and m_projection.

Member Function Documentation

◆ addCachingAlgorithm()

void Isis::Cube::addCachingAlgorithm ( CubeCachingAlgorithm * algorithm)

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.

RegionalCachingAlgorithm is the only initial caching algorithm and works well for most cases. The caching algorithm only apply to the opened Cube and is reset by any changes to the open status of the Cube.

This method takes ownership of algorithm.

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

Definition at line 1928 of file Cube.cpp.

References Isis::CubeIoHandler::addCachingAlgorithm(), isOpen(), m_ioHandler, and Isis::IException::Programmer.

Referenced by Isis::DemShape::DemShape(), and Isis::ProcessMapMosaic::StartProcess().

◆ applyVirtualBandsToLabel()

void Isis::Cube::applyVirtualBandsToLabel ( )
private

Applies virtual bands to label.

Definition at line 2084 of file Cube.cpp.

References Isis::PvlKeyword::clear(), Isis::PvlObject::findObject(), m_bands, m_label, m_virtualBandList, physicalBand(), and Isis::toString().

Referenced by open().

◆ attachSpiceFromIsd()

void Isis::Cube::attachSpiceFromIsd ( nlohmann::json Isd)

Definition at line 1465 of file Cube.cpp.

◆ bandCount()

◆ base()

double Isis::Cube::base ( ) const

Returns the base value for converting 8-bit/16-bit pixels to 32-bit.

\[ out = in * multiplier + base \]

Returns
double The base value for converting 8-bit/16-bit pixels to 32-bit.

Definition at line 1433 of file Cube.cpp.

References m_base.

Referenced by copy(), and setBaseMultiplier().

◆ byteOrder()

ByteOrder Isis::Cube::byteOrder ( ) const

Returns the byte order/endian-ness of the cube file.

Cubes in a native byte order are quicker to read/write than those who must correct their byte order.

Returns
The byte order/endian-ness of the cube file

Definition at line 1445 of file Cube.cpp.

References m_byteOrder.

Referenced by setByteOrder().

◆ camera()

Camera * Isis::Cube::camera ( )

Return a camera associated with the cube.

The generation of the camera can throw an exception, so you might want to catch errors if that interests you.

Returns
A camera based on the open cube

Definition at line 1457 of file Cube.cpp.

References Isis::CameraFactory::Create(), isOpen(), and m_camera.

Referenced by Isis::StereoTool::calculateElevation(), Isis::CameraStatistics::CameraStatistics(), Isis::ImportImagesWorkOrder::importConfirmedImages(), Isis::ImagePolygon::initCube(), latLonRange(), Isis::Chip::Load(), Isis::SunShadowTool::mouseButtonPress(), Isis::PhotometricFunction::PhotometricFunction(), Isis::SunShadowTool::recalculateShadowHeight(), and Isis::CameraPointInfo::SetCube().

◆ cleanUp()

void Isis::Cube::cleanUp ( bool removeIt)
private

This clears all of the allocated memory associated with an open cube.

Parameters
removeItIf true, the input cube will be removed from disk

Definition at line 2112 of file Cube.cpp.

References Isis::FileName::expanded(), initialize(), m_dataFile, m_dataFileName, m_ioHandler, m_label, m_labelFile, m_labelFileName, m_tempCube, and m_virtualBandList.

Referenced by close(), create(), initLabelFromFile(), open(), and writeLabels().

◆ clearIoCache()

void Isis::Cube::clearIoCache ( )

This will clear excess RAM used for quicker IO in the cube.

This should only be called if you need hundreds of cubes opened simultaneously. The IO cache will start growing again on future IO's.

Definition at line 1944 of file Cube.cpp.

References Isis::CubeIoHandler::clearCache(), m_ioHandler, and m_mutex.

◆ close()

void Isis::Cube::close ( bool removeIt = false)

Closes the cube and updates the labels.

Optionally, it deletes the cube if requested.

Parameters
removeIt(Default value = false) Indicates if the file should be removed/deleted.

Definition at line 255 of file Cube.cpp.

References cleanUp(), isOpen(), isReadWrite(), and writeLabels().

Referenced by Isis::ProcessMosaic::EndProcess(), Isis::ImageOverlapSet::FindImageOverlaps(), fromIsd(), fromLabel(), Isis::Process::PropagateTables(), reopen(), Isis::ProcessMapMosaic::RingsSetOutputCube(), Isis::ProcessMapMosaic::SetOutputCube(), Isis::ProcessMosaic::StartProcess(), ~Cube(), and Isis::ProcessMosaic::~ProcessMosaic().

◆ construct()

void Isis::Cube::construct ( )
private

Initialize members from their initial undefined states.

Definition at line 2160 of file Cube.cpp.

References initialize(), m_camera, m_dataFile, m_dataFileName, m_formatTemplateFile, m_ioHandler, m_label, m_labelFile, m_labelFileName, m_mutex, m_projection, m_tempCube, and m_virtualBandList.

Referenced by Cube(), and Cube().

◆ copy()

◆ create() [1/2]

void Isis::Cube::create ( const QString & cubeFileName)

This method will create an isis cube for writing.

The programmer should make appropriate calls to Set methods before invoking Create. If none are made there are internal defaults which are:

Dimensions 512x512x1
ByteOrder Matches architecture of host machine
Attached From user preference file
Label Size 65536 bytes
Format Tiled
Base 0.0
Multiplier 1.0
Format
These are the possible storage formats of ISIS cubes.
Definition Cube.h:179
ByteOrder
Tests the current architecture for byte order.
Definition Endian.h:42
PixelType
Enumerations for Isis Pixel Types.
Definition PixelType.h:27
Parameters
cubeFileNameName of the cube file to open. If the extenstion ".cub" is not given it will be appended (i.e., the extension of .cub is forced). Environment variables in the filename will be automatically expanded as well.

Definition at line 409 of file Cube.cpp.

References Isis::PvlObject::addObject(), Bsq, cleanUp(), dataFile(), Isis::FileName::expanded(), Isis::IException::Io, isOpen(), m_attached, m_bands, m_base, m_byteOrder, m_dataFile, m_dataFileName, m_format, m_ioHandler, m_label, m_labelBytes, m_labelFile, m_labelFileName, m_lines, m_multiplier, m_pixelType, m_samples, m_storesDnData, m_virtualBandList, Isis::FileName::original(), Isis::PixelTypeName(), Isis::IException::Programmer, realDataFileLabel(), realDataFileName(), Isis::SizeOf(), Isis::toString(), Isis::IException::Unknown, Isis::CubeIoHandler::updateLabels(), Isis::IException::User, and writeLabels().

Referenced by copy(), create(), Isis::ImageImporter::createOutput(), fromLabel(), Isis::Process::SetOutputCube(), and Isis::ProcessMosaic::StartProcess().

◆ create() [2/2]

void Isis::Cube::create ( const QString & cubeFileName,
const CubeAttributeOutput & att )

This method will create an isis cube for writing.

The programmer should make appropriate calls to Set methods before invoking Create. If none are made there are internal defaults which are:

Dimensions 512x512x1
ByteOrder Matches architecture of host machine
Attached From user preference file
Label Size 65536 bytes
Format Tiled
Base 0.0
Multiplier 1.0
Parameters
cubeFileNameName of the cube file to open. If the extenstion ".cub" is not given it will be appended (i.e., the extension of .cub is forced). Environment variables in the filename will be automatically expanded as well.
attCubeAttributeOutput

Definition at line 597 of file Cube.cpp.

References Isis::AttachedLabel, create(), setByteOrder(), setFormat(), setLabelsAttached(), setMinMax(), and setPixelType().

◆ dataFile()

QFile * Isis::Cube::dataFile ( ) const
private

This returns the QFile with cube DN data in it.

NULL will be returned if no files are opened.

Returns
A file for cube pixel data I/O

Definition at line 2191 of file Cube.cpp.

References m_dataFile, and m_labelFile.

Referenced by create(), and open().

◆ deleteBlob()

bool Isis::Cube::deleteBlob ( QString BlobName,
QString BlobType )

This method will delete a blob label object from the cube as specified by the Blob type and name.

If blob does not exist it will do nothing and return false.

Parameters
BlobNameblob to be deleted
BlobTypetype of blob to search for (Polygon, Table, etc)
Returns
boolean if it found the blob and deleted it.

Definition at line 1961 of file Cube.cpp.

References Isis::PvlObject::deleteObject(), m_label, Isis::PvlObject::object(), and Isis::PvlObject::objects().

Referenced by Isis::ProcessMosaic::StartProcess().

◆ deleteGroup()

void Isis::Cube::deleteGroup ( const QString & group)

Deletes a group from the cube labels.

If the group does not exist nothing happens; otherwise the group is removed. This will only work on output cubes, therefore, input cubes will not be updated.

Parameters
[out]groupName of the group to delete.

Definition at line 1983 of file Cube.cpp.

References Isis::PvlObject::findObject(), group(), and label().

◆ externalCubeFileName()

FileName Isis::Cube::externalCubeFileName ( ) const

If this is an external cube label file, this will give you the cube dn file that this label references.

Returns
The cube that this external label file references

Definition at line 1541 of file Cube.cpp.

References Isis::PvlObject::findObject(), isOpen(), m_label, storesDnData(), and Isis::IException::Unknown.

Referenced by Isis::ControlPointEditWidget::createControlPoint(), Isis::Image::deleteFromDisk(), and Isis::Shape::deleteFromDisk().

◆ fileName()

◆ format()

Cube::Format Isis::Cube::format ( ) const
Returns
the cube's storage format. If no cube is opened yet, then this is the storage format that will be used if create(...) is called.

Definition at line 1581 of file Cube.cpp.

References m_format.

Referenced by setFormat().

◆ fromIsd() [1/2]

void Isis::Cube::fromIsd ( const FileName & fileName,
FileName & labelFile,
FileName & isdFile,
QString access )

Initialize Cube data from a PVL label and JSON ISD.

Parameters
fileNameName of the cube file to open. Environment variables in the filename will be automatically expanded.
labelFilePath to PVL label representing the new Cube label
isdPathPath to Ale compatible ISD
accessDefines how the cube will be opened. Either read-only "r" or read-write "rw".

Definition at line 116 of file Cube.cpp.

References fileName(), fromIsd(), Isis::IException::Io, label(), and reopen().

◆ fromIsd() [2/2]

void Isis::Cube::fromIsd ( const FileName & fileName,
Pvl & label,
nlohmann::json & isd,
QString access )

Initialize Cube data from a PVL label and JSON ISD.

Parameters
fileNameName of the cube file to open. Environment variables in the filename will be automatically expanded.
labelPVL label object representing the new Cube label
isdJSON object containing Ale compatible ISD
accessDefines how the cube will be opened. Either read-only "r" or read-write "rw".

Definition at line 98 of file Cube.cpp.

References close(), fileName(), fromLabel(), label(), and open().

Referenced by fromIsd().

◆ fromLabel()

void Isis::Cube::fromLabel ( const FileName & fileName,
Pvl & label,
QString access )

Initialize Cube data from a PVL label.

Parameters
fileNameName of the cube file to open. Environment variables in the filename will be automatically expanded.
labelPVL label object representing the new Cube label
accessDefines how the cube will be opened. Either read-only "r" or read-write "rw".

Definition at line 75 of file Cube.cpp.

References close(), create(), fileName(), Isis::PvlObject::findObject(), initCoreFromLabel(), label(), open(), and putGroup().

Referenced by fromIsd().

◆ group()

PvlGroup & Isis::Cube::group ( const QString & group) const

Read a group from the cube into a Label.

If the group does not exist an exception will be thrown.

Parameters
[out]groupName of the group to get
Returns
(PvlGroup) Label which will contain the requested group.

Definition at line 1997 of file Cube.cpp.

References Isis::PvlObject::findObject(), group(), and label().

Referenced by deleteGroup(), group(), hasGroup(), Isis::HiLab::HiLab(), putGroup(), and Isis::CubeViewport::setTrackingCube().

◆ hasBlob()

bool Isis::Cube::hasBlob ( const QString & name,
const QString & type )

Check to see if the cube contains a BLOB.

Parameters
nameThe name of the BLOB to search for
typeThe type of the BLOB to search for
Returns
bool True if the BLOB was found

Definition at line 2025 of file Cube.cpp.

References label(), Isis::PvlObject::object(), and Isis::PvlObject::objects().

Referenced by Isis::CameraFactory::Create(), hasTable(), and Isis::Spice::Spice().

◆ hasGroup()

bool Isis::Cube::hasGroup ( const QString & group) const

Return if the cube has a specified group in the labels.

Parameters
[out]groupName of the group to check.
Returns
(bool) True if the cube has the specified group, false if not.

Definition at line 2010 of file Cube.cpp.

References Isis::PvlObject::findObject(), group(), and label().

Referenced by Isis::CubeViewport::CubeViewport(), and latLonRange().

◆ hasTable()

bool Isis::Cube::hasTable ( const QString & name)

Check to see if the cube contains a pvl table by the provided name.

Parameters
nameThe name of the pvl table to search for
Returns
bool True if the pvl table was found

Definition at line 2049 of file Cube.cpp.

References hasBlob().

Referenced by Isis::ClipperNacRollingShutterCamera::ClipperNacRollingShutterCamera().

◆ histogram() [1/2]

Histogram * Isis::Cube::histogram ( const int & band,
const double & validMin,
const double & validMax,
QString msg = "Gathering histogram" )
virtual

This method returns a pointer to a Histogram object which allows the program to obtain and use various statistics and histogram information from the cube.

Cube does not retain ownership of the returned pointer - please delete it when you are done with it.

Parameters
[in]bandReturns the histogram for the specified band. If the user specifies 0 for this parameter, the method will loop through every band in the cube and accumulate a histogram from all of them
validMinThe start of the bin range and valid data range for the histogram
validMaxThe end of the bin range and valid data range for the histogram
msgThe message to display with the percent process while gathering histogram data
Returns
(Histogram) A pointer to a Histogram object.
Exceptions
ProgrammerErrorBand was less than zero or more than the number of bands in the cube.

Definition at line 1635 of file Cube.cpp.

References bandCount(), Isis::Progress::CheckStatus(), Isis::Buffer::DoubleBuffer(), isOpen(), lineCount(), Isis::IException::Programmer, read(), Isis::LineManager::SetLine(), Isis::Progress::SetMaximumSteps(), Isis::Progress::SetText(), Isis::Buffer::size(), Isis::ValidMaximum, and Isis::ValidMinimum.

◆ histogram() [2/2]

Histogram * Isis::Cube::histogram ( const int & band = 1,
QString msg = "Gathering histogram" )
virtual

This method returns a pointer to a Histogram object which allows the program to obtain and use various statistics and histogram information from the cube.

Cube does not retain ownership of the returned pointer - please delete it when you are done with it.

Parameters
[in]band(Default value is 1) Returns the histogram for the specified band.If the user specifies 0 for this parameter, the method will loop through every band in the cube and accumulate a histogram from all of them
msgThe message to display with the percent process while gathering histogram data
Returns
(Histogram) A pointer to a Histogram object.
Exceptions
IsisProgrammerErrorBand was less than zero or more than the number of bands in the cube.

Definition at line 1605 of file Cube.cpp.

References histogram(), Isis::ValidMaximum, and Isis::ValidMinimum.

Referenced by histogram().

◆ initCoreFromLabel()

void Isis::Cube::initCoreFromLabel ( const Pvl & label)
private

This function initializes the Cube core from a Pvl Label passed as a parameter.

Parameters
labelPvl label to initialize from

Definition at line 2293 of file Cube.cpp.

References Bsq, Isis::PvlObject::findObject(), initCoreFromLabel(), label(), m_bands, m_base, m_byteOrder, m_format, m_labelFileName, m_lines, m_multiplier, m_pixelType, m_samples, Isis::FileName::path(), Isis::PixelTypeEnumeration(), and Tile.

Referenced by fromLabel(), initCoreFromLabel(), open(), and setExternalDnData().

◆ initialize()

void Isis::Cube::initialize ( )
private

This sets Cube to its default state: Native byte order Format = Tile PixelType = Real (4 bytes per pixel) Attached labels Label size = 65536 bytes.

samples, lines, bands unset

Base = 0 Multiplier = 1.0

Definition at line 2268 of file Cube.cpp.

References Isis::IsBigEndian(), m_attached, m_bands, m_base, m_byteOrder, m_format, m_labelBytes, m_lines, m_multiplier, m_pixelType, m_samples, m_storesDnData, and Tile.

Referenced by cleanUp(), and construct().

◆ initLabelFromFile()

void Isis::Cube::initLabelFromFile ( FileName labelFileName,
bool readWrite )
private

This function initializes the Cube label from a file passed as a parameter.

Parameters
labelFileNameFileName to initialize from
readWritebool that determines whether the label is an old isis label and needs to be reformatted

Definition at line 2337 of file Cube.cpp.

References cleanUp(), Isis::FileName::expanded(), Isis::Message::FileOpen(), Isis::PvlObject::hasKeyword(), Isis::IException::Io, m_label, m_labelFile, m_labelFileName, Isis::PvlObject::objects(), Isis::FileName::original(), and reformatOldIsisLabel().

Referenced by open(), and setExternalDnData().

◆ isOpen()

bool Isis::Cube::isOpen ( ) const

Test if a cube file has been opened/created.

Returns
True if a cube has been opened and I/O operations are allowed

Definition at line 182 of file Cube.cpp.

References m_ioHandler, and open().

Referenced by addCachingAlgorithm(), camera(), close(), copy(), create(), Isis::CubeViewport::CubeViewport(), externalCubeFileName(), fileName(), histogram(), isReadOnly(), open(), openCheck(), projection(), read(), read(), relocateDnData(), Isis::Process::SetInputCube(), statistics(), write(), write(), and writeLabels().

◆ isProjected()

bool Isis::Cube::isProjected ( ) const

Returns true if the labels of the cube appear to have a valid mapping group.

This returning true does not guarantee that the cube can project or that the Projection() method will succeed.

Returns
bool True if the file should have a valid projection

Definition at line 197 of file Cube.cpp.

References Isis::PvlObject::findObject(), and label().

◆ isReadOnly()

bool Isis::Cube::isReadOnly ( ) const

Test if the opened cube is read-only, that is write operations will fail if this is true.

A cube must be opened in order to call this method.

Returns
True if the cube is opened read-only

Definition at line 208 of file Cube.cpp.

References isOpen(), m_labelFile, and Isis::IException::Programmer.

Referenced by isReadWrite(), putGroup(), and write().

◆ isReadWrite()

bool Isis::Cube::isReadWrite ( ) const

Test if the opened cube is read-write, that is read and write operations should succeed if this is true.

A cube must be opened in order to call this method.

Returns
True if the cube is opened read-write

Definition at line 230 of file Cube.cpp.

References isReadOnly().

Referenced by close(), copy(), Isis::ProcessByBrick::ProcessCubeInPlace(), Isis::ProcessByBrick::StartProcess(), and Isis::ProcessByBrick::StartProcess().

◆ label()

Pvl * Isis::Cube::label ( ) const

Returns a pointer to the IsisLabel object associated with the cube.

Modifications made to the label will be written when the file is closed if it was opened read-write or created. Take care not to mangle the Core Object as this can produce unexpected results when a new attempt is made to open the file. This pointer is invalid as soon as the cube is closed.

Returns
Pvl Pointer to the Label object associated with the cube.

Definition at line 1707 of file Cube.cpp.

References m_label.

Referenced by Isis::AlphaCube::AlphaCube(), Isis::ApolloMetricCamera::ApolloMetricCamera(), Isis::ApolloPanoramicCamera::ApolloPanoramicCamera(), Isis::Camera::Camera(), Isis::CameraFactory::CameraVersion(), Isis::Chandrayaan1M3Camera::Chandrayaan1M3Camera(), Isis::ClipperNacRollingShutterCamera::ClipperNacRollingShutterCamera(), Isis::ClipperPushBroomCamera::ClipperPushBroomCamera(), Isis::ClipperWacFcCamera::ClipperWacFcCamera(), Isis::ObservationNumber::Compose(), Isis::SerialNumber::Compose(), copy(), Isis::CameraFactory::Create(), Isis::ProjectionFactory::CreateFromCube(), Isis::CrismCamera::CrismCamera(), Isis::CTXCamera::CTXCamera(), Isis::DawnFcCamera::DawnFcCamera(), Isis::DawnVirCamera::DawnVirCamera(), deleteGroup(), Isis::DemShape::DemShape(), Isis::SpectralPlotWindow::drawBandMarkers(), fromIsd(), fromIsd(), fromLabel(), Isis::CubeViewport::getBandFilterName(), Isis::SpectralPlotTool::getSpectralStatistics(), group(), hasBlob(), hasGroup(), Isis::HayabusaAmicaCamera::HayabusaAmicaCamera(), Isis::HayabusaNirsCamera::HayabusaNirsCamera(), Isis::HiresCamera::HiresCamera(), Isis::HiriseCamera::HiriseCamera(), Isis::HrscCamera::HrscCamera(), Isis::Hyb2OncCamera::Hyb2OncCamera(), Isis::IdealCamera::IdealCamera(), Isis::ImageImporter::import(), Isis::ImportImagesWorkOrder::importConfirmedImages(), Isis::CSMCamera::init(), Isis::Image::initCamStats(), Isis::Shape::initCamStats(), initCoreFromLabel(), Isis::Image::isFootprintable(), Isis::Shape::isFootprintable(), isProjected(), Isis::IssNACamera::IssNACamera(), Isis::IssWACamera::IssWACamera(), Isis::JunoCamera::JunoCamera(), Isis::KaguyaMiCamera::KaguyaMiCamera(), Isis::KaguyaTcCamera::KaguyaTcCamera(), Isis::Kernels::Kernels(), Isis::LoHighCamera::LoHighCamera(), Isis::LoMediumCamera::LoMediumCamera(), Isis::LroNarrowAngleCamera::LroNarrowAngleCamera(), Isis::LroWideAngleCamera::LroWideAngleCamera(), Isis::LwirCamera::LwirCamera(), Isis::MarciCamera::MarciCamera(), Isis::Mariner10Camera::Mariner10Camera(), Isis::MdisCamera::MdisCamera(), Isis::MexHrscSrcCamera::MexHrscSrcCamera(), Isis::MiniRF::MiniRF(), Isis::MocNarrowAngleCamera::MocNarrowAngleCamera(), Isis::MocWideAngleCamera::MocWideAngleCamera(), Isis::MsiCamera::MsiCamera(), Isis::NewHorizonsLeisaCamera::NewHorizonsLeisaCamera(), Isis::NewHorizonsLorriCamera::NewHorizonsLorriCamera(), Isis::NewHorizonsMvicFrameCamera::NewHorizonsMvicFrameCamera(), Isis::NewHorizonsMvicTdiCamera::NewHorizonsMvicTdiCamera(), Isis::NirCamera::NirCamera(), Isis::OsirisRexOcamsCamera::OsirisRexOcamsCamera(), projection(), Isis::Process::PropagateTables(), putGroup(), read(), Isis::MocLabels::ReadLabels(), realDataFileLabel(), Isis::ProjectionFactory::RingsCreateFromCube(), Isis::ProcessMapMosaic::RingsSetOutputCube(), Isis::ProcessMapMosaic::RingsSetOutputCube(), Isis::RosettaOsirisCamera::RosettaOsirisCamera(), Isis::RosettaVirtisCamera::RosettaVirtisCamera(), Isis::BandTool::setBandBin(), Isis::Process::SetOutputCube(), Isis::ProcessMapMosaic::SetOutputCube(), Isis::ProcessMapMosaic::SetOutputCube(), Isis::Spice::Spice(), Isis::SsiCamera::SsiCamera(), Isis::ProcessMosaic::StartProcess(), Isis::TgoCassisCamera::TgoCassisCamera(), Isis::ThemisIrCamera::ThemisIrCamera(), Isis::ThemisVisCamera::ThemisVisCamera(), Isis::UniversalGroundMap::UniversalGroundMap(), Isis::AlphaCube::UpdateGroup(), Isis::UvvisCamera::UvvisCamera(), Isis::VikingCamera::VikingCamera(), Isis::VimsCamera::VimsCamera(), and Isis::VoyagerCamera::VoyagerCamera().

◆ labelsAttached()

bool Isis::Cube::labelsAttached ( ) const

Test if labels are attached.

If a cube is open, then this indicates whether or not the opened cube's labels are attached. If a cube is not open, then this indicates whether or not a cube will be created with attached labels if create(...) is called.

Returns
True for attached labels, false for detached

Definition at line 243 of file Cube.cpp.

References m_attached.

◆ labelSize()

int Isis::Cube::labelSize ( bool actual = false) const

Returns the number of bytes used by the label.

Parameters
actualTrue for consumed size, false for allocated size (i.e. the number of bytes in the cube set aside for the label).
Returns
int the number of bytes used by the label.

Definition at line 1719 of file Cube.cpp.

References labelSize(), m_label, and m_labelBytes.

Referenced by copy(), labelSize(), open(), and Isis::Process::SetOutputCube().

◆ latLonRange()

void Isis::Cube::latLonRange ( double & minLatitude,
double & maxLatitude,
double & minLongitude,
double & maxLongitude )

Returns the latitude and longitude range for the Cube.

More accurate than the minimum and maximum latitude and longitude from the mapping group.

Parameters
[out]minLatitudeminimum latitude present in the cube
[out]maxLatitudemaximum latitude present in the cube
[out]minLongitudeminimum longitude present in the cube
[out]maxLongitudemaximum longitude present in the cube

Definition at line 2516 of file Cube.cpp.

References camera(), hasGroup(), lineCount(), projection(), sampleCount(), Isis::IException::Unknown, and Isis::IException::User.

◆ lineCount()

int Isis::Cube::lineCount ( ) const

◆ multiplier()

double Isis::Cube::multiplier ( ) const

Returns the multiplier value for converting 8-bit/16-bit pixels to 32-bit.

\[ out = in * multiplier + base \]

Returns
double The multiplier value for converting 8-bit/16-bit pixels to 32-bit.

Definition at line 1754 of file Cube.cpp.

References m_multiplier.

Referenced by copy().

◆ open()

void Isis::Cube::open ( const QString & cubeFileName,
QString access = "r" )

This method will open an existing isis cube for reading or reading/writing.

Any input cube attributes following the file name will be applied.

Parameters
[in]cubeFileNameName of the cube file to open. Environment variables in the filename will be automatically expanded.
[in]access(Default value of "r") Defines how the cube will be accessed. Either read-only "r" or read-write "rw".

Definition at line 622 of file Cube.cpp.

References applyVirtualBandsToLabel(), Bsq, cleanUp(), dataFile(), Isis::FileName::expanded(), Isis::PvlObject::findObject(), initCoreFromLabel(), initLabelFromFile(), Isis::IException::Io, isOpen(), labelSize(), m_attached, m_dataFile, m_dataFileName, m_format, m_ioHandler, m_label, m_labelBytes, m_labelFile, m_labelFileName, m_storesDnData, m_virtualBandList, Isis::FileName::path(), Isis::IException::Programmer, realDataFileLabel(), realDataFileName(), and setVirtualBands().

Referenced by Isis::Workspace::addCubeViewport(), Isis::Workspace::addCubeViewportFromList(), Isis::Equalization::calculateOverlapStatistics(), Isis::CameraStatistics::CameraStatistics(), Isis::ShapeModelFactory::create(), Cube(), Isis::Equalization::errorCheck(), Isis::HiEqualization::errorCheck(), Isis::ImageOverlapSet::FindImageOverlaps(), fromIsd(), fromLabel(), Isis::GisGeometry::GisGeometry(), isOpen(), Isis::Blobber::load(), Isis::Equalization::loadInputs(), Isis::Process::PropagateTables(), reopen(), Isis::ProcessMapMosaic::RingsSetOutputCube(), Isis::ProcessMapMosaic::RingsSetOutputCube(), Isis::ProcessMapMosaic::RingsSetOutputCube(), Isis::FileTool::saveAsReducedCube(), Isis::MatchTool::selectLeftMeasure(), Isis::MatchTool::selectRightMeasure(), Isis::Process::SetInputCube(), Isis::ProcessMapMosaic::SetOutputCube(), Isis::ProcessMapMosaic::SetOutputCube(), Isis::ProcessMapMosaic::SetOutputCube(), Isis::ProcessMosaic::StartProcess(), Isis::GuiCubeParameter::ViewCube(), and Isis::GuiCubeParameter::ViewLabel().

◆ openCheck()

void Isis::Cube::openCheck ( )
private

Throw an exception if the cube is not open.

Definition at line 2443 of file Cube.cpp.

References isOpen(), and Isis::IException::Programmer.

Referenced by setBaseMultiplier(), setByteOrder(), setDimensions(), setFormat(), setLabelsAttached(), setLabelSize(), setMinMax(), setPixelType(), and setVirtualBands().

◆ physicalBand()

int Isis::Cube::physicalBand ( const int & virtualBand) const
virtual

This method will return the physical band number given a virtual band number.

Physical and virtual bands always match unless the programmer made a call to SetVirtualBand prior to opening the cube.

Parameters
virtualBandVirtual band to translate to physical band.
Returns
int The physical band number.

Definition at line 1779 of file Cube.cpp.

References m_virtualBandList, physicalBand(), Isis::IException::Programmer, and Isis::toString().

Referenced by applyVirtualBandsToLabel(), Isis::CubeViewport::getAllWhatsThisInfo(), physicalBand(), and Isis::CubeViewport::updateWhatsThis().

◆ pixelType()

◆ projection()

Projection * Isis::Cube::projection ( )
Returns
a projection associated with the cube. The generation of the projection can throw an exception, so you might want to catch errors if that interests you.

Definition at line 1800 of file Cube.cpp.

References Isis::ProjectionFactory::CreateFromCube(), isOpen(), label(), and m_projection.

Referenced by Isis::CubeViewport::CubeViewport(), Isis::DemShape::DemShape(), Isis::ImagePolygon::initCube(), latLonRange(), Isis::Chip::Load(), Isis::OverlapStatistics::OverlapStatistics(), and Isis::ProcessMapMosaic::StartProcess().

◆ putGroup()

void Isis::Cube::putGroup ( const PvlGroup & group)

Adds a group in a Label to the cube.

If the group already exists in the cube it will be completely overwritten. This will only work on output cubes, therefore, input cubes will not be updated.

Parameters
[in]groupLabel containing the group to put.

Definition at line 2062 of file Cube.cpp.

References fileName(), Isis::PvlObject::findObject(), group(), isReadOnly(), label(), Isis::PvlContainer::name(), and Isis::IException::Programmer.

Referenced by fromLabel(), Isis::ProcessMapMosaic::RingsSetOutputCube(), Isis::ProcessMapMosaic::RingsSetOutputCube(), Isis::ProcessMapMosaic::SetOutputCube(), and Isis::ProcessMapMosaic::SetOutputCube().

◆ read() [1/2]

void Isis::Cube::read ( Blob & blob,
const std::vector< PvlKeyword > keywords = std::vector<PvlKeyword>() ) const

This method will read data from the specified Blob object.

Parameters
[in]blobThe Blob data to be loaded
Returns
(type)return description

Definition at line 813 of file Cube.cpp.

References Isis::CubeIoHandler::dataFileMutex(), isOpen(), label(), m_ioHandler, m_labelFileName, m_mutex, m_tempCube, and Isis::IException::Programmer.

Referenced by Isis::ProcessMosaic::BandComparison(), Isis::CubeViewport::bluePixel(), Isis::Process::CalculateStatistics(), copy(), Isis::CSMCamera::CSMCamera(), Isis::InterestOperator::FindOverlapByImageFootPrint(), Isis::MosaicSceneItem::getPixelValue(), Isis::CameraPointInfo::GetPointInfo(), Isis::SpectralPlotTool::getSpectralStatistics(), Isis::MosaicSceneItem::getStretch(), Isis::CubeViewport::grayPixel(), Isis::CubeViewport::greenPixel(), Isis::StretchTool::histFromCube(), histogram(), Isis::ImageHistogram::ImageHistogram(), Isis::DemShape::localRadius(), Isis::ProcessByBrick::ProcessCubeInPlaceFunctor< T >::operator()(), Isis::ProcessByBrick::ProcessCubeFunctor< T >::operator()(), Isis::Nearest::operator()(), Isis::Average::operator()(), Isis::OverlapStatistics::OverlapStatistics(), Isis::ScatterPlotWindow::paint(), Isis::Process::PropagateTables(), Isis::Chip::Read(), readCubeStretch(), readFootprint(), readHistory(), readOriginalLabel(), readOriginalXmlLabel(), readTable(), Isis::CubeViewport::redPixel(), Isis::HistogramTool::refreshPlot(), Isis::ImagePolygon::SetImage(), Isis::ScatterPlotWindow::setMousePosition(), Isis::ProcessMosaic::StartProcess(), Isis::ProcessByBrick::StartProcess(), Isis::ProcessByBrick::StartProcess(), statistics(), Isis::StretchTool::statsFromCube(), and Isis::AdvancedTrackTool::TrackMosaicOrigin().

◆ read() [2/2]

void Isis::Cube::read ( Buffer & bufferToFill) const

This method will read a buffer of data from the cube as specified by the contents of the Buffer object.

Parameters
bufferToFillBuffer to be loaded

Definition at line 835 of file Cube.cpp.

References isOpen(), m_ioHandler, m_mutex, Isis::IException::Programmer, and Isis::CubeIoHandler::read().

◆ readCubeStretch()

CubeStretch Isis::Cube::readCubeStretch ( QString name = "CubeStretch",
const std::vector< PvlKeyword > keywords = std::vector<PvlKeyword>() ) const

Read a Stretch from a cube.

Parameters
nameThe name of the Stretch Blob
keywordsA set of keywords and values to match in the Stretch Blob label. This can be used to read the stretch for a specific band.
Returns
CubeStretch

Definition at line 918 of file Cube.cpp.

References fileName(), read(), and Isis::IException::User.

◆ readFootprint()

ImagePolygon Isis::Cube::readFootprint ( ) const

◆ readHistory()

History Isis::Cube::readHistory ( const QString & name = "IsisCube") const

Read the History from the Cube.

Parameters
nameThe name of the History Blob to read. This is used for reading History from Cubes made prior to the History Blob name being standardized.

Definition at line 853 of file Cube.cpp.

References read().

Referenced by Isis::Process::WriteHistory().

◆ readOriginalLabel()

OriginalLabel Isis::Cube::readOriginalLabel ( const QString & name = "IsisCube") const

Read the original PDS3 label from a cube.

Parameters
nameThe name of the OriginalLabel Blob
Returns
OriginalLabel The original PDS3 label as a PVL document

Definition at line 895 of file Cube.cpp.

References fileName(), read(), and Isis::IException::User.

◆ readOriginalXmlLabel()

OriginalXmlLabel Isis::Cube::readOriginalXmlLabel ( ) const

Read the original PDS4 label from a cube.

Returns
OriginalXmlLabel The original PDS4 label as an XML document

Definition at line 937 of file Cube.cpp.

References fileName(), read(), and Isis::IException::User.

◆ readTable()

Table Isis::Cube::readTable ( const QString & name)

Read a Table from the cube.

Parameters
nameThe name of the Table to read
Returns
Table

Definition at line 958 of file Cube.cpp.

References fileName(), Isis::IException::Programmer, and read().

Referenced by Isis::Blobber::load(), and Isis::AdvancedTrackTool::TrackMosaicOrigin().

◆ realDataFileLabel()

Pvl Isis::Cube::realDataFileLabel ( ) const
private

Function to read data from a cube label and return it as a PVL object.

Returns
Pvl object

Definition at line 2456 of file Cube.cpp.

References Isis::PvlObject::findObject(), label(), m_label, and realDataFileName().

Referenced by create(), and open().

◆ realDataFileName()

FileName Isis::Cube::realDataFileName ( ) const
private

This gets the file name of the file which actually contains the DN data.

With ecub's, our data file name could be another ecub or a detached label, so using m_dataFileName is unreasonable.

Returns
FileName object

Definition at line 2206 of file Cube.cpp.

References Isis::FileName::expanded(), Isis::PvlObject::findObject(), m_attached, m_dataFileName, m_labelFileName, m_storesDnData, Isis::FileName::name(), Isis::FileName::original(), Isis::FileName::originalPath(), Isis::FileName::path(), and Isis::FileName::toString().

Referenced by create(), open(), and realDataFileLabel().

◆ reformatOldIsisLabel()

void Isis::Cube::reformatOldIsisLabel ( const QString & oldCube)
private

This is a helper, used by open(...), that handles opening Isis 2 cubes as if they were Isis cubes.

Parameters
oldCubeThe filename of the Isis 2 cube

Definition at line 2486 of file Cube.cpp.

References Isis::FileName::createTempFile(), Isis::FileName::expanded(), m_label, m_labelFile, m_tempCube, Isis::ProgramLauncher::RunIsisProgram(), Isis::ProgramLauncher::RunSystemCommand(), and Isis::FileName::toString().

Referenced by initLabelFromFile().

◆ relocateDnData()

◆ reopen()

void Isis::Cube::reopen ( QString access = "r")

This method will reopen an isis sube for reading or reading/writing.

If access requested is read/write and the open fails, open as read only and throw error.

Parameters
[in]access(QString) Type of access needed (read or read/write

Definition at line 780 of file Cube.cpp.

References close(), Isis::FileName::expanded(), m_labelFile, m_labelFileName, m_virtualBandList, open(), and Isis::IException::Programmer.

Referenced by fromIsd(), relocateDnData(), and Isis::FileTool::save().

◆ sampleCount()

◆ setBaseMultiplier()

void Isis::Cube::setBaseMultiplier ( double base,
double mult )

Used prior to the Create method, this will specify the base and multiplier for converting 8-bit/16-bit back and forth between 32-bit:

\[ 32-bit pixel = 8-bit/16-bit pixel * multiplier + base \]

Parameters
baseAdditive constant.
multMultiplicative constant.

Definition at line 1157 of file Cube.cpp.

References base(), m_base, m_multiplier, and openCheck().

Referenced by copy(), and Isis::Process::SetOutputCube().

◆ setByteOrder()

void Isis::Cube::setByteOrder ( ByteOrder byteOrder)

Used prior to the Create method, this will specify the byte order of pixels, either least or most significant byte.

Parameters
byteOrderAn enumeration of either Msb or Lsb.

Definition at line 1208 of file Cube.cpp.

References byteOrder(), m_byteOrder, and openCheck().

Referenced by copy(), create(), and Isis::Process::SetOutputCube().

◆ setDimensions()

void Isis::Cube::setDimensions ( int ns,
int nl,
int nb )

Used prior to the Create method to specify the size of the cube.

If not invoked, a 512 x 512 x 1 cube will be created.

Parameters
nsNumber of samples
nlNumber of lines
nbNumber of bands

Definition at line 1223 of file Cube.cpp.

References m_bands, m_lines, m_samples, openCheck(), and Isis::IException::Programmer.

Referenced by copy(), Isis::ImageImporter::createOutput(), Isis::Process::SetOutputCube(), Isis::ProcessMosaic::StartProcess(), and Isis::Chip::Write().

◆ setExternalDnData()

void Isis::Cube::setExternalDnData ( FileName cubeFileWithDnData)

Used to set external dn data to cube.

Parameters
cubeFileWithDnDataFileName of the cube with DN Data

Definition at line 1240 of file Cube.cpp.

References initCoreFromLabel(), initLabelFromFile(), m_dataFileName, m_label, m_labelFile, m_labelFileName, and m_storesDnData.

Referenced by copy().

◆ setFormat()

void Isis::Cube::setFormat ( Format format)

Used prior to the Create method, this will specify the format of the cube, either band, sequential or tiled.

If not invoked, a tiled file will be created.

Parameters
formatAn enumeration of either Bsq or Tile.

Definition at line 1272 of file Cube.cpp.

References format(), m_format, and openCheck().

Referenced by copy(), create(), Isis::ImageExporter::initializeProcess(), and Isis::Process::SetOutputCube().

◆ setLabelsAttached()

void Isis::Cube::setLabelsAttached ( bool attach)

Use prior to calling create, this sets whether or not to use separate label and data files.

Parameters
attachIf false, the labels and data will be in separate files.

Definition at line 1284 of file Cube.cpp.

References m_attached, and openCheck().

Referenced by copy(), create(), and Isis::Process::SetOutputCube().

◆ setLabelSize()

void Isis::Cube::setLabelSize ( int labelBytes)

Used prior to the Create method, this will allocate a specific number of bytes in the label area for attached files.

If not invoked, 65536 bytes will be reserved by default.

Parameters
[in]labelBytesNumber of bytes to reserve for label space.

Definition at line 1297 of file Cube.cpp.

References m_labelBytes, and openCheck().

Referenced by copy(), and Isis::Process::SetOutputCube().

◆ setMinMax()

void Isis::Cube::setMinMax ( double min,
double max )

Used prior to the Create method, this will compute a good base and multiplier value given the minimum/maximum range of the 32bit data.

For example, min=0.0 and max=1.0 of 32-bit pixels will ensure the base and multiplier will cause the data to be spread out fully in the 8=bit or 16-bit range.

Parameters
minMinimum 32-bit pixel.
maxMaximum 32-bit pixel.

Definition at line 1174 of file Cube.cpp.

References m_base, m_multiplier, m_pixelType, and openCheck().

Referenced by copy(), create(), and Isis::Process::SetOutputCube().

◆ setPixelType()

void Isis::Cube::setPixelType ( PixelType pixelType)

Used prior to the Create method, this will specify the output pixel type.

If not invoked, the pixel type will be Real.

Parameters
pixelTypeAn enumeration of the pixelType desired in the output cube. See PixelType documentation for more information.

Definition at line 1310 of file Cube.cpp.

References m_pixelType, openCheck(), and pixelType().

Referenced by copy(), create(), Isis::Process::SetOutputCube(), and Isis::ProcessMosaic::StartProcess().

◆ setVirtualBands() [1/2]

void Isis::Cube::setVirtualBands ( const QList< QString > & vbands)

This allows the programmer to specify a subset of bands to work with.

This works with both read and write operations, but is typically only used for reading. This is helpful because users can specify which bands from an input cube they want to work with. For example, if the user only wants to work with band 5 out of a 10 band cube, this can be accommodated.

Parameters
[in]vbandsA vector of strings containing the virtual bands. The vector must contain integers in string form (e.g., "5", "10", "1").

Definition at line 1327 of file Cube.cpp.

References m_ioHandler, m_virtualBandList, openCheck(), Isis::CubeIoHandler::setVirtualBands(), and Isis::toInt().

Referenced by Isis::Workspace::addCubeViewport(), Isis::Workspace::addCubeViewportFromList(), open(), Isis::Process::SetInputCube(), and setVirtualBands().

◆ setVirtualBands() [2/2]

void Isis::Cube::setVirtualBands ( const std::vector< QString > & vbands)

This is a deprecated version of setVirtualBands(const QList<QString> &).

Parameters
[in]vbandsA vector of strings containing the virtual bands. The vector must contain integers in string form (e.g., "5", "10", "1").

Definition at line 1357 of file Cube.cpp.

References setVirtualBands().

◆ statistics() [1/2]

Statistics * Isis::Cube::statistics ( const int & band,
const double & validMin,
const double & validMax,
QString msg = "Gathering statistics" )

This method returns a pointer to a Statistics object which allows the program to obtain and use various statistics from the cube.

Cube does not retain ownership of the returned pointer - please delete it when you are done with it.

Parameters
bandReturns the statistics for the specified band. If the user specifies 0 for this parameter, the method will loop through every band in the cube and accumulate statistics from each band seperately
validMin
validMax
msg
Returns
Statistics*

Definition at line 1857 of file Cube.cpp.

References bandCount(), Isis::Progress::CheckStatus(), Isis::Buffer::DoubleBuffer(), isOpen(), lineCount(), Isis::IException::Programmer, read(), Isis::LineManager::SetLine(), Isis::Progress::SetMaximumSteps(), Isis::Progress::SetText(), and Isis::Buffer::size().

◆ statistics() [2/2]

Statistics * Isis::Cube::statistics ( const int & band = 1,
QString msg = "Gathering statistics" )

This method returns a pointer to a Statistics object which allows the program to obtain and use various statistics from the cube.

Cube does not retain ownership of the returned pointer - please delete it when you are done with it.

Parameters
[in]band(Default value is 1) Returns the statistics for the specified band.If the user specifies 0 for this parameter, the method will loop through every band in the cube and accumulate statistics from each band seperately
msgThe message to display with the percent process while gathering statistics
Returns
(Histogram) A pointer to a Statistics object containing details such as the minimum and maximum pixel values for the input cube on the band specified, or all bands as the case may be.

Definition at line 1836 of file Cube.cpp.

References statistics(), Isis::ValidMaximum, and Isis::ValidMinimum.

Referenced by statistics().

◆ storesDnData()

bool Isis::Cube::storesDnData ( ) const

This method returns a boolean value.

Returns
bool

Definition at line 1910 of file Cube.cpp.

References m_storesDnData.

Referenced by externalCubeFileName().

◆ write() [1/8]

◆ write() [2/8]

void Isis::Cube::write ( Buffer & bufferToWrite)

This method will write a buffer of data from the cube as specified by the contents of the Buffer object.

Parameters
bufferToWriteBuffer to be written.

Definition at line 1124 of file Cube.cpp.

References fileName(), isOpen(), isReadOnly(), m_ioHandler, m_mutex, m_storesDnData, Isis::IException::Programmer, Isis::IException::Unknown, and Isis::CubeIoHandler::write().

◆ write() [3/8]

void Isis::Cube::write ( const CubeStretch & cubeStretch)

Write a Stretch to the Cube.

The stretch will be written to the Cube as a BLOB and can be accessed using Cube::readCubeStretch.

Parameters
cubeStretchThe stretch to write to the Cube.

Definition at line 1084 of file Cube.cpp.

References write().

◆ write() [4/8]

void Isis::Cube::write ( const ImagePolygon & polygon)

Write a polygon to the Cube.

The polygon will be written to the Cube as a BLOB and can be accessed using Cube::readFootprint.

Definition at line 1112 of file Cube.cpp.

References write().

◆ write() [5/8]

void Isis::Cube::write ( const OriginalXmlLabel & lab)

This method will write an OriginalXmlLabel object.

to the cube as specified by the contents of the Blob object.

Parameters
Originalxml label data to be written

Definition at line 1056 of file Cube.cpp.

References write().

◆ write() [6/8]

void Isis::Cube::write ( const Table & table)

Write a Table to the Cube.

The Table will be written to the Cube as a BLOB and can be accessed using Cube::readTable.

Parameters
tableThe table to write to the Cube

Definition at line 1070 of file Cube.cpp.

References Isis::Table::toBlob(), and write().

◆ write() [7/8]

void Isis::Cube::write ( History & history,
const QString & name = "IsisCube" )

Write an updated History to the Cube.

The History will be written to the Cube as a BLOB and can be accessed using Cube::readHistory.

Parameters
historyThe history to write to the Cube.
nameThe name for the history BLOB. This is used for backwards compatibility with cubes from before the History BLOB name was standardized.

Definition at line 1100 of file Cube.cpp.

References Isis::History::toBlob(), and write().

◆ write() [8/8]

void Isis::Cube::write ( OriginalLabel & lab)

This method will write an OriginalLabel object.

to the cube as specified by the contents of the Blob object.

Parameters
Originallabel data to be written

Definition at line 1044 of file Cube.cpp.

References write().

◆ writeLabels()

void Isis::Cube::writeLabels ( )
private

Member Data Documentation

◆ m_attached

bool Isis::Cube::m_attached
private

True if labels are attached.

Definition at line 416 of file Cube.h.

Referenced by create(), initialize(), labelsAttached(), open(), realDataFileName(), setLabelsAttached(), write(), and writeLabels().

◆ m_bands

int Isis::Cube::m_bands
private

The band count of the open cube or the cube that will be created.

Definition at line 438 of file Cube.h.

Referenced by applyVirtualBandsToLabel(), bandCount(), create(), initCoreFromLabel(), initialize(), and setDimensions().

◆ m_base

double Isis::Cube::m_base
private

The base of the open cube or the cube that will be created; does not apply if m_pixelType is Real.

Definition at line 444 of file Cube.h.

Referenced by base(), create(), initCoreFromLabel(), initialize(), setBaseMultiplier(), and setMinMax().

◆ m_byteOrder

ByteOrder Isis::Cube::m_byteOrder
private

The byte order of the opened cube; if there is no open cube then this is the byte order that will be used when a new cube is created.

Defaults to the OS's byte order.

Definition at line 374 of file Cube.h.

Referenced by byteOrder(), create(), initCoreFromLabel(), initialize(), and setByteOrder().

◆ m_camera

Camera* Isis::Cube::m_camera
private

Camera allocated from the camera() method.

Definition at line 394 of file Cube.h.

Referenced by camera(), construct(), and ~Cube().

◆ m_dataFile

QFile* Isis::Cube::m_dataFile
private

This is only sometimes allocated.

This is used for when IsOpen is true and labels are detached so the QFile for the labels does not give us cube data.

Definition at line 361 of file Cube.h.

Referenced by cleanUp(), construct(), create(), dataFile(), and open().

◆ m_dataFileName

FileName* Isis::Cube::m_dataFileName
private

The full filename of the data file (.cub)

Definition at line 403 of file Cube.h.

Referenced by cleanUp(), construct(), create(), open(), realDataFileName(), and setExternalDnData().

◆ m_format

Format Isis::Cube::m_format
private

If isOpen() then this is the IO format that the cube uses.

If there is no file opened then this is the IO format that will be used if a cube is created (using create(...)). This defaults to Tile.

Definition at line 381 of file Cube.h.

Referenced by create(), format(), initCoreFromLabel(), initialize(), open(), and setFormat().

◆ m_formatTemplateFile

FileName* Isis::Cube::m_formatTemplateFile
private

Label pvl format template file (describes how to format labels)

Definition at line 413 of file Cube.h.

Referenced by construct(), writeLabels(), and ~Cube().

◆ m_ioHandler

CubeIoHandler* Isis::Cube::m_ioHandler
private

This does the heavy lifting for cube DN IO and is always allocated when isOpen() is true.

Definition at line 367 of file Cube.h.

Referenced by addCachingAlgorithm(), cleanUp(), clearIoCache(), construct(), copy(), create(), isOpen(), open(), read(), read(), setVirtualBands(), write(), write(), and writeLabels().

◆ m_label

◆ m_labelBytes

int Isis::Cube::m_labelBytes
private

The maximum allowed size of the label; the allocated space.

Definition at line 429 of file Cube.h.

Referenced by create(), initialize(), labelSize(), open(), setLabelSize(), write(), and writeLabels().

◆ m_labelFile

QFile* Isis::Cube::m_labelFile
private

This is the file that contains the labels always; if labels are attached then this contains the file data also.

The method dataFile() will always give you the appropriate QFile member for reading cube data; this should always be used for the labels.

If isOpen() is true, then this is allocated.

Definition at line 355 of file Cube.h.

Referenced by cleanUp(), construct(), create(), dataFile(), initLabelFromFile(), isReadOnly(), open(), reformatOldIsisLabel(), relocateDnData(), reopen(), setExternalDnData(), write(), and writeLabels().

◆ m_labelFileName

FileName* Isis::Cube::m_labelFileName
private

The full filename of the label file (.lbl or .cub)

Definition at line 400 of file Cube.h.

Referenced by cleanUp(), construct(), create(), fileName(), initCoreFromLabel(), initLabelFromFile(), open(), read(), realDataFileName(), relocateDnData(), reopen(), setExternalDnData(), write(), and writeLabels().

◆ m_lines

int Isis::Cube::m_lines
private

The line count of the open cube or the cube that will be created.

Definition at line 435 of file Cube.h.

Referenced by create(), initCoreFromLabel(), initialize(), lineCount(), and setDimensions().

◆ m_multiplier

double Isis::Cube::m_multiplier
private

The multiplier of the open cube or the cube that will be created; does not apply if m_pixelType is Real.

Definition at line 450 of file Cube.h.

Referenced by create(), initCoreFromLabel(), initialize(), multiplier(), setBaseMultiplier(), and setMinMax().

◆ m_mutex

QMutex* Isis::Cube::m_mutex
private

Basic thread-safety mutex; this class is not optimized for threads.

Definition at line 391 of file Cube.h.

Referenced by clearIoCache(), construct(), read(), read(), write(), write(), writeLabels(), and ~Cube().

◆ m_pixelType

PixelType Isis::Cube::m_pixelType
private

This is the pixel type on disk.

If a cube is open, then this will be the opened cube's pixel type. Otherwise, if a cube is created with create(...) then this pixel type will be used. The default is Real.

Definition at line 388 of file Cube.h.

Referenced by create(), initCoreFromLabel(), initialize(), pixelType(), setMinMax(), and setPixelType().

◆ m_projection

Projection* Isis::Cube::m_projection
private

Projection allocated from the projection() method.

Definition at line 397 of file Cube.h.

Referenced by construct(), projection(), and ~Cube().

◆ m_samples

int Isis::Cube::m_samples
private

The sample count of the open cube or the cube that will be created.

Definition at line 432 of file Cube.h.

Referenced by create(), initCoreFromLabel(), initialize(), sampleCount(), and setDimensions().

◆ m_storesDnData

bool Isis::Cube::m_storesDnData
private

True (most common case) when the cube DN data is inside the file we're writing to.

False means we're referencing another cube's internal DN data for reading, and writing buffers is disallowed.

Definition at line 423 of file Cube.h.

Referenced by create(), initialize(), open(), realDataFileName(), relocateDnData(), setExternalDnData(), storesDnData(), write(), and write().

◆ m_tempCube

FileName* Isis::Cube::m_tempCube
private

If open was called with an Isis 2 cube, then this will be the name of the imported ISIS cube.

m_labelFileName and m_dataFileName will store the Isis 2 cube's information.

Definition at line 410 of file Cube.h.

Referenced by cleanUp(), construct(), read(), and reformatOldIsisLabel().

◆ m_virtualBandList

QList<int>* Isis::Cube::m_virtualBandList
private

If allocated, converts from physical on-disk band # to virtual band #.

Definition at line 453 of file Cube.h.

Referenced by applyVirtualBandsToLabel(), bandCount(), cleanUp(), construct(), create(), open(), physicalBand(), reopen(), and setVirtualBands().


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