A PDS_Converter is used to convert an attached PDS image label to or from a detached PDS/JP2 label. More...

#include <PDS_Converter.hh>

Inheritance diagram for PDS_Converter:

Collaboration diagram for PDS_Converter:

Public Member Functions
	PDS_Converter ()
	Constructs an empty PDS_Converter.
	PDS_Converter (const std::string &pathname, const char excluded_names=NULL, const char image_names=NULL)
	Constructs a PDS_Converter from a named file.
	PDS_Converter (const PDS_Converter &converter)
	Copies a PDS_Converter.
virtual PDS_Converter &	operator= (const PDS_Converter &converter)
	Assigns another PDS_Converter to this PDS_Converter.
virtual	~PDS_Converter ()
	Frees the PDS_Data::PDS_Data_Block_List and its contents.
virtual void	write_PDS_JP2_label (const std::string &PDS_label_pathname, const std::string &JP2_pathname, const char *removed_parameter_names=NULL, PDS_Data additional_parameters=NULL)=0
	Write a detached PDS/JP2 label file.
virtual void	write_PDS_label (const std::string &PDS_label_pathname, const Rectangle image_region=NULL, unsigned int resolution_level=1, const char removed_parameter_names=NULL, PDS_Data additional_parameters=NULL)=0
	Write a PDS label file for image data to be appended.
virtual std::string	product_names () const
	Get the name of the product types that this converter is intended to process.
virtual bool	label_recognized () const =0
	Test whether the label parameters are recognized by this converter.
PDS_Converter &	label_size (unsigned int size)
	Set the preferred size of a label file.
unsigned int	label_size () const
	Get the preferred size of a label file.
PDS_Data::PDS_Data_Block_List *	data_blocks () const
	Get the list of data blocks in the PDS label.
void	refresh_data_blocks ()
	Refresh the list of data blocks.
Image_Data_Block *	image_data ()
	Get the Image_Data_Block from the PDS_Data::PDS_Data_Block_List.
PDS_Converter &	excluded_data_block_names (const char **names)
	Set the names of parameters to be excluded from the data block list.
const char **	excluded_data_block_names () const
	Get the names of parameters to be excluded from the data block list.
PDS_Converter &	image_data_block_names (const char **names)
	Set the parameter names of image data blocks.
const char **	image_data_block_names () const
	Get the parameter names of image data blocks.
idaeim::PVL::Aggregate *	PDS_JP2_image_parameters (const std::string &JP2_pathname)
	Assemble PDS/JP2 image file description parameters.
unsigned int	write_label (const std::string &pathname, PDS_Data &label, idaeim::PVL::Lister *lister=NULL, bool pad_label=false)
	Write a label file.
Static Public Attributes
static const char *const	ID = "UA::HiRISE::PDS_Converter (1.14 2012/01/24 03:08:13)"
	Class identification name with source code version and date.
static const char *	DEFAULT_PRODUCT_TYPE = "unspecified"
	Default product name.
static const char *	UNCOMPRESSED_FILE_PARAMETERS_GROUP = "UNCOMPRESSED_FILE"
	Name of the PDS/JP2 label parameter group describing the source uncompressed file.
static const char *	COMPRESSED_FILE_PARAMETERS_GROUP = "COMPRESSED_FILE"
	Names of the PDS/JP2 label parameter group describing the destination compressed file.
static const char *	GeoTIFF_PARAMETER_NAME = "GeoTIFF_Included"
	GeoTIFF included.
static const char *	GML_PARAMETER_NAME = "GML_Included"
	GML included.
static const char *	NO_VERSION_CHANGE_PARAMETER_NAME = "No_Version_Change"
	No Version number change.
Protected Member Functions
void	clear_data_blocks ()
	Clear the data blocks list.
Protected Attributes
const char **	Excluded_Data_Block_Names
	Names (NULL-terminated array) of data blocks to be exluded from the list of data blocks (probably because they are redundant with other data blocks).
PDS_Data::PDS_Data_Block_List *	Data_Blocks
	Pointer to the list of data blocks found in the PDS label.
const char **	Image_Data_Block_Names
	Names (NULL-terminated array) of data blocks that are Image_Data_Blocks.
Image_Data_Block *	IMAGE_Data_Block
	Pointer to the IMAGE data block in the Data_Blocks list.
unsigned int	Label_Size
	The preferred size of the attached PDS label.

Detailed Description

A PDS_Converter is used to convert an attached PDS image label to or from a detached PDS/JP2 label.

A PDS_Converter inherits from PDS_Data which contains the label to be converted.

