HDK
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
ImageSpec Class Reference

#include <imageio.h>

Public Types

enum  SerialFormat { SerialText, SerialXML }
 
enum  SerialVerbose { SerialBrief, SerialDetailed, SerialDetailedHuman }
 

Public Member Functions

 ImageSpec (TypeDesc format=TypeDesc::UNKNOWN)
 
 ImageSpec (int xres, int yres, int nchans, TypeDesc fmt=TypeDesc::UINT8)
 
 ImageSpec (const ROI &roi, TypeDesc fmt=TypeDesc::UINT8)
 
void set_format (TypeDesc fmt)
 Set the data format. More...
 
void default_channel_names ()
 
size_t channel_bytes () const
 
size_t channel_bytes (int chan, bool native=false) const
 
size_t pixel_bytes (bool native=false) const
 
size_t pixel_bytes (int chbegin, int chend, bool native=false) const
 
imagesize_t scanline_bytes (bool native=false) const
 
imagesize_t tile_pixels () const
 
imagesize_t tile_bytes (bool native=false) const
 
imagesize_t image_pixels () const
 
imagesize_t image_bytes (bool native=false) const
 
bool size_t_safe () const
 
void attribute (string_view name, TypeDesc type, const void *value)
 
void attribute (string_view name, TypeDesc type, string_view value)
 
void attribute (string_view name, unsigned int value)
 
void attribute (string_view name, int value)
 
void attribute (string_view name, float value)
 
void attribute (string_view name, string_view value)
 
void erase_attribute (string_view name, TypeDesc searchtype=TypeDesc::UNKNOWN, bool casesensitive=false)
 
ParamValuefind_attribute (string_view name, TypeDesc searchtype=TypeDesc::UNKNOWN, bool casesensitive=false)
 
const ParamValuefind_attribute (string_view name, TypeDesc searchtype=TypeDesc::UNKNOWN, bool casesensitive=false) const
 
const ParamValuefind_attribute (string_view name, ParamValue &tmpparam, TypeDesc searchtype=TypeDesc::UNKNOWN, bool casesensitive=false) const
 
int get_int_attribute (string_view name, int defaultval=0) const
 
float get_float_attribute (string_view name, float defaultval=0) const
 
string_view get_string_attribute (string_view name, string_view defaultval=string_view()) const
 
std::string serialize (SerialFormat format, SerialVerbose verbose=SerialDetailed) const
 Convert ImageSpec class into a serialized string. More...
 
std::string to_xml () const
 
void from_xml (const char *xml)
 
std::pair< string_view, intdecode_compression_metadata (string_view defaultcomp="", int defaultqual=-1) const
 
bool valid_tile_range (int xbegin, int xend, int ybegin, int yend, int zbegin, int zend)
 
TypeDesc channelformat (int chan) const
 
string_view channel_name (int chan) const
 
void get_channelformats (std::vector< TypeDesc > &formats) const
 
int channelindex (string_view name) const
 Return the index of the named channel, or -1 if not found. More...
 
ROI roi () const
 Return pixel data window for this ImageSpec as a ROI. More...
 
ROI roi_full () const
 Return full/display window for this ImageSpec as a ROI. More...
 
void set_roi (const ROI &r)
 
void set_roi_full (const ROI &r)
 
void copy_dimensions (const ImageSpec &other)
 
bool undefined () const
 

Static Public Member Functions

static void auto_stride (stride_t &xstride, stride_t &ystride, stride_t &zstride, stride_t channelsize, int nchannels, int width, int height)
 
static void auto_stride (stride_t &xstride, stride_t &ystride, stride_t &zstride, TypeDesc format, int nchannels, int width, int height)
 
static void auto_stride (stride_t &xstride, TypeDesc format, int nchannels)
 
static std::string metadata_val (const ParamValue &p, bool human=false)
 

Public Attributes

int x
 
int y
 
int z
 origin (upper left corner) of pixel data More...
 
int width
 width of the pixel data window More...
 
