|
HDK
|
#include <imageio.h>
Public Types | |
| enum | SerialFormat { SerialText, SerialXML } |
| enum | SerialVerbose { SerialBrief, SerialDetailed, SerialDetailedHuman } |
Public Member Functions | |
| ImageSpec (TypeDesc format=TypeDesc::UNKNOWN) noexcept | |
| ImageSpec (string_view format) noexcept | |
| ImageSpec (int xres, int yres, int nchans, TypeDesc fmt=TypeUInt8) noexcept | |
| ImageSpec (int xres, int yres, int nchans, string_view fmt) noexcept | |
| ImageSpec (const ROI &roi, TypeDesc fmt=TypeUInt8) noexcept | |
| ImageSpec (const ROI &roi, string_view fmt) noexcept | |
| void | set_format (TypeDesc fmt) noexcept |
| void | set_format (string_view fmt) noexcept |
| void | default_channel_names () noexcept |
| size_t | channel_bytes () const noexcept |
| size_t | channel_bytes (int chan, bool native=false) const noexcept |
| size_t | pixel_bytes (bool native=false) const noexcept |
| size_t | pixel_bytes (int chbegin, int chend, bool native=false) const noexcept |
| imagesize_t | scanline_bytes (bool native=false) const noexcept |
| imagesize_t | tile_pixels () const noexcept |
| imagesize_t | tile_bytes (bool native=false) const noexcept |
| imagesize_t | image_pixels () const noexcept |
| imagesize_t | image_bytes (bool native=false) const noexcept |
| bool | size_t_safe () const noexcept |
| void | attribute (string_view name, TypeDesc type, const void *value) |
| void | attribute (string_view name, unsigned int value) |
Add an unsigned int attribute to extra_attribs. More... | |
| void | attribute (string_view name, int value) |
Add an int attribute to extra_attribs. More... | |
| void | attribute (string_view name, float value) |
Add a float attribute to extra_attribs. More... | |
| void | attribute (string_view name, string_view value) |
Add a string attribute to extra_attribs. More... | |
| void | attribute (string_view name, TypeDesc type, string_view value) |
| void | erase_attribute (string_view name, TypeDesc searchtype=TypeDesc::UNKNOWN, bool casesensitive=false) |
| ParamValue * | find_attribute (string_view name, TypeDesc searchtype=TypeDesc::UNKNOWN, bool casesensitive=false) |
| const ParamValue * | find_attribute (string_view name, TypeDesc searchtype=TypeDesc::UNKNOWN, bool casesensitive=false) const |
| const ParamValue * | find_attribute (string_view name, ParamValue &tmpparam, TypeDesc searchtype=TypeDesc::UNKNOWN, bool casesensitive=false) const |
| TypeDesc | getattributetype (string_view name, bool casesensitive=false) const |
| bool | getattribute (string_view name, TypeDesc type, void *value, 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 |
| std::string | to_xml () const |
Converts the contents of the ImageSpec as an XML string. More... | |
| void | from_xml (const char *xml) |
Populates the fields of the ImageSpec based on the XML passed in. More... | |
| std::pair< string_view, int > | decode_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) noexcept |
| 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 |
| ROI | roi () const noexcept |
| Return pixel data window for this ImageSpec expressed as a ROI. More... | |
| ROI | roi_full () const noexcept |
| Return full/display window for this ImageSpec expressed as a ROI. More... | |
| void | set_roi (const ROI &r) noexcept |
| void | set_roi_full (const ROI &r) noexcept |
| void | copy_dimensions (const ImageSpec &other) |
| bool | undefined () const noexcept |
| AttrDelegate< ImageSpec > | operator[] (string_view name) |
| AttrDelegate< const ImageSpec > | operator[] (string_view name) 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) noexcept |
| static void | auto_stride (stride_t &xstride, stride_t &ystride, stride_t &zstride, TypeDesc format, int nchannels, int width, int height) noexcept |
| static void | auto_stride (stride_t &xstride, TypeDesc format, int nchannels) noexcept |
| static std::string | metadata_val (const ParamValue &p, bool human=false) |
Public Attributes | |
ImageSpec data members | |
The Here are the hard-coded data fields: | |
| int | x |
| origin (upper left corner) of pixel data More... | |
| int | y |
| origin (upper left corner) of pixel data More... | |
| 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 |
| std::vector< TypeDesc > | channelformats |
| std::vector< std::string > | channelnames |
| int | alpha_channel |
| int | z_channel |
| bool | deep |
| ParamValueList | extra_attribs |
ImageSpec describes the data format of an image – dimensions, layout, number and meanings of image channels.
The width, height, depth are the size of the data of this image, i.e., the number of pixels in each dimension. A depth greater than 1 indicates a 3D "volumetric" image. The x, y, z fields indicate the origin of the pixel data of the image. These default to (0,0,0), but setting them differently may indicate that this image is offset from the usual origin. Therefore the pixel data are defined over pixel coordinates [x ... x+width-1] horizontally, [y ... y+height-1] vertically, and [z ... z+depth-1] in depth.
The analogous full_width, full_height, full_depth and full_x, full_y, full_z fields define a "full" or "display" image window over the region [full_x ... full_x+full_width-1] horizontally, [full_y ... full_y+full_height-1] vertically, and [full_z... full_z+full_depth-1] in depth.
Having the full display window different from the pixel data window can be helpful in cases where you want to indicate that your image is a crop window of a larger image (if the pixel data window is a subset of the full display window), or that the pixels include overscan (if the pixel data is a superset of the full display window), or may simply indicate how different non-overlapping images piece together.
For tiled images, tile_width, tile_height, and tile_depth specify that the image is stored in a file organized into rectangular tiles of these dimensions. The default of 0 value for these fields indicates that the image is stored in scanline order, rather than as tiles.
|
noexcept |
Constructor: given just the data format, set all other fields to something reasonable.
|
inlinenoexcept |
Constructs an ImageSpec with the given x and y resolution, number of channels, and pixel data format.
All other fields are set to the obvious defaults – the image is an ordinary 2D image (not a volume), the image is not offset or a crop of a bigger image, the image is scanline-oriented (not tiled), channel names are "R", "G", "B"' and "A" (up to and including 4 channels, beyond that they are named "channel *n*"), the fourth channel (if it exists) is assumed to be alpha.
|
inlinenoexcept |
|
inlineexplicitnoexcept |
| void ImageSpec::attribute | ( | string_view | name, |
| TypeDesc | type, | ||
| const void * | value | ||
| ) |
Add a metadata attribute to extra_attribs, with the given name and data type. The value pointer specifies the address of the data to be copied.
|
inline |
|
inline |
|
inline |
|
inline |
| void ImageSpec::attribute | ( | string_view | name, |
| TypeDesc | type, | ||
| string_view | value | ||
| ) |
Parse a string containing a textual representation of a value of the given type, and add that as an attribute to extra_attribs. Example:
spec.attribute ("temperature", TypeString, "-273.15");
|
inlinenoexcept |
|
noexcept |
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.
|
inline |
| int ImageSpec::channelindex | ( | string_view | name | ) | const |
Return the index of the channel with the given name, or -1 if no such channel is present in channelnames.
Copy from other the image dimensions (x, y, z, width, height, depth, full*, nchannels, format) and data types. It does not copy arbitrary named metadata or channel names (thus, for an ImageSpec with lots of metadata, it is much less expensive than copying the whole thing with operator=()).
| 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".
|
noexcept |
Sets the channelnames to reasonable defaults for the number of channels. Specifically, channel names are set to "R", "G", "B," and "A" (up to and including 4 channels, beyond that they are named "channel*n*".
| void ImageSpec::erase_attribute | ( | string_view | name, |
| TypeDesc | searchtype = TypeDesc::UNKNOWN, |
||
| bool | casesensitive = false |
||
| ) |
Searches extra_attribs for any attributes matching name (as a regular expression), removing them entirely from extra_attribs. If searchtype is anything other than TypeDesc::UNKNOWN, matches will be restricted only to attributes with the given type. The name comparison will be case-sensitive if casesensitive is true, otherwise in a case-insensitive manner.
| ParamValue* ImageSpec::find_attribute | ( | string_view | name, |
| TypeDesc | searchtype = TypeDesc::UNKNOWN, |
||
| bool | casesensitive = false |
||
| ) |
Searches extra_attribs for an attribute matching name, returning a pointer to the attribute record, or NULL if there was no match. If searchtype is anything other than TypeDesc::UNKNOWN, matches will be restricted only to attributes with the given type. The name comparison will be exact if casesensitive is true, otherwise in a case-insensitive manner if caseinsensitive is false.
| 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 the pointer to its ParamValue record, or NULL if not found. This variety of find_attribute(} can retrieve items such as "width", which are data members of the ImageSpec, but not in extra_attribs. The tmpparam is a 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). The extra names it understands are:
"x" "y" "z" "width" "height" "depth" "full_x" "full_y" "full_z" "full_width" "full_height" "full_depth"
Returns the ImageSpec fields of those names (despite the fact that they are technically not arbitrary named attributes in extra_attribs). All are of type int.
"datawindow"
Without a type, or if requested explicitly as an int[4], returns the OpenEXR-like pixel data min and max coordinates, as a 4-element integer array: { x, y, x+width-1, y+height-1 }. If instead you specifically request as an int[6], it will return the volumetric data window, { x, y, z, x+width-1, y+height-1, z+depth-1 }.
"displaywindow"
Without a type, or if requested explicitly as an int[4], returns the OpenEXR-like pixel display min and max coordinates, as a 4-element integer array: { full_x, full_y, full_x+full_width-1, full_y+full_height-1 }. If instead you specifically request as an int[6], it will return the volumetric display window, { full_x, full_y, full_z, full_x+full_width-1, full_y+full_height-1, full_z+full_depth-1 }.
EXAMPLES
ImageSpec spec; // has the info
Imath::Box2i dw; // we want the displaywindow here
ParamValue tmp; // so we can retrieve pseudo-values
TypeDesc int4("int[4]"); // Equivalent: TypeDesc int4(TypeDesc::INT,4);
const ParamValue* p = spec.find_attribute ("displaywindow", int4);
if (p)
dw = Imath::Box2i(p->get<int>(0), p->get<int>(1),
p->get<int>(2), p->get<int>(3));
p = spec.find_attribute("temperature", TypeFloat);
if (p)
float temperature = p->get<float>();
| void ImageSpec::from_xml | ( | const char * | xml | ) |
Populates the fields of the ImageSpec based on the XML passed in.
| float ImageSpec::get_float_attribute | ( | string_view | name, |
| float | defaultval = 0 |
||
| ) | const |
Retrieve the named metadata attribute and return its value as a float. Any integer or floating point type will convert to float in the obvious way (like a C cast), and so will string metadata if its contents consist of of the text representation of one floating point value. If no such metadata exists, or are of a type that cannot be converted, the defaultval will be returned.
| int ImageSpec::get_int_attribute | ( | string_view | name, |
| int | defaultval = 0 |
||
| ) | const |
Retrieve the named metadata attribute and return its value as an int. Any integer type will convert to int by truncation or expansion, string data will parsed into an int if its contents consist of of the text representation of one integer. Floating point data will not succeed in converting to an int. If no such metadata exists, or are of a type that cannot be converted, the defaultval will be returned.
| string_view ImageSpec::get_string_attribute | ( | string_view | name, |
| string_view | defaultval = string_view() |
||
| ) | const |
Retrieve any metadata attribute, converted to a string. If no such metadata exists, the defaultval will be returned.
| bool ImageSpec::getattribute | ( | string_view | name, |
| TypeDesc | type, | ||
| void * | value, | ||
| bool | casesensitive = false |
||
| ) | const |
If the ImageSpec contains the named attribute and its type matches type, copy the attribute value into the memory pointed to by val (it is up to the caller to ensure there is enough space) and return true. If no such attribute is found, or if it doesn't match the type, return false and do not modify val.
EXAMPLES:
ImageSpec spec;
...
// Retrieving an integer attribute:
int orientation = 0;
spec.getattribute ("orientation", TypeInt, &orientation);
// Retrieving a string attribute with a char*:
const char* compression = nullptr;
spec.getattribute ("compression", TypeString, &compression);
// Alternately, retrieving a string with a ustring:
ustring compression;
spec.getattribute ("compression", TypeString, &compression);
Note that when passing a string, you need to pass a pointer to the char*, not a pointer to the first character. Also, the char* will end up pointing to characters owned by the ImageSpec; the caller does not need to ever free the memory that contains the characters.
This was added in version 2.1.
| TypeDesc ImageSpec::getattributetype | ( | string_view | name, |
| bool | casesensitive = false |
||
| ) | const |
If the named attribute can be found in the ImageSpec, return its data type. If no such attribute exists, return TypeUnknown.
This was added in version 2.1.
|
noexcept |
Returns the number of bytes comprising an entire image of these dimensions, i.e., pixel_bytes(native) * width * height * depth 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).
|
noexcept |
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 |
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.
|
inline |
Array indexing by string will create an AttrDelegate that enables a convenient shorthand for adding and retrieving values from the spec:
Assigning to the delegate adds a metadata attribute:
ImageSpec spec; spec["foo"] = 42; // int spec["pi"] = float(M_PI); // float spec["oiio:ColorSpace"] = "sRGB"; // string spec["cameratoworld"] = Imath::Matrix44(...); // matrix
Be very careful, the attribute's type will be implied by the C++ type of what you assign.
std::string colorspace = spec["oiio:ColorSpace"]; int dither = spec["oiio:dither"].get<int>();
This was added in version 2.1.
|
inline |
|
noexcept |
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).
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).
|
inlinenoexcept |
|
inlinenoexcept |
|
noexcept |
Returns the number of bytes comprising each scanline, i.e., pixel_bytes(native) * width 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::serialize | ( | SerialFormat | format, |
| SerialVerbose | verbose = SerialDetailed |
||
| ) | const |
Returns, as a string, a serialized version of the ImageSpec. The format may be either ImageSpec::SerialText or ImageSpec::SerialXML. The verbose argument may be one of: ImageSpec::SerialBrief (just resolution and other vital statistics, one line for SerialText, ImageSpec::SerialDetailed (contains all metadata in original form), or ImageSpec::SerialDetailedHuman (contains all metadata, in many cases with human-readable explanation).
Set the data format, and clear any per-channel format information in channelformats.
|
inlinenoexcept |
|
inlinenoexcept |
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!
|
noexcept |
Returns the number of bytes comprising an image tile, i.e., pixel_bytes(native) * tile_width * tile_height * tile_depth 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).
|
noexcept |
Return the number of pixels comprising a tile (or 0 if it is not a tiled 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::to_xml | ( | ) | const |
Converts the contents of the ImageSpec as an XML string.
|
inlinenoexcept |
| int ImageSpec::alpha_channel |
| std::vector<TypeDesc> ImageSpec::channelformats |
Optional per-channel data formats. If all channels of the image have the same data format, that will be described by format and channelformats will be empty (zero length). If there are different data formats for each channel, they will be described in the channelformats vector, and the format field will indicate a single default data format for applications that don't wish to support per-channel formats (usually this will be the format of the channel that has the most precision).
| std::vector<std::string> ImageSpec::channelnames |
| bool ImageSpec::deep |
| int ImageSpec::depth |
| ParamValueList ImageSpec::extra_attribs |
A list of arbitrarily-named and arbitrarily-typed additional attributes of the image, for any metadata not described by the hard-coded fields described above. This list may be manipulated with the attribute() and find_attribute() methods.
| TypeDesc ImageSpec::format |
Data format of the channels. Describes the native format of the pixel data values themselves, as a TypeDesc. Typical values would be TypeDesc::UINT8 for 8-bit unsigned values, TypeDesc::FLOAT for 32-bit floating-point values, etc.
| int ImageSpec::full_depth |
| int ImageSpec::full_height |
| int ImageSpec::full_width |
| int ImageSpec::nchannels |
| int ImageSpec::tile_depth |
| int ImageSpec::tile_height |
| int ImageSpec::tile_width |
| int ImageSpec::z_channel |
1.8.6