This abstract class provides a base for product-specific label converter classes. Each implementation must provide the label_recognized, write_PDS_JP2_label and write_PDS_label methods.

Author:: Bradford Castalia; UA/HiROC

Version:: 1.16

See also:: PDS_Converter::label_recognized(); PDS_Converter::write_PDS_JP2_label(const std::string&, const std::string&, const char**, PDS_Data*); PDS_Converter::write_PDS_label(const std::string&, const Rectangle*, unsigned int, const char**, PDS*)

Constructor & Destructor Documentation

PDS_Converter ( )

Constructs an empty PDS_Converter.

PDS_Converter	(	const std::string &	pathname,
		const char **	excluded_names = `NULL`,
		const char **	image_names = `NULL`
	)		`[explicit]`

Constructs a PDS_Converter from a named file.

The PDS file may be a detached PDS/JP2 file or a PDS file with an attached label. Either the write_PDS_label or write_PDS_JP2_label methods can be used to convert either source, respectively.

Parameters:

pathname	The pathname string to a source file with a PDS label.
excluded_names	The NULL-terminated array of character strings naming data blocks to be excluded from conversion consideration. May be NULL.
image_names	The NULL-terminated array of character strings naming data blocks that describe image data. N.B.: The PDS_Data::IMAGE_DATA_BLOCK_NAME is always implicitly included. May be NULL.

Exceptions:

invalid_argument If the converter is not capable of converting the source file.

References PDS_Data::data_blocks().

PDS_Converter ( const PDS_Converter & converter )

Copies a PDS_Converter.

Parameters:

converter The PDS_Converter to be copied.

~PDS_Converter ( ) [virtual]

Frees the PDS_Data::PDS_Data_Block_List and its contents.

References PDS_Converter::clear_data_blocks().

Member Function Documentation

PDS_Converter & operator= ( const PDS_Converter & converter ) [virtual]

Assigns another PDS_Converter to this PDS_Converter.

Parameters:

converter The PDS_Converter whose contents are to be assigned to this PDS_Converter.

References PDS_Converter::Data_Blocks, PDS_Converter::Excluded_Data_Block_Names, PDS_Data::image_data(), PDS_Converter::Image_Data_Block_Names, PDS_Converter::Label_Size, and Vectal< T >::push_back().

virtual void write_PDS_JP2_label	(	const std::string &	PDS_label_pathname,
		const std::string &	JP2_pathname,
		const char **	removed_parameter_names = `NULL`,
		PDS_Data *	additional_parameters = `NULL`
	)		`[pure virtual]`

Write a detached PDS/JP2 label file.

N.B.: This is a pure virtual method that must be provided by the implementing class.

This method converts the PDS label held by this PDS_Converter, which is expected to be from a file with an attached label, to its detached PDS/JP2 form and writes the results to a file at the specified pathname. Though the method is free to convert the source label in place, this is strongly discouraged; instead modifications should be made to a copy of the source label. For example:

Copy the source PDS label. PDS_Data PDS_label (*this); Modify the label. ... Write the label file. write_label (pathname, PDS_label);

Parameters:

PDS_label_pathname	The pathname for the detached label file.
JP2_pathname	The name of the JP2 image data file referened by the label file.
removed_parameter_names	A NULL terminated array of character strings that are the names of parameters to be removed from the source label before being written. May be NULL.
additional_parameters	A pointer to PDS_Data that contains additional parameters to be used by the label converter. May be NULL.
additional_parameters	A pointer to PDS_Data that contains additional parameters with product-specific label conversion information. May be NULL.

See also:: write_label(const std::string&, PDS_Data&, idaeim::PVL::Lister*, bool)

Implemented in Generic_PDS_Converter, HiPrecision_PDS_Converter, and HiRISE_PDS_Converter.

Referenced by main().

virtual void write_PDS_label	(	const std::string &	PDS_label_pathname,
		const Rectangle *	image_region = `NULL`,
		unsigned int	resolution_level = `1`,
		const char **	removed_parameter_names = `NULL`,
		PDS_Data *	additional_parameters = `NULL`
	)		`[pure virtual]`

Write a PDS label file for image data to be appended.

N.B.: This is a pure virtual method that must be provided by the implementing class.

This method converts the the PDS label held by this PDS_Converter, which is expected to be from a detached PDS/JP2 label, to its attached PDS form and writes the results to a file at the specified pathname. Though the method is free to convert the source label in place, this is strongly discouraged; instead modifications should be made to a copy of the source label. For example:

Copy the source PDS label. PDS_Data PDS_label (*this); Modify the label. ... Write the label file. write_label (pathname, PDS_label);

Parameters:

PDS_label_pathname	The pathname for the file that begins with the converted PDS label.
image_region	A Rectangle pointer that specifies a region within the image that was selected. If NULL, the entire image was selected.
resolution_level	The resolution level at which the image is rendereed from the JP2 codestream is rendered. 1 is full resolution, 2 is half resolution, 3 is quarter resolution, etc.; i.e. the rendering scale is 1 / (2**(L - 1)).
removed_parameter_names	A NULL terminated array of character strings that are the names of parameters to be removed from the source label before being written. May be NULL.
additional_parameters	A pointer to PDS_Data that contains additional parameters with product-specific label conversion information. May be NULL.

See also:: write_label(const std::string&, PDS_Data&, idaeim::PVL::Lister*, bool)

Implemented in Generic_PDS_Converter, HiPrecision_PDS_Converter, and HiRISE_PDS_Converter.

Referenced by main().

string product_names ( ) const [virtual]

Get the name of the product types that this converter is intended to process.

There is no particular meaning to the string that is returned. Each PDS_Converter implementation may choose whatever name(s) it sees fit. Nevertheless, it is recommended that each space separated word in the returned string be chosen to name a recognizable product such as the value of a label parameter that is known to identify the type of product. For example, the value of the INSTRUMENT_ID parameter might be used.

Returns:: A string used to identify the type of products recognized by this PDS_Converter. This will be the DEFAULT_PRODUCT_TYPE name if the PDS_Converter implementation does not provide this method.

Reimplemented in Generic_PDS_Converter, HiPrecision_PDS_Converter, and HiRISE_PDS_Converter.

References PDS_Converter::DEFAULT_PRODUCT_TYPE.

Referenced by main().

virtual bool label_recognized ( ) const [pure virtual]

Test whether the label parameters are recognized by this converter.

N.B.: A false return value does not necessarily mean that this converter will be unable to process the label; only that the label does not describe a product type recognized by the converter.

Returns:: true if the label parameters are recognized by this converter; false otherwise.

Implemented in Generic_PDS_Converter, HiPrecision_PDS_Converter, and HiRISE_PDS_Converter.

PDS_Converter& label_size ( unsigned int size ) [inline]

Set the preferred size of a label file.

N.B.: The preferred label size is a hint; the actual size of the label may be larger, but will not be smaller. If the label will not fit in the preferred size the label size is increased the to minimum size required rounded up to the nearest 1K (1024) bytes.

Parameters:

size	The preferred size, in characters, of a label file.

Returns:: This PDS_Converter.

See also:: write_label(const std::string&, PDS_Data&, idaeim::PVL::Lister*, bool)

References PDS_Converter::Label_Size.

Referenced by main().

unsigned int label_size ( ) const [inline]

Get the preferred size of a label file.

Returns:: The preferred size, in characters, of a label file.

References PDS_Converter::Label_Size.

PDS_Data::PDS_Data_Block_List* data_blocks ( ) const [inline]

Get the list of data blocks in the PDS label.

Returns:: A pointer to the current data block list. This will be NULL if no data blocks are currently identified identified in the label. N.B. The list may not be current if the label parameters have been changed or otherwise modified; a refresh of the data blocks can be used in this case.

References PDS_Converter::Data_Blocks.

void refresh_data_blocks ( )

Refresh the list of data blocks.

Both the general data blocks list and the image data block pointer are refreshed from the current PDS label parameters. The previous data blocks are deleted.

References PDS_Converter::clear_data_blocks(), and PDS_Converter::image_data().

Image_Data_Block * image_data ( )

Get the Image_Data_Block from the PDS_Data::PDS_Data_Block_List.

If the Image_Data_Block has has not yet been found the PDS_Data::PDS_Data_Block_List is searched for it. If there is currently no list of data blocks, an attempt is made get a new data block list. If this fails to identify an image data block an attempt is made to find a Parameter Aggregate with the PDS_Data::IMAGE_DATA_BLOCK_NAME regardless of whether a corresponding record pointer parameter is present in the label. If this succeeds an IMAGE_Data_Block is constructed from the parameter group that is found.

Returns:: A pointer to the Image_Data_Block, or NULL if none can be found.

See also:: PDS_Data::image_data(PDS_Data::PDS_Data_Block_List*)

References PDS_Data::AGGREGATE_PARAMETER, PDS_Data::data_blocks(), PDS_Converter::Data_Blocks, PDS_Converter::Excluded_Data_Block_Names, PDS_Data::find_parameter(), PDS_Converter::IMAGE_Data_Block, PDS_Data::IMAGE_DATA_BLOCK_NAME, and PDS_Converter::Image_Data_Block_Names.