int height
 height of the pixel data window More...
 
int depth
 depth of pixel data, >1 indicates a "volume" More...
 
int full_x
 origin of the full (display) window More...
 
int full_y
 origin of the full (display) window More...
 
int full_z
 origin of the full (display) window More...
 
int full_width
 width of the full (display) window More...
 
int full_height
 height of the full (display) window More...
 
int full_depth
 depth of the full (display) window More...
 
int tile_width
 tile width (0 for a non-tiled image) More...
 
int tile_height
 tile height (0 for a non-tiled image) More...
 
int tile_depth
 
int nchannels
 number of image channels, e.g., 4 for RGBA More...
 
TypeDesc format
 data format of the channels More...
 
std::vector< TypeDescchannelformats
 Optional per-channel formats. More...
 
std::vector< std::stringchannelnames
 
int alpha_channel
 Index of alpha channel, or -1 if not known. More...
 
int z_channel
 Index of depth channel, or -1 if not known. More...
 
bool deep
 Contains deep data. More...
 
ParamValueList extra_attribs
 Additional attributes. More...
 

Detailed Description

ImageSpec describes the data format of an image – dimensions, layout, number and meanings of image channels.

Definition at line 225 of file imageio.h.

Member Enumeration Documentation

Enumerator
SerialText 
SerialXML 

Definition at line 477 of file imageio.h.

Enumerator
SerialBrief 
SerialDetailed 
SerialDetailedHuman 

Definition at line 478 of file imageio.h.

Constructor & Destructor Documentation

ImageSpec::ImageSpec ( TypeDesc  format = TypeDesc::UNKNOWN)

Constructor: given just the data format, set all other fields to something reasonable.

ImageSpec::ImageSpec ( int  xres,
int  yres,
int  nchans,
TypeDesc  fmt = TypeDesc::UINT8 
)

Constructor for simple 2D scanline image with nothing special. If fmt is not supplied, default to unsigned 8-bit data.

ImageSpec::ImageSpec ( const ROI roi,
TypeDesc  fmt = TypeDesc::UINT8 
)
explicit

Constructor from an ROI that gives x, y, z, and channel range, and a data format.

Member Function Documentation

void ImageSpec::attribute ( string_view  name,
TypeDesc  type,
const void value 
)

Add an optional attribute to the extra attribute list

void ImageSpec::attribute ( string_view  name,
TypeDesc  type,
string_view  value 
)

Add an optional attribute to the extra attribute list.

void ImageSpec::attribute ( string_view  name,
unsigned int  value 
)
inline

Add an unsigned int attribute

Definition at line 399 of file imageio.h.

void ImageSpec::attribute ( string_view  name,
int  value 
)
inline

Add an int attribute

Definition at line 405 of file imageio.h.

void ImageSpec::attribute ( string_view  name,
float  value 
)
inline

Add a float attribute

Definition at line 411 of file imageio.h.

void ImageSpec::attribute ( string_view  name,
string_view  value 
)
inline

Add a string attribute

Definition at line 417 of file imageio.h.

static void ImageSpec::auto_stride ( stride_t xstride,
stride_t ystride,
stride_t zstride,
stride_t  channelsize,
int  nchannels,
int  width,
int  height 
)
inlinestatic

Adjust the stride values, if set to AutoStride, to be the right sizes for contiguous data with the given format, channels, width, height.

Definition at line 361 of file imageio.h.

static void ImageSpec::auto_stride ( stride_t xstride,
stride_t ystride,
stride_t zstride,
TypeDesc  format,
int  nchannels,
int  width,
int  height 
)
inlinestatic

Adjust the stride values, if set to AutoStride, to be the right sizes for contiguous data with the given format, channels, width, height.

Definition at line 375 of file imageio.h.

static void ImageSpec::auto_stride ( stride_t xstride,
TypeDesc  format,
int  nchannels 
)
inlinestatic

Adjust xstride, if set to AutoStride, to be the right size for contiguous data with the given format and channels.

