A JP2_Encoder encodes image pixel data into a JPEG2000 JP2 file. More...

#include <JP2_Encoder.hh>

Collaboration diagram for JP2_Encoder:

Public Member Functions
	JP2_Encoder ()
	~JP2_Encoder ()
std::string	source () const
	Get the PDS image data source pathname.
JP2_Encoder &	source (const std::string &pathname)
	Set the pathname to the PDS image data source.
std::string	destination () const
	Get the destination JP2 file pathname.
JP2_Encoder &	destination (const std::string &pathname)
	Set the destination JP2 file pathname.
std::string	PDS_label_pathname () const
	Get the PDS/JP2 label file pathname.
JP2_Encoder &	PDS_label_pathname (const std::string &pathname)
	Set the PDS/JP2 label file pathname.
std::streamoff	image_data_location () const
	Get the location of the image data in the source file.
JP2_Encoder &	image_data_location (std::streamoff file_offset)
	Set the location of the image data in the source file.
unsigned int	image_bands () const
	Get the number of bands (components) in the PDS image.
JP2_Encoder &	image_bands (unsigned int bands)
	Set the number of bands (components) in the PDS image.
const Size_2D	image_size () const
	Get the size of the source PDS image data.
JP2_Encoder &	image_size (const Size_2D &size)
	Set the size of the source PDS image data.
unsigned int	pixel_bytes () const
	Get the number of bytes per pixel.
JP2_Encoder &	pixel_bytes (unsigned int bytes_per_pixel)
	Set the number of bytes per pixel.
unsigned int	pixel_bits () const
	Get the pixel precision.
JP2_Encoder &	pixel_bits (unsigned int bits_per_pixel)
	Set the number of bits per pixel.
bool	signed_data () const
	Get the signedness of the pixel data.
JP2_Encoder &	signed_data (bool data_is_signed)
	Set the signedness of the data.
bool	MSB_data () const
	Test if the source data will be treated as MSB ordered.
JP2_Encoder &	MSB_data (bool data_is_MSB)
	Set the source data byte ordering.
bool	swap_pixel_bytes () const
	Test if multi-byte pixels will be reordered before being sent to the JPEG2000 codestream generation machinery.
JP2_Encoder &	swap_pixel_bytes (bool swap_data)
	Set if multi-byte pixels will be reordered before being sent to the JPEG2000 codestream generation machinery.
unsigned int	line_prefix_bytes () const
	Get the number of bytes preceeding each line of image pixel data.
JP2_Encoder &	line_prefix_bytes (unsigned int prefix_bytes)
	Set the number of bytes preceeding each line of image pixel data.
unsigned int	line_suffix_bytes () const
	Get the number of bytes following each line of image pixel data.
JP2_Encoder &	line_suffix_bytes (unsigned int suffix_bytes)
	Set the number of bytes following each line of image pixel data.
const Size_2D	tile_size () const
	Get the size of the JP2 image tiles.
JP2_Encoder &	tile_size (const Size_2D &size)
	Set the size of the JP2 image tiles.
unsigned int	resolution_levels () const
	Get the total number of codestream resolution levels.
JP2_Encoder &	resolution_levels (unsigned int resolution_levels)
	Set the total number of codestream resolution levels.
unsigned int	quality_layers () const
	Get the number of codestream quality layers.
JP2_Encoder &	quality_layers (unsigned int quality_layers)
	Set the number of codestream quality layers.
double	bit_rate () const
	Get the codestream compression bit-rate.
JP2_Encoder &	bit_rate (double rate)
	Set the codestream compression bit-rate.
std::string	progression_order () const
	Get the codestream progression order descriptor.
JP2_Encoder &	progression_order (const std::string &progression)
	Set the codestream progression order.
const std::vector< Size_2D >	precinct_sizes () const
	Get the precinct sizes for each resolution level.
const Size_2D	precinct_size (unsigned int resolution_level=0) const
	Get the precinct size for a given resolution level.
JP2_Encoder &	precinct_sizes (const std::vector< Size_2D > &sizes)
	Set the precinct sizes for each resolution level.
JP2_Encoder &	precinct_size (const Size_2D &size, unsigned int resolution_level=0)
	Set the precinct size for a given resolution level.
const Size_2D	code_block_size () const
	Get the code block size.
JP2_Encoder &	code_block_size (const Size_2D &size)
	Set the code block size.
JP2_Box::JP2_Box_List &	added_boxes ()
	Get the list of user specified data boxes added to the JP2 file.
JP2_Encoder &	add_box (JP2_Box *box)
	Add a data box to the JP2 file.
bool	remove_box (JP2_Box *box)
	Remove a data box from the list of user specified boxes.
const unsigned char *	producer_UUID () const
	Get the product producer signature UUID value.
JP2_Encoder &	producer_UUID (const unsigned char *id)
	Set the product producer signature UUID value.
std::string	comment () const
	Get the codestream comment.
JP2_Encoder &	comment (const std::string &text)
	Set comment text to be added to the codestream.
bool	ready () const
	Test if the encoder is ready to compress the image data.
std::string	reasons () const
	Get a description of the reasons that the encoder is not ready.
int	needs () const
	Indicates what the encoder needs to do its job.
JP2_Encoder_Error *	encoder_error () const
	Get the JP2_Encoder_Error describing the last encoder error that occurred.
long long	encode ()
	Encode the image source to a JPEG2000 JP2 destination.
void	open ()
	Open the source JP2 file.
long long	write_header ()
	Write the required metadata boxes to the JP2 file.
long long	write_user_boxes ()
	Write user specified boxes to the JP2 file.
long long	write_codestream ()
	Generate the compressed image data JPEG2000 codestream and write it to the JP2 file.
JP2_Encoder &	incremental_flush_bytes (long long bytes)
	Set the rate at which compressed image data will be written to the output JP2 file.
long long	incremental_flush_bytes () const
	Get the rate at which compressed image data will be written to the output JP2 file.
JP2_Encoder &	incremental_flush_lines (unsigned int lines)
	Set the rate at which compressed image data will be written to the output JP2 file.
int	incremental_flush_lines () const
	Get the rate at which compressed image data will be written to the output JP2 file.
long long	close ()
int	invalid_precinct_size (const std::vector< Size_2D > &sizes)
	Check for valid precinct sizes.

Static Public Attributes
static const char *const	ID
	Class identification name with source code version and date.
