A JP2_Decoder decodes image pixel data from a JPEG2000 JP2 image file. More...

#include <JP2_Decoder.hh>

Collaboration diagram for JP2_Decoder:

[legend]

Public Member Functions
	JP2_Decoder ()
	Constructs a JP2_Decoder.
std::string	source () const
	Get the JP2 source pathname.
JP2_Decoder &	source (const std::string &pathname)
	Set the pathname to the JP2 source.
Size_2D	image_size () const
	Get the size of the JP2 source image.
unsigned int	image_width () const
	Get the width of the JP2 source image.
unsigned int	image_height () const
	Get the height of the JP2 source image.
unsigned int	image_bands () const
	Get the number of bands (components) in the JP2 image.
unsigned int	resolution_levels () const
	Get the total number of codestream resolution levels.
unsigned int	pixel_bytes () const
	Get the number of bytes per pixel.
unsigned int	pixel_bits () const
	Get the pixel precision.
bool	signed_data () const
	Get the signedness of the pixel data.
unsigned char *const	producer_UUID () const
	Get the UUID found in the JP2 source.
std::string	URL () const
	Get the URL found in the JP2 source.
std::string	destination () const
	Get the destination file pathname for the rendered image data.
JP2_Decoder &	destination (const std::string &pathname)
	Set the destination file pathname for the rendered image data.
Size_2D	rendered_size () const
	Get the size of the rendered image.
unsigned int	rendered_width () const
	Get the width of the rendered image.
unsigned int	rendered_height () const
	Get the height of the rendered image.
Rectangle	image_region () const
	Get the image region that will be rendered from the JP2 source.
JP2_Decoder &	image_region (const Rectangle &region)
	Set the image region that will be rendered from the JP2 source.
JP2_Decoder &	image_region (int x, int y, int width, int height)
	Set the image region that will be rendered from the JP2 source.
unsigned int	resolution_level () const
	Get the resolution level at which the codestream will be rendered.
JP2_Decoder &	resolution_level (unsigned int level)
	Set the resolution level at which the codestream will be rendered.
bool	swap_pixel_bytes () const
	Tests if multi-byte pixels will be reordered before being written.
JP2_Decoder &	swap_pixel_bytes (bool swap_data)
	Sets whether multi-byte pixels will be reordered before being written.
unsigned long long	bytes_written () const
	Get the number of image data bytes written.
bool	ready () const
	Tests if the decoder has the information it needs to do its job.
std::string	reasons () const
	Describe the reasons that the decoder is not ready.
unsigned long long	decode ()
	Deocde the pixel data from the JPEG2000 JP2 source and write the rendered results to the image data destination.
void	open ()
	Open the source JP2 file.
bool	is_open () const
	Test if the decoder is open.
unsigned long long	write_image_data ()
	Write rendered image data.
void	close ()
	Close access to the JP2 source.
JP2_Decoder_Error *	decoder_error () const

Static Public Attributes
static const char *const	ID
	Class identification name with source code version and date.
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 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	DECODER_EXCEPTION = 67
	JP2_Decoder_Error exception signal value.

Protected Member Functions
std::streamsize	write_stripe (std::ostream &destination, std::streamoff file_offset, int band, int line, int lines, kdu_int16 *buffer)
	Write an image data buffer with pixel data to a stream.
std::streamsize	write_stripe (std::ostream &destination, std::streamoff file_offset, int band, int line, int lines, kdu_int32 *buffer)
	Write an image data buffer with pixel data to a stream.
void	set_resolution_and_region (unsigned int level, const Rectangle &region)
	Set the effective rendering resolution level and image region.

Protected Attributes
std::string	JP2_Pathname
	JP2 source pathname.
unsigned int	Image_Bands
	Total image bands (components).
Size_2D	Image_Size
	Dimensions of the source image.
unsigned int	Pixel_Bytes
	Pixel datum size in bytes.
unsigned int	Pixel_Bits
	Pixel precision bits.
bool	Signed_Data
	Whether pixel data is signed.
unsigned int	Resolution_Levels
	Resolution levels available.
