PCIDSK::PCIDSKFile Class Reference

Top interface to PCIDSK (.pix) files. More...

#include <pcidsk_file.h>

List of all members.

Public Member Functions

virtual PCIDSKInterfacesGetInterfaces ()=0
 Fetch hookable interfaces in use with this file.
virtual PCIDSKChannelGetChannel (int band)=0
 Fetch channel interface object.
virtual PCIDSKSegmentGetSegment (int segment)=0
 Fetch segment interface object.
virtual std::vector
< PCIDSKSegment * > 
GetSegments ()=0
virtual PCIDSK::PCIDSKSegmentGetSegment (int type, std::string name, int previous=0)=0
 Fetch segment interface object.
virtual int GetWidth () const =0
 Fetch image width.
virtual int GetHeight () const =0
 Fetch image height.
virtual int GetChannels () const =0
 Fetch channel (band) count.
virtual std::string GetInterleaving () const =0
 Fetch file interleaving method.
virtual bool GetUpdatable () const =0
 Check readonly/update status.
virtual uint64 GetFileSize () const =0
 Fetch file size.
virtual int CreateSegment (std::string name, std::string description, eSegType seg_type, int data_blocks)=0
 create a new auxiliary segment
virtual void DeleteSegment (int segment)=0
 delete an existing segment
virtual void CreateOverviews (int chan_count, int *chan_list, int factor, std::string resampling)=0
 Create an overview level.
virtual int GetPixelGroupSize () const =0
 fetch number of bytes per pixel
virtual void * ReadAndLockBlock (int block_index, int xoff=-1, int xsize=-1)=0
 Read a block.
virtual void UnlockBlock (bool mark_dirty=false)=0
 Unlock block.
virtual void WriteToFile (const void *buffer, uint64 offset, uint64 size)=0
 Write data to file.
virtual void ReadFromFile (void *buffer, uint64 offset, uint64 size)=0
 Read data from file.
virtual void GetIODetails (void ***io_handle_pp, Mutex ***io_mutex_pp, std::string filename="")=0
virtual std::string GetMetadataValue (const std::string &key)=0
virtual void SetMetadataValue (const std::string &key, const std::string &value)=0
virtual std::vector< std::string > GetMetadataKeys ()=0
 Fetch metadata keys.
virtual void Synchronize ()=0
 Write pending information to disk.

Detailed Description

Top interface to PCIDSK (.pix) files.


Member Function Documentation

void PCIDSK::PCIDSKFile::CreateOverviews ( int  chan_count,
int *  chan_list,
int  factor,
std::string  resampling 
) [pure virtual]

Create an overview level.

An overview is created on the indicated list of channels. If chan_count is zero, then it will be created for all channels on the file. The overview will have a size determined by dividing the base image level by "factor". The file needs to be open in update mode.

If the requested overview level already exists an exception will be thrown.

While this function creates the overview level, and records the resampling method in metadata, it does not actually compute and assign imagery to the overview. This must be done externally by the application. Overview computation is not a function of the PCIDSK SDK.

Parameters:
chan_count the number of channels listed in chan_list.
chan_list the channels for which the overview level should be created.
factor the overview decimation factor.
resampling the resampling to be used for this overview - one of "NEAREST", "AVERAGE" or "MODE".
int PCIDSK::PCIDSKFile::CreateSegment ( std::string  name,
std::string  description,
eSegType  seg_type,
int  data_blocks 
) [pure virtual]

create a new auxiliary segment

A new segment of the desired type is created and assigned the given name and description. The segment number is returned. The segment is created with the requested number of data blocks. If this is zero a default size may be assigned for some types with fixed sizes.

This method may fail if there are no unused segment pointers available in the file.

Parameters:
name segment name, at most eight characters.
description segment description, at most 64 characters.
seg_type the segment type.
data_blocks the number of data blocks the segment should be initially assigned. If zero a default value may be used for some fixed sized segments.
Returns:
the number of the segment created.

Referenced by PCIDSK::Create().

int PCIDSK::PCIDSKFile::DeleteSegment ( int  segment  )  [pure virtual]

delete an existing segment

Delete the indicated segment number. The segment must currently exist. The internal PCIDSKSegment object associated with this segment will also be destroyed, and any references to it from GetSegment() or other sources should not be used by the application after this call is made.

Parameters:
segment the number of the segment to delete from the file.
PCIDSKChannel * PCIDSK::PCIDSKFile::GetChannel ( int  band  )  [pure virtual]

Fetch channel interface object.

The returned channel object remains owned by the PCIDSKFile and should not be deleted by the caller, and will become invalid after the PCIDSKFile is closed (deleted).

Parameters:
band the band number to fetch (one based).
Returns:
pointer to internally managed channel object.
int PCIDSK::PCIDSKFile::GetChannels (  )  const [pure virtual]

Fetch channel (band) count.

Returns:
the number of channels on this file.
uint64 PCIDSK::PCIDSKFile::GetFileSize (  )  const [pure virtual]

Fetch file size.

Returns:
returns the size of the PCIDSK file in bytes, as recorded in the file header.
int PCIDSK::PCIDSKFile::GetHeight (  )  const [pure virtual]

Fetch image height.

Returns:
the height of the file in pixels.
const char * PCIDSK::PCIDSKFile::GetInterleaving (  )  const [pure virtual]

Fetch file interleaving method.