static const unsigned int	DEFAULT_RESOLUTION_LEVELS = 6
	Default number of resolution levels.
static const unsigned int	MAX_RESOLUTION_LEVELS = 32
	Maximum number of resolution levels.
static const unsigned int	MAX_QUALITY_LAYERS = 16384
	Maximum number of quality layers.
static const char *const	UUID_INFO_BOX_NAME = "uinf"
	PDS label reference information UUID Info JP2 container box name.
static const char *const	UUID_BOX_NAME = "ulst"
	Data provider UUID JP2 box name.
static const int	UUID_SIZE = 16
	Size of the UUID data content.
static const char *const	URL_BOX_NAME = "url "
	PDS label relative filename URL JP2 box name.
static const int	MIN_STRIPE_HEIGHT = 256
	Image data stripe minimum and maximum number of lines.
static const int	MAX_STRIPE_HEIGHT = 8192
static const int	NEEDS_SOURCE = 1 << 0
	What the encoder needs to do its job.
static const int	NEEDS_DESTINATION = 1 << 1
static const int	NEEDS_IMAGE = 1 << 2
static const int	ENCODER_EXCEPTION = 66
	JP2_Encoder_Error exception signal value.

Protected Member Functions
void	read_stripe (std::istream &source, int band, int line, int lines, kdu_int16 *buffer)
	Fill an image data buffer with pixel data from a source stream.
void	read_stripe (std::istream &source, int band, int line, int lines, kdu_int32 *buffer)
	Fill an image data buffer with pixel data from a source stream.

Protected Attributes
std::string	Image_Source
	Image source pathname.
std::string	JP2_Pathname
	Image destination pathname.
std::streamoff	Image_Offset
	Image data location as a byte offset within the source file.
unsigned int	Image_Bands
	Total image bands (components).
Size_2D	Image_Size
unsigned int	Line_Prefix_Bytes
	The number of bytes preceeding and following each line of pixel bytes.
unsigned int	Line_Suffix_Bytes
unsigned int	Pixel_Bytes
	Pixel datum size in bytes.
unsigned int	Pixel_Bits
	Pixel precision bits.
bool	Signed_Data
	Whether pixel data is to be treated as signed.
JP2_Box::JP2_Box_List	Added_Boxes
std::string	PDS_Label_Pathname
	PDS label file pathname to be placed in a UUID Info URL box.
unsigned char *	Producer_UUID
	The UUID to be placed in a UUID List box inside a UUID Info box.
std::string	Comment
	Comment segment to be added to the codestream.
bool	Swap_Pixel_Bytes
	Whether pixel bytes should be reordered before be encoded.
unsigned int	Resolution_Levels
	The number of resolution levels to encode.
unsigned int	Quality_Layers
double	Bit_Rate
std::string	Progression_Order
	The codestream progression order to be used.
Size_2D	Tile_Size
	Tile size for codestream structure organization.
std::vector< Size_2D >	Precinct_Sizes
	Precinct sizes for codestream structure organization within tiles.
Size_2D	Code_Block_Size
	Code block size for codestream packet encoding within precincts.
long long	Incremental_Flush_Bytes

Detailed Description

A JP2_Encoder encodes image pixel data into a JPEG2000 JP2 file.

After a JP2_Encoder is constructed it must be configured. The encoder must be configured with at least an input image data source file, an output JP2 destination file and the image data characterization with at least the image size and number of pixel bytes or pixel bits. By default the image data is assumed to be located at the beginning the source file, has one band (i.e. component), is unsigned, is MSB ordered (if multi-byte) and has no line prefix or suffix bytes.

The JP2_Encoder can also be configured with various JPEG2000 codestream organization information. By default the codestream will be untiled, have DEFAULT_RESOLUTION_LEVELS resolution levels, use Precint-Component-Resolution-Level progression order, have a 64x64 code block size and use precinct sizes determined by the underlying codestream generation machinery.

Once the JP2_Encoder is ready encoding can be started to generate the JP2 file from the image data source. Lossless image data compression will be used to generate the JPEG2000 codestream. A JP2_Encoder may be reused with or without reconfiguration between uses.

This implementation employs the Kakadu Software libraries.

Author: Bradford Castalia, Drew Davidson and Ben Pearson, UA/HiROC

Version: 1.28

Constructor & Destructor Documentation

◆ JP2_Encoder()

◆ ~JP2_Encoder()

~JP2_Encoder ( )

References Producer_UUID.

Member Function Documentation

◆ source() [1/2]

std::string source ( ) const

inline

Get the PDS image data source pathname.

Returns: The pathname string for the PDS source. This will be the empty string if no source has been bound to this JP2_Encoder.

References Image_Source.

Referenced by main(), read_stripe(), and read_stripe().

◆ source() [2/2]

JP2_Encoder & source ( const std::string & pathname )

Set the pathname to the PDS image data source.

N.B.: If the source has already been opened and the pathname is different than the previous pathname, the source is closed.

Parameters

pathname The image data source pathname.

Returns: This JP2_Encoder.

References close(), and Image_Source.

◆ destination() [1/2]

std::string destination ( ) const

inline

Get the destination JP2 file pathname.

Returns: The destination file pathname string. This will be empty if no destination has been bound to this JP2_Encoder.

See also: destination(const std::string&)

References JP2_Pathname.

◆ destination() [2/2]

JP2_Encoder & destination ( const std::string & pathname )

inline

Set the destination JP2 file pathname.

Parameters

pathname The destination file pathname string.

Returns: This JP2_Encoder.

References JP2_Encoder(), and JP2_Pathname.

◆ PDS_label_pathname() [1/2]

std::string PDS_label_pathname ( ) const

inline

Get the PDS/JP2 label file pathname.

Returns: The PDS/JP2 label file pathname string. This will be empty if no PDS/JP2 label file has been bound to this JP2_Encoder.

See also: PDS_label_pathname(const std::string&)

References PDS_Label_Pathname.

◆ PDS_label_pathname() [2/2]

JP2_Encoder & PDS_label_pathname ( const std::string & pathname )

inline

Set the PDS/JP2 label file pathname.

Only the filename portion of the pathname is used for the relative filename URL reference when the user boxes are written to the JP2 file.

Parameters

pathname The PDS/JP2 label file pathname string. If NULL no label filename reference URL box or producer signature UUUID box will be included in the JP2 file.