Referenced by main(), and PDS_Converter::refresh_data_blocks().

PDS_Converter & excluded_data_block_names ( const char ** names )

Set the names of parameters to be excluded from the data block list.

The list of known data blocks is updated. N.B.: The current image data block names are used to refresh the data block list, so if they are to be set they should be set first.

Parameters:

names A NULL-terminated array of character strings. May be NULL if no data blocks are to be excluded.

Returns:: This PDS_Converter.

const char** excluded_data_block_names ( ) const [inline]

Get the names of parameters to be excluded from the data block list.

Returns:: A NULL-terminated array of character strings. May be NULL if no data blocks are to be excluded.

See also:: excluded_data_block_names(const char**)

References PDS_Converter::Excluded_Data_Block_Names.

PDS_Converter & image_data_block_names ( const char ** names )

Set the parameter names of image data blocks.

N.B.: The PDS_Data::IMAGE_DATA_BLOCK_NAME is always implicitly included even if the image names array is NULL.

The label's image data block is located. At the same time the list of known data blocks is also refreshed.

Parameters:

names A NULL-terminated array of character strings. May be NULL if only the PDS_Data::IMAGE_DATA_BLOCK_NAME is to be used.

Returns:: This PDS_Converter.

const char** image_data_block_names ( ) const [inline]

Get the parameter names of image data blocks.

Returns:: A NULL-terminated array of character strings. May be NULL if only the PDS_Data::IMAGE_DATA_BLOCK_NAME is to be used.

See also:: image_data_block_names(const char**)

References PDS_Converter::Image_Data_Block_Names.

Aggregate * PDS_JP2_image_parameters ( const std::string & JP2_pathname )

Assemble PDS/JP2 image file description parameters.

Two groups of parameters are generated: A COMPRESSED_FILE group that refers to an associated JP2 file, and an UNCOMPRESSED_FILE group that describes the source image data file used to generate the JP2 file. The UNCOMPRESSED_FILE group also includes the complete IMAGE parameters group. The source image data filename is found in the name of the Parameter Aggregate containing this PDS label representation. The image data block is used to obtain the image data definitions.

Example:


    OBJECT = COMPRESSED_FILE
        FILE_NAME                  = "PSP_002068_2635_RED.JP2"
        RECORD_TYPE                = UNDEFINED
        ENCODING_TYPE              = "JP2"
        ENCODING_TYPE_VERSION_NAME = "ISO/IEC15444-1:2004"
        INTERCHANGE_FORMAT         = BINARY
        UNCOMPRESSED_FILE_NAME     = "PSP_002068_2635_RED.IMG"
        REQUIRED_STORAGE_BYTES     = 68624340 <BYTES>
        ^DESCRIPTION               = "JP2INFO.TXT"
    END_OBJECT = COMPRESSED_FILE
    OBJECT = UNCOMPRESSED_FILE
        FILE_NAME    = "PSP_002068_2635_RED.IMG"
        RECORD_TYPE  = FIXED_LENGTH
        RECORD_BYTES = 10860 <BYTES>
        FILE_RECORDS = 6319
        ^IMAGE       = "PSP_002068_2635_RED.IMG"
        OBJECT = IMAGE
            ...
        END_OBJECT = IMAGE
    END_OBJECT = UNCOMPRESSED_FILE

Parameters:

JP2_pathname The pathname to the associated JP2 file. Only the final filename portion is used.

Returns:: A pointer to a Parameter Aggregate containing the COMPRESSED_FILE and UNCOMPRESSED_FILE Aggregates. N.B.: Because two parameter Aggregates are assembled they are enclosed in a container Aggregate that is not expected to be retained; only the Parameter Aggregates it carries are relevant.

Exceptions:

runtime_error If an image data block can not be found in the source label.

References file_name(), ID, and Vectal< T >::poke_back().

unsigned int write_label	(	const std::string &	pathname,
		PDS_Data &	label,
		idaeim::PVL::Lister *	lister = `NULL`,
		bool	pad_label = `false`
	)

Write a label file.

If a file exists at the specified pathname it will be replaced with the new file.

If label padding is enabled (it is not by default) and the size of the label file after writing the label parameters is less than the preferred label size the file will be padded with space characters up to the preferred size.

Parameters:

pathname	The pathname to the label file.
label	A reference to the PDS_Data containing the label parameters.
lister	The idaeim::PVL::Lister that will apply formatting to the label parameters as they are written. May be null (the default) and a standard PDS style lister will be provided.
pad_label	If true label file padding will be applied to ensure the label size is at least the preferred size; if false no padding will be applied.