Definition at line 384 of file imageio.h.

size_t ImageSpec::channel_bytes ( ) const
inline

Return the number of bytes for each channel datum, assuming they are all stored using the data format given by this->format.

Definition at line 282 of file imageio.h.

size_t ImageSpec::channel_bytes ( int  chan,
bool  native = false 
) const

Return the number of bytes needed for the single specified channel. If native is false (default), compute the size of one channel of this->format, but if native is true, compute the size of the channel in terms of the "native" data format of that channel as stored in the file.

string_view ImageSpec::channel_name ( int  chan) const
inline

Return the channel name of the given channel. This is safe even if channelnames is not filled out.

Definition at line 522 of file imageio.h.

TypeDesc ImageSpec::channelformat ( int  chan) const
inline

Return the channelformat of the given channel. This is safe even if channelformats is not filled out.

Definition at line 515 of file imageio.h.

int ImageSpec::channelindex ( string_view  name) const

Return the index of the named channel, or -1 if not found.

void ImageSpec::copy_dimensions ( const ImageSpec other)
inline

Copy the dimensions (x, y, z, width, height, depth, full*, nchannels, format) and types of the other ImageSpec. Be careful, this doesn't copy channelnames or the metadata in extra_attribs.

Definition at line 578 of file imageio.h.

std::pair<string_view, int> ImageSpec::decode_compression_metadata ( string_view  defaultcomp = "",
int  defaultqual = -1 
) const

Hunt for the "Compression" and "CompressionQuality" settings in the spec and turn them into the compression name and quality. This handles compression name/qual combos of the form "name:quality".

void ImageSpec::default_channel_names ( )

Set the channelnames to reasonable defaults ("R", "G", "B", "A"), and alpha_channel, based on the number of channels.

void ImageSpec::erase_attribute ( string_view  name,
TypeDesc  searchtype = TypeDesc::UNKNOWN,
bool  casesensitive = false 
)

Remove the specified attribute from the list of extra_attribs. If not found, do nothing. If searchtype is anything but UNKNOWN, restrict matches to only those of the given type. If casesensitive is true, the name search will be case-sensitive, otherwise the name search will be performed without regard to case (this is the default).

ParamValue* ImageSpec::find_attribute ( string_view  name,
TypeDesc  searchtype = TypeDesc::UNKNOWN,
bool  casesensitive = false 
)

Search for an attribute of the given name in the list of extra_attribs. If searchtype is anything but UNKNOWN, restrict matches to only those of the given type. If casesensitive is true, the name search will be case-sensitive, otherwise the name search will be performed without regard to case (this is the default).

const ParamValue* ImageSpec::find_attribute ( string_view  name,
TypeDesc  searchtype = TypeDesc::UNKNOWN,
bool  casesensitive = false 
) const
const ParamValue* ImageSpec::find_attribute ( string_view  name,
ParamValue tmpparam,
TypeDesc  searchtype = TypeDesc::UNKNOWN,
bool  casesensitive = false 
) const

Search for the named attribute and return a pointer to an ParamValue record, or NULL if not found. This variety of find_attribute() can retrieve items such as "width", which are part of the ImageSpec, but not in extra_attribs. The tmpparam is a temporary storage area owned by the caller, which is used as temporary buffer in cases where the information does not correspond to an actual extra_attribs (in this case, the return value will be &tmpparam).

void ImageSpec::from_xml ( const char *  xml)

Get an ImageSpec class from XML string.

void ImageSpec::get_channelformats ( std::vector< TypeDesc > &  formats) const
inline

Fill in an array of channel formats describing all channels in the image. (Note that this differs slightly from the member data channelformats, which is empty if there are not separate per-channel formats.)

Definition at line 531 of file imageio.h.

float ImageSpec::get_float_attribute ( string_view  name,
float  defaultval = 0 
) const

Simple way to get a float attribute, with default provided. Automatically will return a float even if the data is really double or half.