Returns: This JP2_Encoder.

See also: producer_UUID(const unsigned char*)

References JP2_Encoder(), and PDS_Label_Pathname.

◆ image_data_location() [1/2]

std::streamoff image_data_location ( ) const

inline

Get the location of the image data in the source file.

Returns: The byte offset where the image data starts in the source file.

See also: image_data_location(std::ios::off_type)

References Image_Offset.

◆ image_data_location() [2/2]

JP2_Encoder & image_data_location ( std::streamoff file_offset )

inline

Set the location of the image data in the source file.

Parameters

file_offset The byte offset where the image data starts in the source file.

Returns: This JP2_Encoder.

References Image_Offset, and JP2_Encoder().

◆ image_bands() [1/2]

unsigned int image_bands ( ) const

inline

Get the number of bands (components) in the PDS image.

Returns: The number of bands in the PDS image.

See also: image_bands(unsigned int)

References Image_Bands.

◆ image_bands() [2/2]

JP2_Encoder & image_bands ( unsigned int bands )

inline

Set the number of bands (components) in the PDS image.

Parameters

bands The number of bands in the PDS image.

Returns: This JP2_Encoder.

References Image_Bands, and JP2_Encoder().

◆ image_size() [1/2]

const Size_2D image_size ( ) const

inline

Get the size of the source PDS image data.

Returns: A Size_2D object containing the image width and height.

See also: image_size(const Size_2D&)

References Image_Size.

◆ image_size() [2/2]

JP2_Encoder & image_size ( const Size_2D & size )

Set the size of the source PDS image data.

Parameters

size	A Size_2D object containing the image width and height.

Returns: This JP2_Encoder.

Exceptions

invalid_argument If either the image width or height is zero.

References Size_2D::Height, ID, Image_Size, and Size_2D::Width.

◆ pixel_bytes() [1/2]

unsigned int pixel_bytes ( ) const

inline

Get the number of bytes per pixel.

Returns: The number of storage bytes used by each pixel.

See also: pixel_bytes(unsigned int)

References Pixel_Bytes.

Referenced by pixel_bits().

◆ pixel_bytes() [2/2]

JP2_Encoder & pixel_bytes ( unsigned int bytes_per_pixel )

Set the number of bytes per pixel.

N.B.: If the number of pixel bytes is 1 the data will be set to unsigned.

Parameters

bytes_per_pixel The number of bytes per pixel. Only the values 1, 2 and 4 are allowed.

Returns: This JP2_Encoder.

Exceptions

invalid_argument	If the argument is not 1, 2 or 4.
length_error	If the number of pixel bytes is less than are needed to hold the `pixel bits`.

References ID, Pixel_Bits, Pixel_Bytes, and signed_data().

◆ pixel_bits() [1/2]

unsigned int pixel_bits ( ) const

inline

Get the pixel precision.

Returns: The number of valid bits used by each pixel.

See also: pixel_bits(unsigned int)

References Pixel_Bits.

◆ pixel_bits() [2/2]

JP2_Encoder & pixel_bits ( unsigned int bits_per_pixel )

Set the number of bits per pixel.

The number of pixel bytes is enlarged, if necessary, to accommodate all the pixel bits.

N.B.: If the number of pixel bits is less than the number of bits in the pixel bytes the data will be set to unsigned.

Parameters

bits_per_pixel The number of bits per pixel. The maximum value is 32.

Returns: This JP2_Encoder.

Exceptions

invalid_argument If the argument is greater than 32.

References ID, Pixel_Bits, Pixel_Bytes, pixel_bytes(), and signed_data().

◆ signed_data() [1/2]

bool signed_data ( ) const

inline

Get the signedness of the pixel data.

Returns: true if the pixel data is treated as signed; false otherwise.

See also: signed_data(bool)

References Signed_Data.

Referenced by pixel_bits(), and pixel_bytes().

◆ signed_data() [2/2]

JP2_Encoder & signed_data ( bool data_is_signed )

Set the signedness of the data.

N.B.: If the number of pixel bytes is 1, or the number of pixel bits is less than the number of bits in the pixel bytes, then the data is unsigned by definition. In such cases the argument will be forced to false.

Parameters

data_is_signed true if the data is to be treated as signed; false otherwise.

Returns: This JP2_Encoder.

References Pixel_Bits, Pixel_Bytes, and Signed_Data.

◆ MSB_data() [1/2]

bool MSB_data ( ) const

Test if the source data will be treated as MSB ordered.

Returns: true if the host system is not high endian and pixel byte swapping has been enabled, or the host system is high endian and pixel byte swapping has not been enabled; false otherwise.

References Swap_Pixel_Bytes.

◆ MSB_data() [2/2]

JP2_Encoder & MSB_data ( bool data_is_MSB )

Set the source data byte ordering.

N.B.: The pixel byte swapping state is set by this method: If the host system is not high endian and the source data is MSB ordered, or the host system is high endian and the source data is LSB ordered, pixel byte swapping will be enabled; otherwise pixel byte swapping will be disabled.

Parameters

data_is_MSB true if the source data is MSB ordered; false if the source data is LSB ordered.

Returns: This JP2_Encoder.

References Swap_Pixel_Bytes.

◆ swap_pixel_bytes() [1/2]

bool swap_pixel_bytes ( ) const

inline

Test if multi-byte pixels will be reordered before being sent to the JPEG2000 codestream generation machinery.

Returns: true if multi-byte pixels are to be reordered; false otherwise.

See also: swap_pixel_bytes(bool)

References Swap_Pixel_Bytes.

◆ swap_pixel_bytes() [2/2]

JP2_Encoder & swap_pixel_bytes ( bool swap_data )

inline

Set if multi-byte pixels will be reordered before being sent to the JPEG2000 codestream generation machinery.

Parameters

swap_data true if multi-byte pixels are to be reordered; false otherwise.

Returns: This JP2_Encoder.

See also: MSB_data(bool)

References JP2_Encoder(), and Swap_Pixel_Bytes.

◆ line_prefix_bytes() [1/2]

unsigned int line_prefix_bytes ( ) const

inline

Get the number of bytes preceeding each line of image pixel data.

Returns: The number of line prefix bytes.

See also: line_prefix_bytes(unsigned int)

References Line_Prefix_Bytes.

◆ line_prefix_bytes() [2/2]