Returns:
the interleaving name, one of "PIXEL", "BAND" or "FILE". Note that tiled files will be reported as "FILE" interleaving.
std::vector< std::string > PCIDSK::PCIDSKFile::GetMetadataKeys (  )  [pure virtual]

Fetch metadata keys.

Returns a vector of metadata keys that occur on this object. The values associated with each may be fetched with GetMetadataValue().

Returns:
list of keys
See also:
GetMetadataValue()
int PCIDSK::PCIDSKFile::GetPixelGroupSize (  )  const [pure virtual]

fetch number of bytes per pixel

Returns the number of bytes for each pixel group. Each pixel group consists of the values for all the channels in the file in order.

Note:
This method should only be called for GetInterleaving() == "PIXEL" files.
Returns:
the size of a pixel group in bytes.
See also:
ReadAndLockBlock()
PCIDSKSegment * PCIDSK::PCIDSKFile::GetSegment ( int  type,
std::string  name,
int  previous = 0 
) [pure virtual]

Fetch segment interface object.

If available, a segment of the specified type and name is returned. The search is started after segment "previous" if none-zero.

The returned segment object remains owned by the PCIDSKFile and should not be deleted by the caller, and will become invalid after the PCIDSKFile is closed (deleted).

Parameters:
type the segment type desired, or SEG_UNKNOWN for any type.
name the segment name or "" for any name.
previous segment after which the search should start or 0 (default) to start from the start.
Returns:
pointer to internally managed segment object or NULL if none correspond to the request.
PCIDSKSegment * PCIDSK::PCIDSKFile::GetSegment ( int  segment  )  [pure virtual]

Fetch segment interface object.

The returned segment object remains owned by the PCIDSKFile and should not be deleted by the caller, and will become invalid after the PCIDSKFile is closed (deleted).

Parameters:
segment the segment number to fetch (one based).
Returns:
pointer to internally managed segment object.

Referenced by PCIDSK::Create().

bool PCIDSK::PCIDSKFile::GetUpdatable (  )  const [pure virtual]

Check readonly/update status.

Returns:
true if the file is open for update, or false if it is read-only.
int PCIDSK::PCIDSKFile::GetWidth (  )  const [pure virtual]

Fetch image width.

Returns:
the width of the file in pixels.
uint8 * PCIDSK::PCIDSKFile::ReadAndLockBlock ( int  block_index,
int  win_xoff = -1,
int  win_xsize = -1 
) [pure virtual]

Read a block.

Returnst the pointer to an internal buffer for the indicated block. The buffer is owned by the PCIDSKFile object, but will be considered locked and available for the application code to read and modify until the UnlockBlock() method is called. The buffer will contain all the pixel values for the requested block in pixel interleaved form.

The win_xoff, and win_xsize parameters may be used to select a subregion of the scanline block to read. By default the whole scanline is read.

Note:
This method should only be called for GetInterleaving() == "PIXEL" files. Normal imagery access should be via the PCIDSKChannel class. This method is provided on the PCIDSKFile for pixel interleaved files to allow optimized access for this one case.
Parameters:
block_index the zero based block(scanline) to be read.
win_xoff the offset into the scanline to start reading values.
win_xsize the number of pixels to read.
Returns:
pointer to an internal buffer with pixel data in it.
void PCIDSK::PCIDSKFile::ReadFromFile ( void *  buffer,
uint64  offset,
uint64  size 
) [pure virtual]

Read data from file.

This method is normally only used by the PCIDSK library itself, and provides a mechanism to read directly from the PCIDSK file. Applications should normally use the PCIDSK::PCIDSKChannel::ReadBlock() method for imagery, or appropriate PCIDSK::PCIDSKSegment methods for reading segment data.

Parameters:
buffer pointer to the buffer into which the data should be read.
offset the byte offset in the file (zero based) at which to read the data.
size the number of bytes from the file to read.
void PCIDSK::PCIDSKFile::Synchronize (  )  [pure virtual]

Write pending information to disk.

Some write and update operations on PCIDSK files are not written to disk immediately after write calls. This method will ensure that any pending writes are flushed through to disk. This includes writing updates to tiled layer indexes, flushing out metadata, and potential caching of other information such as vector writes.

NOTE: Currently this method does not invalidate read-cached information such as segment pointer lists, segment headers, or band metadata. At some point in the future it might be extended to do this as well.

void PCIDSK::PCIDSKFile::UnlockBlock ( bool  mark_dirty = false  )  [pure virtual]

Unlock block.

This method should be called after use of the buffer from ReadAndLockBlock() is complete. If the buffer was modified and will need to be written to disk the argument "mark_dirty" should be passed in as true.

Note:
This method should only be called for GetInterleaving() == "PIXEL" files.
Parameters:
mark_dirty true if the block data was modified, else false.
See also:
ReadAndLockBlock()
void PCIDSK::PCIDSKFile::WriteToFile ( const void *  buffer,
uint64  offset,
uint64  size 
) [pure virtual]

Write data to file.

This method is normally only used by the PCIDSK library itself, and provides a mechanism to write directly to the PCIDSK file. Applications should normally use the PCIDSK::PCIDSKChannel::ReadBlock(), and PCIDSK::PCIDSKChannel::WriteBlock() methods for imagery, or appropriate PCIDSK::PCIDSKSegment methods for updating segment data.

Parameters:
buffer pointer to the data to write to disk.
offset the byte offset in the file (zero based) at which to write the data.
size the number of bytes from buffer to write.

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

Generated for GDAL by doxygen 1.6.1.