unsigned char *	UUID_Info_UUID
	First UUID value found in a UUID List box of a UUID Info super box.
std::string	UUID_Info_URL
	First URL value found in a URL box of a UUID Info super box.
std::string	Image_Destination
	Image data destination pathname.
Size_2D	Rendered_Size
	Rendered image size.
Rectangle	Image_Region
	Image region to be rendered.
unsigned int	Resolution_Level
	Resolution level to render.
bool	Swap_Pixel_Bytes
	Whether pixel bytes should be reordered when written.
unsigned long long	Bytes_Written
	Total number of pixel bytes written.

Detailed Description

A JP2_Decoder decodes image pixel data from a JPEG2000 JP2 image file.

After a JP2_Decoder is constructed it must be configured. The decoder must be configured with at least an input JP2 source file before it can be opened. Once opened numerous accessors can be used to get information from the JP2 file, especially image data characterization. A JP2_Decoder may be configured to reorder muli-byte pixel data (the codestream is expected to produce MSB ordered data by default), decompress a selected region of the entire image or render at less than the full resolution level. It must also be configured with an output image data destination file to be ready to decode the source which includes opening the source and writing the image data.

A JP2_Decoder may be reused with or without between uses. Other than the source and destination, its configuration is reset to the default values whenever it is closed.

This implementation employs the Kakadu Software libraries.

Author: Bradford Castalia, UA/HiROC

Version: 1.16

Constructor & Destructor Documentation

◆ JP2_Decoder()

JP2_Decoder ( )

Constructs a JP2_Decoder.

The decoder must be configured with at least an input JP2 source before it can be opened. It must also be configured with an output image data destination to be ready to do its job.

Member Function Documentation

◆ source() [1/2]

std::string source ( ) const

inline

Get the JP2 source pathname.

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

◆ source() [2/2]

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

Set the pathname to the JP2 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 JP2 source pathname.

Returns: This JP2_Decoder.

◆ image_size()

Size_2D image_size ( ) const

inline

Get the size of the JP2 source image.

N.B.: Use the image_width() and image_height() methods for fast access to the image size values.

Returns: A Size_2D object containing the image width and height. These values will be zero until the JP2 source has been opened.

◆ image_width()

unsigned int image_width ( ) const

inline

Get the width of the JP2 source image.

Returns: The width of the image in pixels. This will be zero until the JP2 source has been opened.

◆ image_height()

unsigned int image_height ( ) const

inline

Get the height of the JP2 source image.

Returns: The height of the image in lines. This will be zero until the JP2 source has been opened.

◆ image_bands()

unsigned int image_bands ( ) const

inline

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

Returns: The number of bands in the JP2 image. This will be zero until the JP2 source has been opened.

◆ resolution_levels()

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.

The number of resolution levels is determined from the default codestream (COD segment) values. Tile segments may override this value.

Returns: The total number of codestream resolution levels. This will be zero until the JP2 source has been opened.

◆ pixel_bytes()

unsigned int pixel_bytes ( ) const

inline

Get the number of bytes per pixel.

Returns: The number of storage bytes used by each pixel. This will be zero until the JP2 source has been opened.

◆ pixel_bits()

unsigned int pixel_bits ( ) const

inline

Get the pixel precision.

Returns: The number of valid bits used by each pixel. This will be zero until the JP2 source has been opened.

◆ signed_data()

bool signed_data ( ) const

inline

Get the signedness of the pixel data.

Returns: true if the pixel data is treated as signed; false otherwise. This information will be meaningless until the JP2 source has been opened.

◆ producer_UUID()

unsigned char *const producer_UUID ( ) const

inline

Get the UUID found in the JP2 source.

The first UUID value in a UUID List box of a UUID Info super box is copied. There may be additional UUID values, List boxes or Info boxes but these are ignored.

Returns: A 16 byte (UUID_SIZE) array. N.B.: This is not null-terminated C-string character array. If no UUID has been found, or the JP2 source has not been opened, this will be NULL.

◆ URL()

std::string URL ( ) const

inline

Get the URL found in the JP2 source.