JP2_Encoder & line_prefix_bytes ( unsigned int prefix_bytes )

inline

Set the number of bytes preceeding each line of image pixel data.

Parameters

prefix_bytes The number of line prefix bytes.

Returns: This JP2_Encoder.

References JP2_Encoder(), and Line_Prefix_Bytes.

◆ line_suffix_bytes() [1/2]

unsigned int line_suffix_bytes ( ) const

inline

Get the number of bytes following each line of image pixel data.

Returns: The number of line suffix bytes.

See also: line_suffix_bytes(unsigned int)

References Line_Suffix_Bytes.

◆ line_suffix_bytes() [2/2]

JP2_Encoder & line_suffix_bytes ( unsigned int suffix_bytes )

inline

Set the number of bytes following each line of image pixel data.

Parameters

suffix_bytes The number of line suffix bytes.

Returns: This JP2_Encoder.

References JP2_Encoder(), and Line_Suffix_Bytes.

◆ tile_size() [1/2]

const Size_2D tile_size ( ) const

inline

Get the size of the JP2 image tiles.

Returns: A Size_2D object containing the JP2 image tiles width and height.

See also: tile_size(const Size_2D&)

References Tile_Size.

◆ tile_size() [2/2]

JP2_Encoder & tile_size ( const Size_2D & size )

inline

Set the size of the JP2 image tiles.

If the tile width is zero the width of the image will be use. If the tile height is zero height of the image will be used.

Parameters

size	A Size_2D object containing the JP2 tiles width and height.

Returns: This JP2_Encoder.

References JP2_Encoder(), and Tile_Size.

◆ resolution_levels() [1/2]

unsigned int resolution_levels ( ) const

inline

Get the total number of codestream resolution levels.

N.B.: The number of resolution levels is one more than the number of JPEG2000 decomposition levels.

Returns: The total number of codestream resolution levels.

See also: resolution_levels(unsigned int)

References Resolution_Levels.

Referenced by resolution_levels().

◆ resolution_levels() [2/2]

JP2_Encoder & resolution_levels ( unsigned int resolution_levels )

Set the total number of codestream resolution levels.

N.B.: The number of resolution levels is one more than the number of JPEG2000 decomposition levels.

Parameters

resolution_levels The total number of codestream resolution levels.

Returns: This JP2_Encoder.

Exceptions

invalid_argument If the specified number of resolution levels is greater than the MAX_RESOLUTION_LEVELS allowed.

See also: resolution_levels()

References ID, MAX_RESOLUTION_LEVELS, Precinct_Sizes, Resolution_Levels, and resolution_levels().

◆ quality_layers() [1/2]

unsigned int quality_layers ( ) const

inline

Get the number of codestream quality layers.

Returns: The number of codestream quality layers.

See also: quality_layers(unsigned int)

References Quality_Layers.

Referenced by quality_layers().

◆ quality_layers() [2/2]

JP2_Encoder & quality_layers ( unsigned int quality_layers )

Set the number of codestream quality layers.

The default number of quality layers is 1. The maximum number of layers is MAX_QUALITY_LAYERS (16384).

Parameters

quality_layers The number of codestream quality layers. A value of zero will be set to 1.

Returns: This JP2_Encoder.

Exceptions

invalid_argument If the specified number of quality layers is greater than the maximum of the MAX_QUALITY_LAYERS allowed.

References ID, MAX_QUALITY_LAYERS, Quality_Layers, and quality_layers().

◆ bit_rate() [1/2]

double bit_rate ( ) const

inline

Get the codestream compression bit-rate.

Returns: The codestream compression bit-rate. This will be zero if loss-less, reversible compression is to be used.

See also: bit_rate(double)

References Bit_Rate.

◆ bit_rate() [2/2]

JP2_Encoder & bit_rate ( double rate )

Set the codestream compression bit-rate.

The compression bit-rate is expressed in terms of the ratio between the total number of compressed bits (including headers) and the product of the largest horizontal and vertical image component dimensions. This may also be thought of as the number of bits per pixel used in the compressed codestream.

Parameters

rate	The codestream compression bit-rate. A value of zero means that loss-less, reversible compression is to be used. A value less than zero is set to zero.

Returns: This JP2_Encoder.

See also: bit_rate()

References Bit_Rate.

◆ progression_order() [1/2]

std::string progression_order ( ) const

inline

Get the codestream progression order descriptor.

Returns: The progression order descriptor string.

See also: progression_order(const std::string&)

References Progression_Order.

◆ progression_order() [2/2]

JP2_Encoder & progression_order ( const std::string & progression )

Set the codestream progression order.

The progression order is described by a string which specifies the order in which the JPEG2000 codestream is written. A JPEG2000 codestream has Position (image area), Component (image band), Resolution and Layer (quality) dimensions. The codestream progression order is specified as the first letters of each dimension in the order in which they are to be written; the first dimension specified varies the most slowly while the last dimension specified varies the most quickly.

The default progression order is set at compile time by the value of the DEFAULT_PROGRESSION_ORDER symbol.

Parameters

progression A string specifying the progression order.

Returns: This JP2_Encoder.

Exceptions

invalid_argument If the progression order string is not four characters containing 'P', 'C', 'R' and 'L' in some order.

References ID, and Progression_Order.

◆ precinct_sizes() [1/2]

const std::vector< Size_2D > precinct_sizes ( ) const

inline

Get the precinct sizes for each resolution level.

Returns: The list of precinct sizes as a const std::vector<Size_2D>) with one entry for each resolution level.

See also: precinct_sizes(const std::vector<Size_2D>& sizes); resolution_levels(unsigned int)

References Precinct_Sizes.

◆ precinct_size() [1/2]

const Size_2D precinct_size ( unsigned int resolution_level = 0 ) const

Get the precinct size for a given resolution level.

Parameters

resolution_level The resoultion level index (0-based) for which the precinct size is to be obtained.

Returns: The precinct size (Size_2D) for the resolution level.

Exceptions

invalid_argument If the resolution level is greater than or equal to the number of resolution levels.

See also: resolution_levels(unsigned int)

References ID, and Precinct_Sizes.

◆ precinct_sizes() [2/2]

JP2_Encoder & precinct_sizes ( const std::vector< Size_2D > & sizes )

Set the precinct sizes for each resolution level.

Each precinct size dimension must be a non-zero power of two.

