OpenImageIO
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Pages
Public Member Functions | Static Public Member Functions | Public Attributes | List of all members
ImageSpec Class Reference

#include <imageio.h>

Public Member Functions

 ImageSpec (TypeDesc format=TypeDesc::UNKNOWN)
 
 ImageSpec (int xres, int yres, int nchans, TypeDesc fmt=TypeDesc::UINT8)
 
void set_format (TypeDesc fmt)
 
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 (const std::string &name, TypeDesc type, const void *value)
 
void attribute (const std::string &name, TypeDesc type, const std::string &value)
 
void attribute (const std::string &name, unsigned int value)
 
void attribute (const std::string &name, int value)
 
void attribute (const std::string &name, float value)
 
void attribute (const std::string &name, const char *value)
 
void attribute (const std::string &name, const std::string &value)
 
void erase_attribute (const std::string &name, TypeDesc searchtype=TypeDesc::UNKNOWN, bool casesensitive=false)
 
ImageIOParameter * find_attribute (const std::string &name, TypeDesc searchtype=TypeDesc::UNKNOWN, bool casesensitive=false)
 
const ImageIOParameter * find_attribute (const std::string &name, TypeDesc searchtype=TypeDesc::UNKNOWN, bool casesensitive=false) const
 
int get_int_attribute (const std::string &name, int defaultval=0) const
 
float get_float_attribute (const std::string &name, float defaultval=0) const
 
std::string get_string_attribute (const std::string &name, const std::string &defaultval=std::string()) const
 
std::string metadata_val (const ImageIOParameter &p, bool human=false) const
 
std::string to_xml () const
 
void from_xml (const char *xml)
 
bool valid_tile_range (int xbegin, int xend, int ybegin, int yend, int zbegin, int zend)
 
TypeDesc channelformat (int chan) const
 Return teh channelformat of the given channel.
 
void get_channelformats (std::vector< TypeDesc > &formats) const
 

Static Public Member Functions

static TypeDesc format_from_quantize (int quant_black, int quant_white, int quant_min, int quant_max)
 
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)
 

Public Attributes

int x
 
int y
 
int z
 origin (upper left corner) of pixel data
 
int width
 width of the pixel data window
 
int height
 height of the pixel data window
 
int depth
 depth of pixel data, >1 indicates a "volume"
 
int full_x
 origin of the full (display) window
 
int full_y
 origin of the full (display) window
 
int full_z
 origin of the full (display) window
 
int full_width
 width of the full (display) window
 
int full_height
 height of the full (display) window
 
int full_depth
 depth of the full (display) window
 
int tile_width
 tile width (0 for a non-tiled image)
 
int tile_height
 tile height (0 for a non-tiled image)
 
int tile_depth
 
int nchannels
 number of image channels, e.g., 4 for RGBA
 
TypeDesc format
 data format of the channels
 
std::vector< TypeDesc > channelformats
 Optional per-channel formats.
 
std::vector< std::string > channelnames
 
int alpha_channel
 Index of alpha channel, or -1 if not known.
 
int z_channel
 Index of depth channel, or -1 if not known.
 
bool deep
 Contains deep data.
 
int quant_black
 quantization of black (0.0) level
 
int quant_white
 quantization of white (1.0) level
 
int quant_min
 quantization minimum clamp value
 
int quant_max
 quantization maximum clamp value
 
ImageIOParameterList extra_attribs
 Additional attributes.
 

Detailed Description

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

Constructor & Destructor Documentation

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

Constructor: given just the data format, set the default quantize and set all other channels 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.

Member Function Documentation

void ImageSpec::attribute ( const std::string &  name,
TypeDesc  type,
const void *  value 
)

Add an optional attribute to the extra attribute list

void ImageSpec::attribute ( const std::string &  name,
TypeDesc  type,
const std::string &  value 
)

Add an optional attribute to the extra attribute list.

void ImageSpec::attribute ( const std::string &  name,
unsigned int  value 
)
inline

Add an unsigned int attribute

void ImageSpec::attribute ( const std::string &  name,
int  value 
)
inline

Add an int attribute

void ImageSpec::attribute ( const std::string &  name,
float  value 
)
inline

Add a float attribute

void ImageSpec::attribute ( const std::string &  name,
const char *  value 
)
inline

Add a string attribute

void ImageSpec::attribute ( const std::string &  name,
const std::string &  value 
)
inline

Add a string attribute

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.

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.

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.

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.

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.

TypeDesc ImageSpec::channelformat ( int  chan) const
inline

Return teh channelformat of the given channel.

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 ( const std::string &  name,
TypeDesc  searchtype = TypeDesc::UNKNOWN,
bool  casesensitive = false 
)

Remove the specified attribute from the list of extra attributes. If not found, do nothing.

ImageIOParameter* ImageSpec::find_attribute ( const std::string &  name,
TypeDesc  searchtype = TypeDesc::UNKNOWN,
bool  casesensitive = false 
)

Search for a attribute of the given name in the list of extra attributes.

static TypeDesc ImageSpec::format_from_quantize ( int  quant_black,
int  quant_white,
int  quant_min,
int  quant_max 
)
static

Given quantization parameters, deduce a TypeDesc that can be used without unacceptable loss of significant bits.

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.)

float ImageSpec::get_float_attribute ( const std::string &  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 ( const std::string &  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.

std::string ImageSpec::get_string_attribute ( const std::string &  name,
const std::string &  defaultval = std::string() 
) 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.

std::string ImageSpec::metadata_val ( const ImageIOParameter &  p,
bool  human = false 
) const

For a given parameter (in this ImageSpec's extra_attribs), 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.

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).

void ImageSpec::set_format ( TypeDesc  fmt)

Set the data format, and as a side effect set quantize to good defaults for that format

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!

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::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.

Member Data Documentation

int ImageSpec::alpha_channel

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

std::vector<TypeDesc> ImageSpec::channelformats

Optional per-channel formats.

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

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

bool ImageSpec::deep

Contains deep data.

int ImageSpec::depth

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

ImageIOParameterList 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.

TypeDesc ImageSpec::format

data format of the channels

int ImageSpec::full_depth

depth of the full (display) window

int ImageSpec::full_height

height of the full (display) window

int ImageSpec::full_width

width of the full (display) window

int ImageSpec::full_x

origin of the full (display) window

int ImageSpec::full_y

origin of the full (display) window

int ImageSpec::full_z

origin of the full (display) window

int ImageSpec::height

height of the pixel data window

int ImageSpec::nchannels

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

int ImageSpec::quant_black

quantization of black (0.0) level

int ImageSpec::quant_max

quantization maximum clamp value

int ImageSpec::quant_min

quantization minimum clamp value

int ImageSpec::quant_white

quantization of white (1.0) level

int ImageSpec::tile_depth

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

int ImageSpec::tile_height

tile height (0 for a non-tiled image)

int ImageSpec::tile_width

tile width (0 for a non-tiled image)

int ImageSpec::width

width of the pixel data window

int ImageSpec::z

origin (upper left corner) of pixel data

int ImageSpec::z_channel

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


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