The first URL box contents of a UUID Info super box is copied. There may be additional URL boxes but they are ignored.

Returns: A URL string. This will be empty if no URL has been found or the JP2 source has not been opened.

◆ destination() [1/2]

std::string destination ( ) const

inline

Get the destination file pathname for the rendered image data.

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

◆ destination() [2/2]

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

inline

Set the destination file pathname for the rendered image data.

Parameters

pathname The destination file pathname string.

Returns: This JP2_Decoder.

◆ rendered_size()

Size_2D rendered_size ( ) const

Get the size of the rendered image.

Returns: A Size_2D object containing the rendered image width and height. These values will be zero until the JP2 source has been opened.

See also: rendered_width(); rendered_height()

◆ rendered_width()

unsigned int rendered_width ( ) const

Get the width of the rendered image.

Returns: The width of the rendered image in pixels. This will be zero until the JP2 source has been opened.

See also: rendered_size()

◆ rendered_height()

unsigned int rendered_height ( ) const

Get the height of the rendered image.

Returns: The height of the rendered image in lines. This will be zero until the JP2 source has been opened.

See also: rendered_size()

◆ image_region() [1/3]

Rectangle image_region ( ) const

inline

Get the image region that will be rendered from the JP2 source.

Returns: The Rectangle specifying the image region to be rendered. If no image region has been specified and the JP2 source has not yet been opened all the Rectangle values will be zero. When the JP2 source is opened, if no image region has been specified it will be initialized to the entire image size. If an image region has been specified it will be set to the intersection of the image size and the image region.

See also: image_region(const Rectangle&); image_size()

◆ image_region() [2/3]

JP2_Decoder & image_region ( const Rectangle & region )

Set the image region that will be rendered from the JP2 source.

The image region is specified relative to the full resolution image. Specifying a rendering resolution level greater than 1 will result in a correspondingly smaller image region.

The actual image region rendered will be the intersection of the region with the image size.

Parameters

region A Rectangle specifying the image region to be rendered.

Returns: This JP2_Decoder.

Exceptions

out_of_range If the decoder has been opened and selected region does not intersect with the image.

See also: image_region(int, int, int, int)

◆ image_region() [3/3]

JP2_Decoder & image_region	(	int	x,
		int	y,
		int	width,
		int	height )

Set the image region that will be rendered from the JP2 source.

Parameters

x	The horizontal (x-axis) position of the image region.
y	The vertical (y-axis) position of the image region.
width	The width of the image region.
height	The height of the image region.

Returns: This JP2_Decoder.

Exceptions

out_of_range If the decoder has been opened and selected region does not intersect with the image.

See also: image_region(const Rectangle&)

◆ resolution_level() [1/2]

unsigned int resolution_level ( ) const

inline

Get the resolution level at which the codestream will be rendered.

Returns: The codestream rendering resolution level.

See also: resolution_level(unsigned int)

◆ resolution_level() [2/2]

JP2_Decoder & resolution_level ( unsigned int level )

Set the resolution level at which the codestream will be rendered.

Level 1 is full resolution. Level 2 renders the image at half size, level 3 at quarter size, etc.; i.e. the image size is divided by 2**(level-1).

N.B.: The resolution level is one more than the JPEG2000 decomposition level.

Parameters

level The codestream rendering resolution level.

Returns: This JP2_Encoder.

Exceptions

out_of_range If the decoder has been opened since the image region was previously set and selected region does not intersect with the image.

◆ swap_pixel_bytes() [1/2]

bool swap_pixel_bytes ( ) const

inline

Tests if multi-byte pixels will be reordered before being written.

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

◆ swap_pixel_bytes() [2/2]

JP2_Decoder & swap_pixel_bytes ( bool swap_data )

inline

Sets whether multi-byte pixels will be reordered before being written.

By default multi-byte pixels will not be reordered. N.B.: The pixel data rendered from the JP2 file has no defined order. It is necessary to obtain correct pixel data ordering information elsewhere.

Parameters

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

Returns: This JP2_Decoder.

◆ bytes_written()