If the number of precinct sizes is greater than the number of resolution levels the excess size values will be ignored. If the number of precinct sizes is less than the number of resolution levels the last size will be used for the sizes of all remaining resolution levels.

Parameters

sizes A list (vector<Size_2D>) of precinct sizes in resolution number order.

Returns: This JP2_Encoder.

Exceptions

invalid_argument If any precinct size dimension is not a non-zero power of two.

See also: invalid_precinct_size(const std::vector<Size_2D>& sizes)

References ID, invalid_precinct_size(), Precinct_Sizes, and Resolution_Levels.

◆ precinct_size() [2/2]

JP2_Encoder & precinct_size	(	const Size_2D &	size,
		unsigned int	resolution_level = 0 )

Set the precinct size for a given resolution level.

Parameters

size	A precinct size (Size_2D) for the resolution level.
resolution_level	The resoultion level index (0-based) for which the precinct size is to be obtained.

Exceptions

invalid_argument If the resolution level is greater than or equal to the number of resolution levels.

See also: resolution_levels(unsigned int)

References Size_2D::Height, ID, UA::HiRISE::power_of_2(), Precinct_Sizes, Resolution_Levels, and Size_2D::Width.

◆ code_block_size() [1/2]

const Size_2D code_block_size ( ) const

inline

Get the code block size.

Returns: The size (Size_2D) of the code block.

See also: code_block_size(const Size_2D&)

References Code_Block_Size.

◆ code_block_size() [2/2]

JP2_Encoder & code_block_size ( const Size_2D & size )

Set the code block size.

Parameters

size	The size (Size_2D) of the code block.

Returns: This JP2_Encoder.

Exceptions

invalid_argument If either dimension is 0 or greater than 64.

References Code_Block_Size, Size_2D::Height, ID, and Size_2D::Width.

◆ added_boxes()

JP2_Box::JP2_Box_List & added_boxes ( )

inline

Get the list of user specified data boxes added to the JP2 file.

Returns: A reference to a JP2_Box::JP2_Box_List, a vector of JP2_Box objects that will be added to the JP2 file, or that were added if the file has already been written.

References Added_Boxes.

◆ add_box()

JP2_Encoder & add_box ( JP2_Box * box )

Add a data box to the JP2 file.

The box is placed on the list of user specified boxes that will be added to included in the JP2 file when it is written.

Parameters

box	A JP2_Box pointer.

Returns: This JP2_Encoder.

References Added_Boxes.

◆ remove_box()

bool remove_box ( JP2_Box * box )

Remove a data box from the list of user specified boxes.

Parameters

box	A JP2_Box pointer.

Returns: true if the specified box was found in the list of user specifed boxes; false otherwise.

See also: added_boxes()

References Added_Boxes.

◆ producer_UUID() [1/2]

const unsigned char * producer_UUID ( ) const

inline

Get the product producer signature UUID value.

Returns: An array of UUID_SIZE (16) characters (N.B.: This is not a null-terminated character string) containing the product producer UUID value. This will be NULL if a product producer signature of all zeros is to be used.

See also: producer_UUID(const unsigned char*)

References Producer_UUID.

◆ producer_UUID() [2/2]

JP2_Encoder & producer_UUID ( const unsigned char * id )

Set the product producer signature UUID value.

The producer signature UUID value is intended to provide a unique identifier for the product. The UUID will be placed in a UUID List box inside a UUID Info box.

N.B.: A producer signature will only be included in the JP2 file if a PDS label pathname has been specified.

Parameters

id	An array of UUID_SIZE (16) characters (N.B.: This is not a null-terminated character string) containing the product producer UUID value. If NULL no product producer signature is to be used.

Returns: This JP2_Encoder.

References Producer_UUID, and UUID_SIZE.

◆ comment() [1/2]

std::string comment ( ) const

inline

Get the codestream comment.

Returns: The string that will be added as a comment to the codestream. This will be an empty string if no comment is specified.

See also: comment(const std::string& text)

References Comment.

◆ comment() [2/2]

JP2_Encoder & comment ( const std::string & text )

inline

Set comment text to be added to the codestream.

Parameters

text	A string to be added to the codestream as a comment. If the string is empty no comment will be added to the codestream.

Returns: This JP2_Encoder.

See also: comment()

References Comment, and JP2_Encoder().

◆ ready()

bool ready ( ) const

Test if the encoder is ready to compress the image data.

Returns: true if the encoder is ready; false otherwise.

See also: needs() const; reasons() const

References Image_Bands, Image_Size, Image_Source, JP2_Pathname, and Pixel_Bytes.

Referenced by open().

◆ reasons()

string reasons ( ) const

Get a description of the reasons that the encoder is not ready.

Returns: A string describing what the encoder needs. This will be the empty string if the encoder is ready to compress image data.

References Image_Bands, Image_Size, Image_Source, JP2_Pathname, and Pixel_Bytes.

Referenced by open().

◆ needs()

int needs ( ) const

Indicates what the encoder needs to do its job.

The returned bit flag value will be zero if the encoder has all the required user-supplied information. Otherwise it will have one or more of the following bits set:

NEEDS_SOURCE (0): A source PDS file pathname has not been specified.
NEEDS_DESTINATION (1): A destination PDS/JP2 file pathname has not been specified.
NEEDS_IMAGE: The source image structure - image size, number of bands and bytes per pixel - has not been completely defined.

@return A bit flag value.

References Image_Bands, Image_Size, Image_Source, JP2_Pathname, NEEDS_DESTINATION, NEEDS_IMAGE, NEEDS_SOURCE, and Pixel_Bytes.

◆ encoder_error()

JP2_Encoder_Error * encoder_error ( ) const

Get the JP2_Encoder_Error describing the last encoder error that occurred.

The JP2_Encoder_Error contains a Message string data member describing the last error. This will be the empty string if no error has occurred.

Returns: A pointer to a JP2_Encoder_Error object.

Referenced by main().

◆ encode()

long long encode ( )

Encode the image source to a JPEG2000 JP2 destination.

This function is the main workhorse of the class. It is responsible for doing the actual work of generating a JP2 file.

The destination JP2 file is opened. The JP2 metadata boxes are written to the file, including the required header boxes and any user boxes that have been added and the box to contain a producer signature UUID and PDS label filename URL if this has been specified. The source pixel data is written to a codestream box. The completed JP2 file is then closed.