int ImageSpec::get_int_attribute ( string_view  name,
int  defaultval = 0 
) const

Simple way to get an integer attribute, with default provided. Automatically will return an int even if the data is really unsigned, short, or byte.

string_view ImageSpec::get_string_attribute ( string_view  name,
string_view  defaultval = string_view() 
) const

Simple way to get a string attribute, with default provided.

imagesize_t ImageSpec::image_bytes ( bool  native = false) const

Return the number of bytes for an entire image. This will return std::numeric_limits<image size_t>::max() in the event of an overflow where it's not representable in an imagesize_t. If native is false (default), assume all channels are in this->format, but if native is true, compute the size of a pixel in the "native" data format of the file (these may differ in the case of per-channel formats).

imagesize_t ImageSpec::image_pixels ( ) const

Return the number of pixels for an entire image. This will return std::numeric_limits<imagesize_t>::max() in the event of an overflow where it's not representable in an imagesize_t.

static std::string ImageSpec::metadata_val ( const ParamValue p,
bool  human = false 
)
static

For a given parameter p, format the value nicely as a string. If 'human' is true, use especially human-readable explanations (units, or decoding of values) for certain known metadata.

size_t ImageSpec::pixel_bytes ( bool  native = false) const

Return the number of bytes for each pixel (counting all channels). If native is false (default), assume all channels are in this->format, but if native is true, compute the size of a pixel in the "native" data format of the file (these may differ in the case of per-channel formats). This will return std::numeric_limits<size_t>::max() in the event of an overflow where it's not representable in a size_t.

size_t ImageSpec::pixel_bytes ( int  chbegin,
int  chend,
bool  native = false 
) const

Return the number of bytes for just the subset of channels in each pixel described by [chbegin,chend). If native is false (default), assume all channels are in this->format, but if native is true, compute the size of a pixel in the "native" data format of the file (these may differ in the case of per-channel formats). This will return std::numeric_limits<size_t>::max() in the event of an overflow where it's not representable in a size_t.

ROI ImageSpec::roi ( ) const
inline

Return pixel data window for this ImageSpec as a ROI.

Definition at line 541 of file imageio.h.

ROI ImageSpec::roi_full ( ) const
inline

Return full/display window for this ImageSpec as a ROI.

Definition at line 546 of file imageio.h.

imagesize_t ImageSpec::scanline_bytes ( bool  native = false) const

Return the number of bytes for each scanline. This will return std::numeric_limits<imagesize_t>::max() in the event of an overflow where it's not representable in an imagesize_t. If native is false (default), assume all channels are in this->format, but if native is true, compute the size of a pixel in the "native" data format of the file (these may differ in the case of per-channel formats).

std::string ImageSpec::serialize ( SerialFormat  format,
SerialVerbose  verbose = SerialDetailed 
) const

Convert ImageSpec class into a serialized string.

void ImageSpec::set_format ( TypeDesc  fmt)

Set the data format.

void ImageSpec::set_roi ( const ROI r)
inline

Set pixel data window parameters (x, y, z, width, height, depth) for this ImageSpec from an ROI. Does NOT change the channels of the spec, regardless of r.

Definition at line 554 of file imageio.h.

void ImageSpec::set_roi_full ( const ROI r)
inline

Set full/display window parameters (full_x, full_y, full_z, full_width, full_height, full_depth) for this ImageSpec from an ROI. Does NOT change the channels of the spec, regardless of r.

Definition at line 566 of file imageio.h.

bool ImageSpec::size_t_safe ( ) const
inline

Verify that on this platform, a size_t is big enough to hold the number of bytes (and pixels) in a scanline, a tile, and the whole image. If this returns false, the image is much too big to allocate and read all at once, so client apps beware and check these routines for overflows!

Definition at line 352 of file imageio.h.

imagesize_t ImageSpec::tile_bytes ( bool  native = false) const