unsigned long long bytes_written ( ) const

inline

Get the number of image data bytes written.

Returns: The number of image data bytes written.

◆ ready()

bool ready ( ) const

Tests if the decoder has the information it needs to do its job.

Both the JP2 source and rendered image destination must be specified.

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

◆ reasons()

string reasons ( ) const

Describe the reasons that the decoder is not ready.

Returns: A string, possibly of more than one line, that decribes the reasons for the decoder not being ready. This will be the empty string if the decoder is ready.

See also: ready()

◆ decode()

unsigned long long decode ( )

Deocde the pixel data from the JPEG2000 JP2 source and write the rendered results to the image data destination.

The JP2 source is opened, the contents are rendered and written to the destination file, and then the source is closed.

Returns: The number of bytes written to the image data file.

◆ open()

void open ( )

Open the source JP2 file.

If the source is already open nothing is done.

Access to the JP2 source is opened and checked that it contains the required JP2 format content. The producer_UUID() and URL are extracted, if present. The image characterization - image_bands(), image_size(), pixel_bytes(), pixel_bits() and resolution_levels() - are determined. If the resolution level to be rendered is greater than the number of resolution levels, it is reduced to the maximum value. All the bands are compared to make suse they have the same image and pixel structure. The selected image_region(const Rectangle&), if any, is clipped to the image extent.

Exceptions

logic_error	If no `JP2 source` has been specified
out_of_range	If any of the image bands (JP2 components) do not have identical image structure (image and pixel).
out_of_range	If the selected image region does not intersect the image extent.

◆ is_open()

bool is_open ( ) const

Test if the decoder is open.

Returns: true if this JP2_Decoder has been successfully opened and not yet closed; false otherwise.

◆ write_image_data()

unsigned long long write_image_data ( )

Write rendered image data.

The JP2 source is opened if this has not yet been done, and the decoder is checked that it is ready. Data buffers to hold horizontal stripes of rendered image data are allocated.

The destination file is opened for writing. N.B.: If the file already exists the image data will be appended to the current content.

Returns: The number of image data bytes that were written to the destination file.

Exceptions

logic_error	If the decoder is not ready().
runtime_error	If insufficient memory is available to allocate the rendered image data buffers.

◆ close()

void close ( )

Close access to the JP2 source.

The JP2 source stream is closed and all resources associated with it are deleted. In addition, the JP2 source image characterization information - image_bands(), image_size(), pixel_bytes(), pixel_bits(), resolution_levels() producer_UUID() and URL() - is reset to the unknown state. However, neither the source() nor destination() pathname is reset so this JP2_Decoder is ready to be reused.

N.B.: Output specifications remain unchanged.

◆ decoder_error()

JP2_Decoder_Error * decoder_error ( ) const

◆ write_stripe() [1/2]

std::streamsize write_stripe	(	std::ostream &	destination,
		std::streamoff	file_offset,
		int	band,
		int	line,
		int	lines,
		kdu_int16 *	buffer )

protected

Write an image data buffer with pixel data to a stream.

The contents of the data buffer are expected to contain the results of codestream decoding of a horizontal stripe of the source image. This data is modified in place to adjust for data order and signedness.

The lines of image data starting with the specified line of the specified band are written to the buffer as a contiguous sequence of bytes.

Parameters

destination	An ostream that has been opened on the destination file.
file_offset	File offset to the start of the image data.
band	The index of the image band to which pixel data is to be written.
line	The starting index of the image line to which pixel data it to be written.
lines	The number of image lines to write.
buffer	Buffer storage containing lines * image_width pixels where each pixel is stored as a 16-bit signed integer.

Returns: The number of image data bytes that were written to the destination file.

◆ write_stripe() [2/2]

std::streamsize write_stripe	(	std::ostream &	destination,
		std::streamoff	file_offset,
		int	band,
		int	line,
		int	lines,
		kdu_int32 *	buffer )

protected

Write an image data buffer with pixel data to a stream.

The contents of the data buffer are expected to contain the results of codestream decoding of a horizontal stripe of the source image. This data is modified in place to adjust for data order and signedness.