Returns: The number of bytes written to the JP2 file.

References close(), open(), write_codestream(), write_header(), and write_user_boxes().

Referenced by main().

◆ open()

void open ( )

Open the source JP2 file.

References ID, JP2_Pathname, ready(), and reasons().

Referenced by encode(), and write_header().

◆ write_header()

long long write_header ( )

Write the required metadata boxes to the JP2 file.

Returns: The number of bytes written to the JP2 file.

References Bit_Rate, Code_Block_Size, Comment, DEFAULT_RESOLUTION_LEVELS, ID, Image_Bands, Image_Size, incremental_flush_lines(), open(), Pixel_Bits, Pixel_Bytes, Precinct_Sizes, Progression_Order, Quality_Layers, Resolution_Levels, Signed_Data, and Tile_Size.

Referenced by encode(), write_codestream(), and write_user_boxes().

◆ write_user_boxes()

long long write_user_boxes ( )

Write user specified boxes to the JP2 file.

If a PDS label filename has been specified a UUID Info box containing a UUID box with producer signature and a URL box with a relative file reference to the PDS label filename is written to the JP2 file.

Returns: The number of bytes written to the JP2 file.

References Added_Boxes, PDS_Label_Pathname, Producer_UUID, JP2_Box::type_code(), URL_BOX_NAME, UUID_BOX_NAME, UUID_INFO_BOX_NAME, UUID_SIZE, and write_header().

Referenced by encode().

◆ write_codestream()

long long write_codestream ( )

Generate the compressed image data JPEG2000 codestream and write it to the JP2 file.

References Bit_Rate, ENCODER_EXCEPTION, ID, Image_Bands, Image_Size, Image_Source, incremental_flush_lines(), MAX_STRIPE_HEIGHT, MIN_STRIPE_HEIGHT, Pixel_Bits, Pixel_Bytes, Quality_Layers, read_stripe(), and write_header().

Referenced by encode().

◆ incremental_flush_bytes() [1/2]

JP2_Encoder & incremental_flush_bytes ( long long bytes )

inline

Set the rate at which compressed image data will be written to the output JP2 file.

Incremental codestream flushing is when the compressed image data that has accumulated in memory is periodically written to the output JP2 file during the process of codestream generation. Incremental codestream flushing is desirable to avoid retaining the entire codestream in memory when a large image is being processed; the memory requirements to hold the entire codestream may be more than the system can provide. The rate of codestream flushing is controlled by the number of image lines that have been compressed since the last flush or the start of compression. Since the issue of incremental codestream flushing is the amount of system memory that is used this method allows the rate to be expressed in terms of bytes. This should be as large as possible, or zero to disable incremental flushing, to allow for the most efficient compression operations as possible.

However, incremental flushing may not actually occur at the requested rate, or may not occur at all, depending on the progression order and other codestream organization issues. In addition, incremental flushing may generate additional JPEG2000 tile-part segments beyond the initial tile-part segment for each tile, and each of these additional tile-parts will require that additional space be reserved in the tile-part length segments of the main header. Since the actual number of tile-parts generated by incremental flushing depends on the data and thus will not be known until the codestream generation has been completed - at which time the reserved space for the tile-part length segments are overwritten with the actual location information

an estimate of the number of tile-parts is necessary. If the actual number of tile-parts is less than what has been reserved empty tile parts will be provided as place holders. N.B.: If the actual number is larger than what has been reserved the generation of the codestream will fail.

The default flush rate is set at compile time by the value of the INCREMENTAL_FLUSH_BYTES symbol.

Parameters

bytes The requested maximum amount of memory to use in generating the compressed image data codestream before the codestream will be flushed to the output JP2 file. If zero incremental flushing is disabled.

Returns: This JP2_Encoder.

See also: incremental_flush_lines()

References Incremental_Flush_Bytes, and JP2_Encoder().

◆ incremental_flush_bytes() [2/2]

long long incremental_flush_bytes ( ) const

inline

Get the rate at which compressed image data will be written to the output JP2 file.

Returns: The requested maximum amount of memory to use in generating the compressed image data codestream before the codestream will be flushed to the output JP2 file. If zero incremental flushing is disabled.

References Incremental_Flush_Bytes.

Referenced by incremental_flush_lines().

◆ incremental_flush_lines() [1/2]

JP2_Encoder & incremental_flush_lines ( unsigned int lines )

Set the rate at which compressed image data will be written to the output JP2 file.

The incremental flush rate is set in terms of the number of image lines to compress before flushing the codestream from memory to the JP2 file. This will set the maximum flush bytes.

Warning: Since the determining the maximum flush bytes from a number of image lines depends on the image width and number of pixel bytes if these have not yet been set the maximum flush bytes will be set to zero thus disabling incremental flushing.

Parameters

lines The number of image lines to compress before flushing the codestream. If zero incremental flushing is disabled.

References Image_Size, incremental_flush_bytes(), and Pixel_Bytes.

◆ incremental_flush_lines() [2/2]

int incremental_flush_lines ( ) const

Get the rate at which compressed image data will be written to the output JP2 file.

The incremental flush rate, in terms of the number of image lines, is determined by the requested maximum flush bytes. If the maximum flush bytes is zero or the size of an image band is greater than or equal to the maximum flush bytes the flush lines will be zero (no incremental flusing will occur). Otherwise the number of flush lines is set to the height of an image tile. If number of bytes in these image lines for a single band is greater than the maximum flush bytes the number of flush lines is reduced by 1024 until the number of bytes in the lines is less than or equal to the maximum flush bytes.

Returns: The rate, in terms of image lines, at which the compressed image data codestream will be requested to be flushed to the output JP2 file. If zero incremental flushing is disabled.

References Image_Size, Incremental_Flush_Bytes, Pixel_Bytes, and Tile_Size.

Referenced by write_codestream(), and write_header().

◆ close()

long long close ( )

Referenced by encode(), and source().

◆ invalid_precinct_size()

int invalid_precinct_size ( const std::vector< Size_2D > & sizes )

Check for valid precinct sizes.

Valid precinct sizes are non-zero powers of 2.

Parameters

sizes A vector of precinct Size_2D values.

Returns: If all sizes are valid, 0. Otherwise the vector entry number (i.e. index + 1) of the first invalid entry encountered.

