PDS_JP2
|
A JP2_Decoder decodes image pixel data from a JPEG2000 JP2 image file. More...
#include <JP2_Decoder.hh>
Public Member Functions | |
JP2_Decoder () | |
Constructs a JP2_Decoder. More... | |
std::string | source () const |
Get the JP2 source pathname. More... | |
JP2_Decoder & | source (const std::string &pathname) |
Set the pathname to the JP2 source. More... | |
Size_2D | image_size () const |
Get the size of the JP2 source image. More... | |
unsigned int | image_width () const |
Get the width of the JP2 source image. More... | |
unsigned int | image_height () const |
Get the height of the JP2 source image. More... | |
unsigned int | image_bands () const |
Get the number of bands (components) in the JP2 image. More... | |
unsigned int | resolution_levels () const |
Get the total number of codestream resolution levels. More... | |
unsigned int | pixel_bytes () const |
Get the number of bytes per pixel. More... | |
unsigned int | pixel_bits () const |
Get the pixel precision. More... | |
bool | signed_data () const |
Get the signedness of the pixel data. More... | |
unsigned char *const | producer_UUID () const |
Get the UUID found in the JP2 source. More... | |
std::string | URL () const |
Get the URL found in the JP2 source. More... | |
std::string | destination () const |
Get the destination file pathname for the rendered image data. More... | |
JP2_Decoder & | destination (const std::string &pathname) |
Set the destination file pathname for the rendered image data. More... | |
Size_2D | rendered_size () const |
Get the size of the rendered image. More... | |
unsigned int | rendered_width () const |
Get the width of the rendered image. More... | |
unsigned int | rendered_height () const |
Get the height of the rendered image. More... | |
Rectangle | image_region () const |
Get the image region that will be rendered from the JP2 source. More... | |
JP2_Decoder & | image_region (const Rectangle ®ion) |
Set the image region that will be rendered from the JP2 source. More... | |
JP2_Decoder & | image_region (int x, int y, int width, int height) |
Set the image region that will be rendered from the JP2 source. More... | |
unsigned int | resolution_level () const |
Get the resolution level at which the codestream will be rendered. More... | |
JP2_Decoder & | resolution_level (unsigned int level) |
Set the resolution level at which the codestream will be rendered. More... | |
bool | swap_pixel_bytes () const |
Tests if multi-byte pixels will be reordered before being written. More... | |
JP2_Decoder & | swap_pixel_bytes (bool swap_data) |
Sets whether multi-byte pixels will be reordered before being written. More... | |
unsigned long long | bytes_written () const |
Get the number of image data bytes written. More... | |
bool | ready () const |
Tests if the decoder has the information it needs to do its job. More... | |
std::string | reasons () const |
Describe the reasons that the decoder is not ready. More... | |
unsigned long long | decode () |
Deocde the pixel data from the JPEG2000 JP2 source and write the rendered results to the image data destination. More... | |
void | open () |
Open the source JP2 file. More... | |
bool | is_open () const |
Test if the decoder is open. More... | |
unsigned long long | write_image_data () |
Write rendered image data. More... | |
void | close () |
Close access to the JP2 source. More... | |
JP2_Decoder_Error * | decoder_error () const |
Static Public Attributes | |
static const char *const | ID |
Class identification name with source code version and date. More... | |
static const char *const | UUID_INFO_BOX_NAME = "uinf" |
PDS label reference information UUID Info JP2 container box name. More... | |
static const char *const | UUID_BOX_NAME = "ulst" |
Data provider UUID JP2 box name. More... | |
static const char *const | URL_BOX_NAME = "url " |
PDS label relative filename URL JP2 box name. More... | |
static const int | MIN_STRIPE_HEIGHT = 256 |
Image data stripe minimum and maximum number of lines. More... | |
static const int | MAX_STRIPE_HEIGHT = 8192 |
static const int | DECODER_EXCEPTION = 67 |
JP2_Decoder_Error exception signal value. More... | |
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. More... | |
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. More... | |
void | set_resolution_and_region (unsigned int level, const Rectangle ®ion) |
Set the effective rendering resolution level and image region. More... | |
Protected Attributes | |
std::string | JP2_Pathname |
JP2 source pathname. More... | |
unsigned int | Image_Bands |
Total image bands (components). More... | |
Size_2D | Image_Size |
Dimensions of the source image. More... | |
unsigned int | Pixel_Bytes |
Pixel datum size in bytes. More... | |
unsigned int | Pixel_Bits |
Pixel precision bits. More... | |
bool | Signed_Data |
Whether pixel data is signed. More... | |
unsigned int | Resolution_Levels |
Resolution levels available. More... | |
unsigned char * | UUID_Info_UUID |
First UUID value found in a UUID List box of a UUID Info super box. More... | |
std::string | UUID_Info_URL |
First URL value found in a URL box of a UUID Info super box. More... | |
std::string | Image_Destination |
Image data destination pathname. More... | |
Size_2D | Rendered_Size |
Rendered image size. More... | |
Rectangle | Image_Region |
Image region to be rendered. More... | |
unsigned int | Resolution_Level |
Resolution level to render. More... | |
bool | Swap_Pixel_Bytes |
Whether pixel bytes should be reordered when written. More... | |
unsigned long long | Bytes_Written |
Total number of pixel bytes written. More... | |
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 { open() 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 { swap_pixel_bytes(bool) reorder} muli-byte pixel data (the codestream is expected to produce MSB ordered data by default), decompress a selected image_region(const Rectangle&) region} of the entire image or render at less than the full { resolution_level(unsigned int) resolution level}. It must also be configured with an output image data { destination(const std::string&) destination} file to be { ready() ready} to decode() decode} the source which includes opening the source and write_image_data() 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 close() closed}. This implementation employs the Kakadu Software libraries.
JP2_Decoder | ( | ) |
Constructs a JP2_Decoder.
The decoder must be configured with at least an input JP2 {source} before it can be open() opened}. It must also be configured with an output image data { destination(const std::string&) destination} to be ready() ready} to do its job.
|
inline |
Get the JP2 source pathname.
Referenced by main().
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.
pathname | The JP2 source pathname. |
References JP2_Decoder::close(), and JP2_Decoder::JP2_Pathname.
|
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.
Referenced by JP2_Decoder::open(), and JP2_Decoder::set_resolution_and_region().
|
inline |
|
inline |
|
inline |
|
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.
Referenced by main().
|
inline |
|
inline |
Get the pixel precision.
Referenced by main(), and JP2_Decoder::open().
|
inline |
Get the signedness of the pixel data.
Referenced by main(), and JP2_Decoder::open().
|
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.
Referenced by main().
|
inline |
|
inline |
Get the destination file pathname for the rendered image data.
Referenced by main(), and JP2_Decoder::write_stripe().
|
inline |
Set the destination file pathname for the rendered image data.
pathname | The destination file pathname string. |
Size_2D rendered_size | ( | ) | const |
Get the size of the rendered image.
References JP2_Decoder::Rendered_Size.
unsigned int rendered_width | ( | ) | const |
Get the width of the rendered image.
References JP2_Decoder::Rendered_Size, and Size_2D::Width.
Referenced by main().
unsigned int rendered_height | ( | ) | const |
Get the height of the rendered image.
References Size_2D::Height, and JP2_Decoder::Rendered_Size.
Referenced by main().
|
inline |
Get the image region that will be rendered from the JP2 source.
Referenced by JP2_Decoder::image_region(), and main().
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.
region | A Rectangle specifying the image region to be rendered. |
out_of_range | If the decoder has been opened and selected region does not intersect with the image. |
References Size_2D::Height, JP2_Decoder::image_region(), Size_2D::Width, Point_2D::X, and Point_2D::Y.
JP2_Decoder & image_region | ( | int | x, |
int | y, | ||
int | width, | ||
int | height | ||
) |
Set the image region that will be rendered from the JP2 source.
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. |
out_of_range | If the decoder has been opened and selected region does not intersect with the image. |
References Size_2D::Height, JP2_Decoder::Image_Region, JP2_Decoder::Resolution_Level, JP2_Decoder::set_resolution_and_region(), Size_2D::Width, Point_2D::X, and Point_2D::Y.
|
inline |
Get the resolution level at which the codestream will be rendered.
Referenced by main().
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.
level | The codestream rendering resolution level. |
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. |
References JP2_Decoder::Image_Region, JP2_Decoder::Resolution_Level, and JP2_Decoder::set_resolution_and_region().
|
inline |
Tests if multi-byte pixels will be reordered before being written.
Referenced by main().
|
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.
swap_data | true if multi-byte pixels are to be reordered before writing; false otherwise. |
|
inline |
Get the number of image data bytes written.
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.
References JP2_Decoder::Image_Destination, and JP2_Decoder::JP2_Pathname.
Referenced by JP2_Decoder::write_image_data().
string reasons | ( | ) | const |
Describe the reasons that the decoder is not ready.
References JP2_Decoder::Image_Destination, and JP2_Decoder::JP2_Pathname.
Referenced by JP2_Decoder::write_image_data().
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.
References JP2_Decoder::Bytes_Written, JP2_Decoder::close(), JP2_Decoder::open(), and JP2_Decoder::write_image_data().
Referenced by main().
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.
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. |
References box_name(), box_type(), Size_2D::Height, JP2_Decoder::ID, JP2_Decoder::Image_Bands, JP2_Decoder::Image_Region, JP2_Decoder::image_size(), JP2_Decoder::Image_Size, JP2_Decoder::is_open(), JP2_Decoder::JP2_Pathname, JP2_Decoder::pixel_bits(), JP2_Decoder::Pixel_Bits, JP2_Decoder::Pixel_Bytes, JP2_Decoder::Resolution_Level, JP2_Decoder::Resolution_Levels, JP2_Decoder::set_resolution_and_region(), JP2_Decoder::signed_data(), JP2_Decoder::Signed_Data, JP2_Decoder::URL_BOX_NAME, JP2_Decoder::UUID_BOX_NAME, JP2_Decoder::UUID_INFO_BOX_NAME, JP2_Decoder::UUID_Info_URL, JP2_Decoder::UUID_Info_UUID, UUID_SIZE, and Size_2D::Width.
Referenced by JP2_Decoder::decode(), main(), and JP2_Decoder::write_image_data().
bool is_open | ( | ) | const |
Test if the decoder is open.
Referenced by JP2_Decoder::open(), JP2_Decoder::set_resolution_and_region(), and JP2_Decoder::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.
logic_error | If the decoder is not ready(). |
runtime_error | If insufficient memory is available to allocate the rendered image data buffers. |
References JP2_Decoder::Bytes_Written, file_exists(), file_size(), JP2_Decoder::ID, JP2_Decoder::Image_Bands, JP2_Decoder::Image_Destination, JP2_Decoder::is_open(), JP2_Decoder::MAX_STRIPE_HEIGHT, JP2_Decoder::MIN_STRIPE_HEIGHT, JP2_Decoder::open(), JP2_Decoder::Pixel_Bits, JP2_Decoder::Pixel_Bytes, JP2_Decoder::ready(), JP2_Decoder::reasons(), JP2_Decoder::Rendered_Size, Size_2D::Width, and JP2_Decoder::write_stripe().
Referenced by JP2_Decoder::decode().
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.
References Size_2D::Height, JP2_Decoder::Image_Bands, JP2_Decoder::Image_Region, JP2_Decoder::Image_Size, JP2_Decoder::Pixel_Bits, JP2_Decoder::Pixel_Bytes, JP2_Decoder::Rendered_Size, JP2_Decoder::Resolution_Level, JP2_Decoder::Resolution_Levels, JP2_Decoder::UUID_Info_URL, JP2_Decoder::UUID_Info_UUID, Size_2D::Width, Point_2D::X, and Point_2D::Y.
Referenced by JP2_Decoder::decode(), and JP2_Decoder::source().
JP2_Decoder_Error * decoder_error | ( | ) | const |
Referenced by main().
|
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.
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. |
References JP2_Decoder::destination(), Size_2D::Height, JP2_Decoder::ID, JP2_Decoder::Pixel_Bits, JP2_Decoder::Pixel_Bytes, JP2_Decoder::Rendered_Size, JP2_Decoder::Signed_Data, JP2_Decoder::Swap_Pixel_Bytes, and Size_2D::Width.
Referenced by JP2_Decoder::write_image_data().
|
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.
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. |
References JP2_Decoder::destination(), Size_2D::Height, JP2_Decoder::ID, JP2_Decoder::Pixel_Bits, JP2_Decoder::Pixel_Bytes, JP2_Decoder::Rendered_Size, JP2_Decoder::Signed_Data, swap_bytes(), JP2_Decoder::Swap_Pixel_Bytes, and Size_2D::Width.
|
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.
References Size_2D::area(), Size_2D::Height, JP2_Decoder::ID, JP2_Decoder::Image_Region, JP2_Decoder::image_size(), JP2_Decoder::Image_Size, JP2_Decoder::is_open(), JP2_Decoder::Rendered_Size, JP2_Decoder::Resolution_Level, JP2_Decoder::Resolution_Levels, Size_2D::Width, Point_2D::X, and Point_2D::Y.
Referenced by JP2_Decoder::image_region(), JP2_Decoder::open(), and JP2_Decoder::resolution_level().
|
static |
Class identification name with source code version and date.
Referenced by JP2_Decoder::open(), JP2_Decoder::set_resolution_and_region(), JP2_Decoder::write_image_data(), and JP2_Decoder::write_stripe().
|
static |
PDS label reference information UUID Info JP2 container box name.
Referenced by JP2_Decoder::open().
|
static |
Data provider UUID JP2 box name.
Referenced by JP2_Decoder::open().
|
static |
PDS label relative filename URL JP2 box name.
Referenced by JP2_Decoder::open().
|
static |
Image data stripe minimum and maximum number of lines.
Referenced by JP2_Decoder::write_image_data().
|
static |
Referenced by JP2_Decoder::write_image_data().
|
static |
JP2_Decoder_Error exception signal value.
|
protected |
JP2 source pathname.
Referenced by JP2_Decoder::open(), JP2_Decoder::ready(), JP2_Decoder::reasons(), and JP2_Decoder::source().
|
protected |
Total image bands (components).
Referenced by JP2_Decoder::close(), JP2_Decoder::open(), and JP2_Decoder::write_image_data().
|
protected |
Dimensions of the source image.
Referenced by JP2_Decoder::close(), JP2_Decoder::open(), and JP2_Decoder::set_resolution_and_region().
|
protected |
Pixel datum size in bytes.
Referenced by JP2_Decoder::close(), JP2_Decoder::open(), JP2_Decoder::write_image_data(), and JP2_Decoder::write_stripe().
|
protected |
Pixel precision bits.
Referenced by JP2_Decoder::close(), JP2_Decoder::open(), JP2_Decoder::write_image_data(), and JP2_Decoder::write_stripe().
|
protected |
Whether pixel data is signed.
Referenced by JP2_Decoder::open(), and JP2_Decoder::write_stripe().
|
protected |
Resolution levels available.
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.
Referenced by JP2_Decoder::close(), JP2_Decoder::open(), and JP2_Decoder::set_resolution_and_region().
|
protected |
First UUID value found in a UUID List box of a UUID Info super box.
This will be NULL if no UUID has been found. It will be a 16 byte (UUID_SIZE) array otherwise.
Referenced by JP2_Decoder::close(), and JP2_Decoder::open().
|
protected |
First URL value found in a URL box of a UUID Info super box.
Referenced by JP2_Decoder::close(), and JP2_Decoder::open().
|
protected |
Image data destination pathname.
Referenced by JP2_Decoder::ready(), JP2_Decoder::reasons(), and JP2_Decoder::write_image_data().
|
protected |
Rendered image size.
Referenced by JP2_Decoder::close(), JP2_Decoder::rendered_height(), JP2_Decoder::rendered_size(), JP2_Decoder::rendered_width(), JP2_Decoder::set_resolution_and_region(), JP2_Decoder::write_image_data(), and JP2_Decoder::write_stripe().
|
protected |
Image region to be rendered.
Referenced by JP2_Decoder::close(), JP2_Decoder::image_region(), JP2_Decoder::open(), JP2_Decoder::resolution_level(), and JP2_Decoder::set_resolution_and_region().
|
protected |
Resolution level to render.
N.B.: The resolution level is one more than the JPEG2000 decomposition level.
Referenced by JP2_Decoder::close(), JP2_Decoder::image_region(), JP2_Decoder::open(), JP2_Decoder::resolution_level(), and JP2_Decoder::set_resolution_and_region().
|
protected |
Whether pixel bytes should be reordered when written.
Referenced by JP2_Decoder::write_stripe().
|
protected |
Total number of pixel bytes written.
Referenced by JP2_Decoder::decode(), and JP2_Decoder::write_image_data().