Return the number of bytes for each a tile of the image. This will return std::numeric_limits<imagesize_t>::max() in the event of an overflow where it's not representable in an imagesize_t. If native is false (default), assume all channels are in this->format, but if native is true, compute the size of a pixel in the "native" data format of the file (these may differ in the case of per-channel formats).

imagesize_t ImageSpec::tile_pixels ( ) const

Return the number of pixels for a tile. This will return std::numeric_limits<imagesize_t>::max() in the event of an overflow where it's not representable in an imagesize_t.

std::string ImageSpec::to_xml ( ) const

Convert ImageSpec class into XML string.

bool ImageSpec::undefined ( ) const
inline

Is this ImageSpec undefined? (Designated by no channels and undefined data type – true of the uninitialized state of an ImageSpec, and presumably not for any ImageSpec that is useful or purposefully made.)

Definition at line 606 of file imageio.h.

bool ImageSpec::valid_tile_range ( int  xbegin,
int  xend,
int  ybegin,
int  yend,
int  zbegin,
int  zend 
)
inline

Helper function to verify that the given pixel range exactly covers a set of tiles. Also returns false if the spec indicates that the image isn't tiled at all.

Definition at line 502 of file imageio.h.

Member Data Documentation

int ImageSpec::alpha_channel

Index of alpha channel, or -1 if not known.

Definition at line 246 of file imageio.h.

std::vector<TypeDesc> ImageSpec::channelformats

Optional per-channel formats.

Definition at line 243 of file imageio.h.

std::vector<std::string> ImageSpec::channelnames

Names for each channel, e.g., {"R","G","B","A"}

Definition at line 244 of file imageio.h.

bool ImageSpec::deep

Contains deep data.

Definition at line 248 of file imageio.h.

int ImageSpec::depth

depth of pixel data, >1 indicates a "volume"

Definition at line 230 of file imageio.h.

ParamValueList ImageSpec::extra_attribs

Additional attributes.

The above contains all the information that is likely needed for every image file, and common to all formats. Rather than bloat this structure, customize it for new formats, or break back compatibility as we think of new things, we provide extra_attribs as a holder for any other properties of the image. The public functions attribute and find_attribute may be used to access these data. Note, however, that the names and semantics of such extra attributes are plugin-dependent and are not enforced by the imageio library itself.

Definition at line 259 of file imageio.h.

TypeDesc ImageSpec::format

data format of the channels

Definition at line 242 of file imageio.h.

int ImageSpec::full_depth

depth of the full (display) window

Definition at line 236 of file imageio.h.

int ImageSpec::full_height

height of the full (display) window

Definition at line 235 of file imageio.h.

int ImageSpec::full_width

width of the full (display) window

Definition at line 234 of file imageio.h.

int ImageSpec::full_x

origin of the full (display) window

Definition at line 231 of file imageio.h.

int ImageSpec::full_y

origin of the full (display) window

Definition at line 232 of file imageio.h.

int ImageSpec::full_z

origin of the full (display) window

Definition at line 233 of file imageio.h.

int ImageSpec::height

height of the pixel data window

Definition at line 229 of file imageio.h.

int ImageSpec::nchannels

number of image channels, e.g., 4 for RGBA

Definition at line 241 of file imageio.h.

int ImageSpec::tile_depth

tile depth (0 for a non-tiled image, 1 for a non-volume image)

Definition at line 239 of file imageio.h.

int ImageSpec::tile_height

tile height (0 for a non-tiled image)

Definition at line 238 of file imageio.h.

int ImageSpec::tile_width

tile width (0 for a non-tiled image)

Definition at line 237 of file imageio.h.

int ImageSpec::width

width of the pixel data window

Definition at line 228 of file imageio.h.

int ImageSpec::x

Definition at line 227 of file imageio.h.

int ImageSpec::y

Definition at line 227 of file imageio.h.

int ImageSpec::z

origin (upper left corner) of pixel data

Definition at line 227 of file imageio.h.

int ImageSpec::z_channel

Index of depth channel, or -1 if not known.

Definition at line 247 of file imageio.h.


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