References UA::HiRISE::power_of_2().

Referenced by precinct_sizes().

◆ read_stripe() [1/2]

void read_stripe	(	std::istream &	source,
		int	band,
		int	line,
		int	lines,
		kdu_int16 *	buffer )

protected

Fill an image data buffer with pixel data from a source stream.

The lines of source image data starting with the specified line of the specified band are read into the buffer as a contiguous sequence of bytes.

Parameters

source	An istream that has been opened on the source file.
band	The index of the image band from which pixel data is to be read.
line	The starting index of the image line from which pixel data it to be read.
lines	The number of image lines to read.
buffer	Buffer storage to hold at least lines * image_width pixels where each pixel is stored as a 16-bit signed integer.

References ID, Image_Offset, Image_Size, Line_Prefix_Bytes, Line_Suffix_Bytes, Pixel_Bits, Pixel_Bytes, Signed_Data, source(), and Swap_Pixel_Bytes.

Referenced by write_codestream().

◆ read_stripe() [2/2]

void read_stripe	(	std::istream &	source,
		int	band,
		int	line,
		int	lines,
		kdu_int32 *	buffer )

protected

Fill an image data buffer with pixel data from a source stream.

The lines of source image data starting with the specified line of the specified band are read into the buffer as a contiguous sequence of bytes.

Parameters

source	An istream that has been opened on the source file.
band	The index of the image band from which pixel data is to be read.
line	The starting index of the image line from which pixel data it to be read.
lines	The number of image lines to read.
buffer	Buffer storage to hold at least lines * image_width pixels where each pixel is stored as a 32-bit signed integer.

References ID, Image_Offset, Image_Size, Line_Prefix_Bytes, Line_Suffix_Bytes, Pixel_Bits, Pixel_Bytes, Signed_Data, source(), and Swap_Pixel_Bytes.

Member Data Documentation

◆ ID

const char *const ID

static

Initial value:

=

"UA::HiRISE::JP2_Encoder (1.30 2019/03/26 20:51:11)"

Class identification name with source code version and date.

Referenced by code_block_size(), image_size(), open(), pixel_bits(), pixel_bytes(), precinct_size(), precinct_size(), precinct_sizes(), progression_order(), quality_layers(), read_stripe(), read_stripe(), resolution_levels(), write_codestream(), and write_header().

◆ DEFAULT_RESOLUTION_LEVELS

const unsigned int DEFAULT_RESOLUTION_LEVELS = 6

static

Default number of resolution levels.

Referenced by JP2_Encoder(), and write_header().

◆ MAX_RESOLUTION_LEVELS

const unsigned int MAX_RESOLUTION_LEVELS = 32

static

Maximum number of resolution levels.

Referenced by resolution_levels().

◆ MAX_QUALITY_LAYERS

const unsigned int MAX_QUALITY_LAYERS = 16384

static

Maximum number of quality layers.

Referenced by quality_layers().

◆ UUID_INFO_BOX_NAME

const char *const UUID_INFO_BOX_NAME = "uinf"

static

PDS label reference information UUID Info JP2 container box name.

Referenced by write_user_boxes().

◆ UUID_BOX_NAME

const char *const UUID_BOX_NAME = "ulst"

static

Data provider UUID JP2 box name.

Referenced by write_user_boxes().

◆ UUID_SIZE

const int UUID_SIZE = 16

static

Size of the UUID data content.

Referenced by producer_UUID(), and write_user_boxes().

◆ URL_BOX_NAME

const char *const URL_BOX_NAME = "url "

static

PDS label relative filename URL JP2 box name.

Referenced by write_user_boxes().

◆ MIN_STRIPE_HEIGHT

const int MIN_STRIPE_HEIGHT = 256

static

Image data stripe minimum and maximum number of lines.

Referenced by write_codestream().

◆ MAX_STRIPE_HEIGHT

const int MAX_STRIPE_HEIGHT = 8192

static

Referenced by write_codestream().

◆ NEEDS_SOURCE

const int NEEDS_SOURCE = 1 << 0

static

What the encoder needs to do its job.

See also: needs() const

Referenced by needs().

◆ NEEDS_DESTINATION

const int NEEDS_DESTINATION = 1 << 1

static

Referenced by needs().

◆ NEEDS_IMAGE

const int NEEDS_IMAGE = 1 << 2

static

Referenced by needs().

◆ ENCODER_EXCEPTION

const int ENCODER_EXCEPTION = 66

static

JP2_Encoder_Error exception signal value.

Referenced by write_codestream().

◆ Image_Source

std::string Image_Source

protected

Image source pathname.

Referenced by JP2_Encoder(), needs(), ready(), reasons(), source(), source(), and write_codestream().

◆ JP2_Pathname

std::string JP2_Pathname

protected

Image destination pathname.

Referenced by destination(), destination(), JP2_Encoder(), needs(), open(), ready(), and reasons().

◆ Image_Offset

std::streamoff Image_Offset

protected

Image data location as a byte offset within the source file.

Referenced by image_data_location(), image_data_location(), JP2_Encoder(), read_stripe(), and read_stripe().

◆ Image_Bands

unsigned int Image_Bands

protected

Total image bands (components).

Referenced by image_bands(), image_bands(), JP2_Encoder(), needs(), ready(), reasons(), write_codestream(), and write_header().

◆ Image_Size

Size_2D Image_Size

protected

Referenced by image_size(), image_size(), incremental_flush_lines(), incremental_flush_lines(), JP2_Encoder(), needs(), read_stripe(), read_stripe(), ready(), reasons(), write_codestream(), and write_header().

◆ Line_Prefix_Bytes

unsigned int Line_Prefix_Bytes

protected

The number of bytes preceeding and following each line of pixel bytes.

The line prefix and suffix bytes are to be skipped when the image data is being read.

Referenced by JP2_Encoder(), line_prefix_bytes(), line_prefix_bytes(), read_stripe(), and read_stripe().

◆ Line_Suffix_Bytes

unsigned int Line_Suffix_Bytes

protected

Referenced by JP2_Encoder(), line_suffix_bytes(), line_suffix_bytes(), read_stripe(), and read_stripe().

◆ Pixel_Bytes

unsigned int Pixel_Bytes

protected

Pixel datum size in bytes.