The lines of image data starting with the specified line of the specified band are written to the buffer as a contiguous sequence of bytes.

Parameters

destination	An ostream that has been opened on the destination file.
file_offset	File offset to the start of the image data.
band	The index of the image band to which pixel data is to be written.
line	The starting index of the image line to which pixel data it to be written.
lines	The number of image lines to write.
buffer	Buffer storage containing lines * image_width pixels where each pixel is stored as a 16-bit signed integer.

Returns: The number of image data bytes that were written to the destination file.

◆ set_resolution_and_region()

void set_resolution_and_region	(	unsigned int	level,
		const Rectangle &	region )

protected

Set the effective rendering resolution level and image region.

The resolution level and image region interact to affect the rendered image size so they are set together.

If the decoder has not been opened nothing is done.

The efective resolution level is limited to the range 1-resolution levels and applied as an input restriction on the codestream rendering machinery. Any existing image area restriction is lifted at the same time.

If the image region is empty the entire image size is used as the effective image region. Otherwise the dimensions of the image region are adjusted by the resolution level (divided by 2**(level - 1)), intersected with the image size at the rendering resolution and the resulting effective image region is applied as an input restriction on the codestream rendering machinery.

The effective rendered image size is set.

Parameters

level	The rendering resolution level.
region	The selected image area to be rendered relative to the full resolution image.

Exceptions

out_of_range If the selected image are does not intersect with the source image.

Member Data Documentation

◆ ID

const char *const ID

static

Initial value:

=

"UA::HiRISE::JP2_Decoder (1.22 2019/03/26 20:51:11)"

Class identification name with source code version and date.

◆ UUID_INFO_BOX_NAME

const char *const UUID_INFO_BOX_NAME = "uinf"

static

PDS label reference information UUID Info JP2 container box name.

This is the minimum number of available resolution levels as determined from the default coding style (COD) information. The minimum resolution level available in the tile segments may be lower still, but that won't be known until the tiles have been read.

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

◆ UUID_Info_UUID

unsigned char* UUID_Info_UUID

◆ Swap_Pixel_Bytes

bool Swap_Pixel_Bytes

protected

Whether pixel bytes should be reordered when written.

◆ Bytes_Written

unsigned long long Bytes_Written

protected

Total number of pixel bytes written.

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_Decoder()

Member Function Documentation

◆ source() [1/2]

◆ source() [2/2]

◆ image_size()

◆ image_width()

◆ image_height()

◆ image_bands()

◆ resolution_levels()

◆ pixel_bytes()

◆ pixel_bits()

◆ signed_data()

◆ producer_UUID()

◆ URL()

◆ destination() [1/2]

◆ destination() [2/2]

◆ rendered_size()

◆ rendered_width()

◆ rendered_height()

◆ image_region() [1/3]

◆ image_region() [2/3]

◆ image_region() [3/3]

◆ resolution_level() [1/2]

◆ resolution_level() [2/2]

◆ swap_pixel_bytes() [1/2]

◆ swap_pixel_bytes() [2/2]

◆ bytes_written()

◆ ready()

◆ reasons()

◆ decode()

◆ open()

◆ is_open()

◆ write_image_data()

◆ close()

◆ decoder_error()

◆ write_stripe() [1/2]

◆ write_stripe() [2/2]

◆ set_resolution_and_region()

Member Data Documentation

◆ ID

◆ UUID_INFO_BOX_NAME

◆ UUID_BOX_NAME

◆ URL_BOX_NAME

◆ MIN_STRIPE_HEIGHT

◆ MAX_STRIPE_HEIGHT

◆ DECODER_EXCEPTION

◆ JP2_Pathname

◆ Image_Bands

◆ Image_Size

◆ Pixel_Bytes

◆ Pixel_Bits

◆ Signed_Data

◆ Resolution_Levels

◆ UUID_Info_UUID

◆ UUID_Info_URL

◆ Image_Destination

◆ Rendered_Size

◆ Image_Region

◆ Resolution_Level

◆ Swap_Pixel_Bytes

◆ Bytes_Written