Referenced by incremental_flush_lines(), incremental_flush_lines(), JP2_Encoder(), needs(), pixel_bits(), pixel_bytes(), pixel_bytes(), read_stripe(), read_stripe(), ready(), reasons(), signed_data(), write_codestream(), and write_header().

◆ Pixel_Bits

unsigned int Pixel_Bits

protected

Pixel precision bits.

Referenced by JP2_Encoder(), pixel_bits(), pixel_bits(), pixel_bytes(), read_stripe(), read_stripe(), signed_data(), write_codestream(), and write_header().

◆ Signed_Data

bool Signed_Data

protected

Whether pixel data is to be treated as signed.

Referenced by JP2_Encoder(), read_stripe(), read_stripe(), signed_data(), signed_data(), and write_header().

◆ Added_Boxes

JP2_Box::JP2_Box_List Added_Boxes

protected

Referenced by add_box(), added_boxes(), remove_box(), and write_user_boxes().

◆ PDS_Label_Pathname

std::string PDS_Label_Pathname

protected

PDS label file pathname to be placed in a UUID Info URL box.

Referenced by JP2_Encoder(), PDS_label_pathname(), PDS_label_pathname(), and write_user_boxes().

◆ Producer_UUID

unsigned char* Producer_UUID

protected

The UUID to be placed in a UUID List box inside a UUID Info box.

Referenced by JP2_Encoder(), producer_UUID(), producer_UUID(), write_user_boxes(), and ~JP2_Encoder().

◆ Comment

std::string Comment

protected

Comment segment to be added to the codestream.

Referenced by comment(), comment(), and write_header().

◆ Swap_Pixel_Bytes

bool Swap_Pixel_Bytes

protected

Whether pixel bytes should be reordered before be encoded.

Referenced by JP2_Encoder(), MSB_data(), MSB_data(), read_stripe(), read_stripe(), swap_pixel_bytes(), and swap_pixel_bytes().

◆ Resolution_Levels

unsigned int Resolution_Levels

protected

The number of resolution levels to encode.

N.B.: The number of resolution levels is one more than the number of JPEG2000 decomposition levels.

Referenced by JP2_Encoder(), precinct_size(), precinct_sizes(), resolution_levels(), resolution_levels(), and write_header().

◆ Quality_Layers

unsigned int Quality_Layers

protected

Referenced by JP2_Encoder(), quality_layers(), quality_layers(), write_codestream(), and write_header().

◆ Bit_Rate

double Bit_Rate

protected

Referenced by bit_rate(), bit_rate(), JP2_Encoder(), write_codestream(), and write_header().

◆ Progression_Order

std::string Progression_Order

protected

The codestream progression order to be used.

Referenced by JP2_Encoder(), progression_order(), progression_order(), and write_header().

◆ Tile_Size

Size_2D Tile_Size

protected

Tile size for codestream structure organization.

Referenced by incremental_flush_lines(), JP2_Encoder(), tile_size(), tile_size(), and write_header().

◆ Precinct_Sizes

std::vector<Size_2D> Precinct_Sizes

protected

Precinct sizes for codestream structure organization within tiles.

Referenced by JP2_Encoder(), precinct_size(), precinct_size(), precinct_sizes(), precinct_sizes(), resolution_levels(), and write_header().

◆ Code_Block_Size

Size_2D Code_Block_Size

protected

Code block size for codestream packet encoding within precincts.

Referenced by code_block_size(), code_block_size(), JP2_Encoder(), and write_header().

◆ Incremental_Flush_Bytes

long long Incremental_Flush_Bytes

protected

Referenced by incremental_flush_bytes(), incremental_flush_bytes(), incremental_flush_lines(), and JP2_Encoder().

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

Public Member Functions

Static Public Attributes

Protected Member Functions

Protected Attributes

Detailed Description

Constructor & Destructor Documentation

◆ JP2_Encoder()

◆ ~JP2_Encoder()

Member Function Documentation

◆ source() [1/2]

◆ source() [2/2]

◆ destination() [1/2]

◆ destination() [2/2]

◆ PDS_label_pathname() [1/2]

◆ PDS_label_pathname() [2/2]

◆ image_data_location() [1/2]

◆ image_data_location() [2/2]

◆ image_bands() [1/2]

◆ image_bands() [2/2]

◆ image_size() [1/2]

◆ image_size() [2/2]

◆ pixel_bytes() [1/2]

◆ pixel_bytes() [2/2]

◆ pixel_bits() [1/2]

◆ pixel_bits() [2/2]

◆ signed_data() [1/2]

◆ signed_data() [2/2]

◆ MSB_data() [1/2]

◆ MSB_data() [2/2]

◆ swap_pixel_bytes() [1/2]

◆ swap_pixel_bytes() [2/2]

◆ line_prefix_bytes() [1/2]

◆ line_prefix_bytes() [2/2]

◆ line_suffix_bytes() [1/2]

◆ line_suffix_bytes() [2/2]

◆ tile_size() [1/2]

◆ tile_size() [2/2]

◆ resolution_levels() [1/2]

◆ resolution_levels() [2/2]

◆ quality_layers() [1/2]

◆ quality_layers() [2/2]

◆ bit_rate() [1/2]

◆ bit_rate() [2/2]

◆ progression_order() [1/2]

◆ progression_order() [2/2]

◆ precinct_sizes() [1/2]

◆ precinct_size() [1/2]

◆ precinct_sizes() [2/2]

◆ precinct_size() [2/2]

◆ code_block_size() [1/2]

◆ code_block_size() [2/2]

◆ added_boxes()

◆ add_box()

◆ remove_box()

◆ producer_UUID() [1/2]

◆ producer_UUID() [2/2]

◆ comment() [1/2]

◆ comment() [2/2]

◆ ready()

◆ reasons()

◆ needs()

◆ encoder_error()

◆ encode()

◆ open()

◆ write_header()

◆ write_user_boxes()

◆ write_codestream()

◆ incremental_flush_bytes() [1/2]

◆ incremental_flush_bytes() [2/2]

◆ incremental_flush_lines() [1/2]

◆ incremental_flush_lines() [2/2]

◆ close()

◆ invalid_precinct_size()

◆ read_stripe() [1/2]

◆ read_stripe() [2/2]

Member Data Documentation

◆ ID

◆ DEFAULT_RESOLUTION_LEVELS

◆ MAX_RESOLUTION_LEVELS

◆ MAX_QUALITY_LAYERS