The UMS image reader is an Ultimedia Services Version 2 feature and does not apply to Ultimedia Services Version 1.2.1.
The UMS image reader is one component of the UMS support for image display (UID). The 2.1.5 release of UID supports JPEG, GIF, Photo CD, and a subset of TIFF images. An image reader allows applications to read and decode (when applicable) a range of image files in a consistent manner. Image reader support includes the ability to read subimages as well as entire images, decode image data into a variety of data formats, control color maps used in decoding, and apply transformations to the image data.
The UID encompasses a number of image reader classes. The base image reader class is the UMSImageReader. This base class contains the image reader methods that are common to all derived image reader classes. In addition to the UMSImageReader, a number of format-specific image reader classes are also available; they include the UMSJPEGImageReader and UMSPCDImageReader, UMSPCDIPImageReader, and UMSPCDOImageReader. These derived classes offer functionality beyond that of the UMSImageReader, but their methods are not shared among all the derived classes. Consequently, these classes should be used only when there is a requirement for the extended functionality that they offer. If portability of code across different image formats is important, then applications should use only the UMSImageReader class.
To learn more about the UMSImageReader object, see:
For introductory information, see Formatted File Access Objects.
This section lists the methods supported by all image reader objects.
There are three types of method parameters: in, out, and inout. Each type specifies how memory is allocated and deallocated, as follows:
| in | Caller allocates and deallocates. |
| out | Method allocates and caller deallocates if parameter is an unbounded string or unbounded sequence. |
| inout | Caller allocates and deallocates. |
For all three parameter types, the caller usually allocates the parameter that is passed in. The only time the method allocates storage is if the parameter is of type out, and then only if the out parameter is an unbounded sequence or string. For a sequence, only the buffer pointed to by the sequence is deallocated, and not the sequence structure itself. For an out parameter of a simple type such a long or a structure (That is, for a parameter with a fixed length), the caller can pass in the address of an automatic variable; no deallocation is necessary. When the caller passes in the address of a sequence (an automatic variable is acceptable) for an out parameter that is an unbounded sequence, the method allocates a buffer and sets the sequence to point to it. In this case, the caller is required to deallocate that buffer when finished with it.
A number of structure definitions are used in the image reader methods String formats are contained in UMSStrings.h, and image reader definitions are contained in UMSTypes.h. For detailed information about X Windows data structures, refer to the appropriate X Windows header files.
The UMS image reader metaclass supports two methods: make_by_pathname and make_by_alias. The make_by_pathname method is invoked when the caller does not know what kind of image file is to be viewed, whereas the make_by_alias method is invoked when the caller already knows the specific image type. In both cases, UMSImageReaderNewClass is called to create the class. Subsequently, the make_by_pathname or make_by_alias method of this class is invoked to create the desired image reader object. See UMSImageReaderMClass class for the method descriptions.
typedef struct {
unsigned long width;
unsigned long height;
} UMSImageSize;
typedef struct {
unsigned short top;
unsigned short left;
unsigned short bottom;
unsigned short right;
} UMSImageRect;
typedef struct {
short red; /* intensity of red color balance */
short green; /* intensity of green color balance */
short blue; /* intensity of blue color balance */
short saturation; /* level of saturation */
short brightness; /* level of brightness */
} UMSImageColorProperties;
typedef struct {
short vertical; /* vertical coordinate, origin at left top */
short horizontal; /* horizontal coordinate, origin at left top */
} UMSImagePoint;
typedef enum {
ROTATE_0,
ROTATE_90,
ROTATE_180,
ROTATE_270,
MIRROR_0,
MIRROR_90,
MIRROR_180,
MIRROR_270
} UMSImageTransform;
typedef enum {
SOURCE_COORDINATE_SYSTEM,
DESTINATION_COORDINATE_SYSTEM
} UMSImageCoordinateSystem;
typedef enum {
NO_DITHER,
PCD_DITHER,
IBM_DITHER
} UMSImageDitherTypes;
In programming with the UMS image reader, one fundamental question must be answered regarding the declaration and initialization of image reader objects. Do you want a generic or a specific image reader? A generic image reader is based on the base image reader class, and hence can be used with a variety of image file types, such as JPEG and Photo CD, in a consistent manner (for example, there are no interface changes between image file types). In contrast, a specific image reader can be used only with one type of image file, such as JPEG, Photo CD Image Pacs, or Photo CD overview files, but a potentially larger and more powerful collection of methods is available to the image reader object.
To declare a generic image reader, the following header and variable declarations must be made:
#include <UMSImageReader.h> /* use the base image reader declaration */
UMSImageReaderMClass IR_Class; /* declare an image reader meta class */
UMSImageReader IR; /* declare a base class image reader object */
Given these declarations, the metaclass and image reader objects are instantiated as follows. (Note that error checking is not included in the code fragments, and that not all parameters have been included.)
IR_Class = UMSImageReaderNewClass(UMSImageReader_MajorVersion, UMSImageReader_MinorVersion);
IR = UMSImageReaderMClass_make_by_pathname(IR_Class, ev, file_path_name, ... );
Image reader objects declared and instantiated as indicated above can be used with JPEG, Photo CD Image Pac, and Photo CD overview files. However, none of the Photo CD Image Pac specific methods can be invoked by the image reader object. (There are no JPEG specific image reader methods.) Note that the open method is not invoked. (make_by_pathname invokes open as part of its processing.)
If the Photo CD Image Pac specific methods are required by an application, then the image reader object should be declared and instantiated as follows for an Image Pac reader.
#include <UMSPCDIPImageReader.h> UMSPCDIPImageReader IR;
IR = UMSPCDIPImageReaderNew( );
returnCode = UMSPCDIPImageReader_open( IR, ev, InFile );
Once an image reader object has been instantiated, the application should initialize the object as desired before reading images. The image reader resets its state to default values each time open is invoked. If the default values are not acceptable, the application must invoke the appropriate methods to change the reader's state. (This could include loading a color map, setting the current image, or changing the transform.) In the case of Photo CD overview files, each image in the overview has its own state; hence, changing the current image also changes the current state. The current image's state is always applied whenever read_image is invoked. Consequently, once the state for each image has been set as desired, there is no need for the application to reinvoke the methods that set state for the current image when changing the current image.
The following methods are common to all image reader classes. Note that all base methods are defined as pure virtual functions; the base methods do not contain any implementation. The state implied by the following methods (color map, color map attributes, format, transform, and size) is on a per-image basis. This means that each image in an image file has its own state; when the current image in a file is changed, the image state is also changed appropriately.
pathname is a string that specifies an image file. The method opens the file, extracts information about the image file, and initializes the internal state. It fails if the image format is not supported.
| in string pathname | pathname is a string that specifies an image file. This must be a path that can be opened. |
The method returns the number of different images in an image file.
| out unsigned long count | count is the number of different images in the current image file. |
The method sets the image number specified by selection as the current image. The pixmap data associated with this image is copied into system memory when read_image or another image loading method is invoked. The first image is image number 0. If, for example, get_image_count returns 5, the image numbers of the five images are 0-4. The default current image is the first image in a file, so if an image file contains only one image, the caller does not need to invoke set_image before loading the image.
| in unsigned long selection | The image number specified by selection is the new current image. |
The method returns the image number of the current image. The first image is number 0, the second image number 1, and so on.
| out unsigned long selection | The argument returns the image number of the current image. |
This method allocates and returns in list._buffer a pointer to the first pointer in an array of string pointers, where a string in C and C++ is defined as a char *; the caller is responsible for deallocating the storage (That is, the caller must deallocate each string and the array of string pointers.) Each string specifies one image data (That is, pixmap) format that the method read_image supports for the current image. The number of formats contained in the sequence is specified in both its _maximum and _length fields.
The currently supported formats are:
IF_PCDYCC24 refers to the Kodak Photo CD YCC 24-bit image data. IF_RGBPacked24 refers to 24 bits per pixel image data that is in "RGBR" format (in 32 bits). IF_RGB24Plane refers to three planes of color (RRR GGG BBB), where the number of red, green, or blue components is the number of pixels in the image. IF_RGB24 and IF_PadRGB24 both refer to 24 bits per pixel image data that is in "PadRGB" format (in 32 bits). IF_RGB8Dither is a 8-bit dithered image. IF_Grayscale8 refers to 8-bit grayscale image data. The default format is IF_RGB8Dither and PCD_DITHER is the default dither state. The valid dither states are NO_DITHER and PCD_DITHER.
The currently supported formats are:
The default format is IF_RGB8Dither, and IBM_DITHER is the default state. No other dithering state is valid.
The currently supported formats are:
The default format is IF_RGB8Dither and NO_DITHER is the default state. No other dithering state is valid.
The method specifies the color format to be used when reading image data. inFormat is the specified format.
| in string inFormat | inFormat is a string that specifies the color format to be used when reading image data. |
The method gets the currently specified color format for image data. The method allocates format and the caller deallocates it.
| out string format | format is a string that contains the currently selected color format for reading image data. |
The method specifies the number of entries in the color map and the offset of these entries. These are relative to a 256 entry color map with entries from 0 to 255. If the requested color map size or base index is not supported, the respective output parameter is changed to an appropriate value. If such adjustment is required, the size is adjusted downward when possible. The color map occupies the highest color map entries.
The JPEG decoder supports only four colormap sizes with the following number of sizes: 256, 224, 128, and 64. These are the only sizes that is accepted by set_colormap_attributes.
The only valid colormap attributes for grayscale Photo CD images are a colormap of 256 entries with a colormap index of 0 (Zero).
The method gets the current color map size and the base index value used when dithering 8-bit image data.
| out unsigned long colormapBaseIndex | The index of the first color map entry in the current color map. |
| out unsigned long colormapSize | The number of entries in the current color map. |
When the original source of the image is a colormapped form, (such as TIFF and GIF), this method gets the size of the source colormap (but never more than 256). When the original source of the image is not in a color indexed form, this value is 256, since that is the largest colormap 8 bit indexing can support.
| out unsigned long best_size | Set to the size of colormap that will provide the best image quality available for the source image. |
The method sets a color map using the current settings for color map base index and color map size. The color map is specified as a sequence of octets, with 4 bytes of data for each entry: pad, red, green, and blue. inColormap is the desired color map; outColormap, which is allocated by the method, is the actual color map. The caller must deallocate outColormap. If the image contains a color map, it is used as the default color map; otherwise, UMS defines a default color map for the image. The default color map contains 128 colors; it is installed when open is called successfully, and removed when close is called successfully. Note that the caller never needs to look at outColormap unless the return code is set to ValueChanged, although the current color map is returned whether the map was changed or accepted as specified. outColormap._length is set to the number of bytes in the color map whenever the return code is UMSImageReader_Success or UMSImageReader_ValueChanged.
Color map rules: If a file contains a color map and the color map can be set, the color map in the file is the default color map used by the image reader, and it is returned by get_colormap. A different color map can be specified by set_colormap, and get_colormap then returns that color map. If a file contains a color map but the color map cannot be set, the color map in the file is the default color map used by the image reader, and it is returned by get_colormap. In this case, when an attempt to set another color map is made, set_colormap returns the value Value Changed and the color map is not replaced; get_colormap returns the color map in the file. If a file does not contain a color map but a map can be set, UMS creates a default color map and get_colormap returns it. A different color map can be specified by set_colormap, and get_colormap returns that color map.
The method converts the color map data into an array of XColor structures and passes the array to the toolkit software.
Callers cannot set the color map used by the JPEG decoder; it creates its own color maps. Consequently, this method always ignores the color map specified by the caller, returns UMSImageReader_ValueChanged, and copies the decoder's color map into outColormap. For JPEG color maps, UMS currently supports 256, 224, 128, and 64 entry color maps; other color map sizes are not supported.
The method gets the current color map using the current settings for color map base index and color map size. The color map is returned as a sequence of octets. Each color map entry is 4 bytes long, encoded as: pad, red, green, and blue. The color map is allocated by the method and deallocated by the caller. colormap._length is set to the number of bytes in the color map.
| out sequence<octet> colormap | The color map that is currently installed and the number of bytes in it. |
The JPEG decoder's color map is returned by this method.
The method gets the transformation required to read the currently selected image right-side-up. This value can be used with set_transform to read the image right-side-up. Note that this value is not affected by the current transform setting. get_rightsideup_transform returns ROTATE_0 for any image file format that does not specify a right-side-up transform.
| out UMSImageTransform rightsideup | The argument returns the transformation required to display the current image right-side-up. |
The method returns an array of UMSImageTransform enumerations that specify which transforms are supported on an image reader. ROTATE_0 is always supported. Support for other transforms depends on the image reader type. The method allocates the array, and the caller must deallocate it. (It is an array of unsigned longs.)
| out sequence<UMSImageTransform> transforms | The argument returns an array of UMSImageTransforms of the transforms supported by the image reader and the number of elements in the array. |
The method specifies the orientation with which the current image is read. Calls to this method affect read_image and get_display_size. Once set_transform has been called, get_display_size should be called to determine the display width and height because the orientation of the display may have changed. Note that the selected transform is relative only to the image orientation in the image file; it is not relative to the currently selected transform.
| in UMSImageTransform inTransform | inTransform specifies the transformation that is applied to the next read of the current image. |
This method gets the currently specified orientation to be applied when an image is read.
| out UMSImageTransform transform | transform returns the current transformation applied to the current image when it is read. |
The method returns the number of different sizes (Specifically, image widths and heights) available for the current image in sizes._length. It also allocates and initializes an array of UMSImageSize structures that contains sizes._length number of entries. The caller must deallocate the array. Each entry in the array specifies one image size. Whenever set_image_size is to be called, get_image_sizes should be called first to ensure that the correct image sizes are known to the caller. If a transform has been applied to an image, any resulting change in display width and height is reflected in subsequent calls to get_display_size (but not get_image_sizes).
| out sequence<UMSImageSize> sizes | sizes returns a pointer to an array of UMSImageSize elements of the image sizes available for the current image and the number of elements in the array. |
The method sets the image size (Specifically, width and height) to be used when reading an image file. The caller initializes inSize to the desired width and height. If the requested size is not supported, an error is returned. Note that when an image file is opened, the image reader sets its internal state for the image size to the width and height of the image. set_image_size is not affected by the transform state. For image formats that do not support scaling, set_image_size also sets the internal state for display size automatically (appropriately adjusted for the current transform).
| in UMSImageSize *inSize | inSize specifies the size of the current image to be used when reading it. |
The default size is Base (768x512). Because all Photo CD images have landscape orientation on Photo CD discs, the image width must always be longer than the image height when set_image_size is called; otherwise, an error is returned.
The method returns the currently specified size to be used in reading an image file. Note that the size reflects the width and height when the image is next read, and is not necessarily the width and height of any in-memory pixmap of the current image. get_image_size is not affected by the transform state.
| out UMSImageSize size | size returns the currently specified image size to be used when reading an image file. |
The method sets the size of the displayable image. inSize contains the desired display size. The specified size is either accepted or rejected. If scaling is not supported for an image format, the valid display sizes are identical to the image sizes reported by get_image_sizes. If you want to display an image that is the same size as the image contained in an image file, the same size should be specified to both set_image_size and set_display_size; no scaling takes place. (However, the transform state can cause the image and display widths and heights to be reversed with respect to each other. If the current transform results in a display size with width and height reversed from the image width and height, attempts to call set_display_size with a width and height that do not match this current transform is rejected.) If the image and the display sizes are not the same, then software scaling occurs (if supported by the image reader associated with that format). Scaling can result in performance degradation. Note that when an image file is opened, the image reader sets the internal state for both image and display sizes to default values. Consequently, if scaling is not supported for a format, the caller never need call set_display_size.
set_display_size is affected by transformations to an image's orientation. For example, if the currently specified image's width and height on disk is 512 and 768 but its orientation is 90 degrees, then set_display_size must specify the width as 768 and the height as 512; an attempt to set the size to a width of 512 and a height of 768 returns an error.
| in UMSImageSize *inSize | inSize specifies the size of the displayable image. |
CurrentTransformAndDisplaySizeConflict
The method returns the currently specified size to be used when displaying an image file. get_display_size is affected by transformations to an image's orientation. For example, if the currently specified image's width and height are 512 and 768 and the display size was set to the image size, when its oriention is changed to 90 degrees, get_display_size returns the width as 768 and the height as 512.
| out UMSImageSize size | size returns the current size of the displayable image. |
The method returns TRUE if arbitrary scaling (That is, any desired size) is supported for the current image format. FALSE is returned if arbitrary scaling is not supported. Scaling is not supported for Photo CD images, but is supported by JPEG. In those cases where arbitrary scaling is not supported, the display size must be the same as the current image size. Note that in those cases where scaling is supported and an image file contains multiple image resolutions, scaling occurs if the display and image sizes are not the same, even if both sizes are set to different images resolutions that are valid. (The image reader reads from disk the resolution specified via set_image_size [rather than the size specified by set_display_size], and then scales to the size specified by set_display_size.)
The method receives as input inFlag, which specifies the coordinate system in which the subimage inRect is defined. (inFlag is set either to SOURCE_COORDINATE_SYSTEM or DESTINATION_COORDINATE_SYSTEM.) The method returns via outRect the corresponding coordinates of the subimage in the other coordinate system. This allows the caller to define, for example, the subimage coordinates in image space (that is, source space) and query what the corresponding subimage coordinates in display space (that is, destination space) are. Source space is defined to be unscaled and untransformed (that is, the image as contained in the image file), while destination space is defined to be scaled and transformed (that is, the current scaling factor and transformation are applied). Consequently, you can use this method to determine how much memory must be allocated for subsequent calls to read_image. For scalable formats, the method uses the proportional ratios of the image width and height to the display width and height in its conversion of subimage coordinates from one coordinate system to another.
To specify the full image, set all fields in the UMSImageRect structure that are pointed to by the input parameter InRect to 0 rather than using the actual coordinates of the image.
The method returns an error if no image file has been opened.
Note: For PhotoCD overview images, the get_subimage_coordinates method supports only full images; subimages of overviews are not allowed.
The method reads a rectangular image area defined by rect from an image into a corresponding rectangular area in the memory block buffer. The coordinate space of the rectangle can be either defined in the image space or the display space; this definition is supplied by the flag parameter. buffer._buffer must point to the address of the first byte to which image data should be written; therefore, if the first byte is at coordinates (x,y) in a buffer, buffer._buffer should point to the address that corresponds to location (x,y), and buffer._maximum should be set to at least the number of bytes contained in the rectangle. To read the entire image, rect can be set to NULL or all fields in rect can be set to 0. The value of stride specifies the offset in bytes from the beginning of one row to the beginning of the next row of buffer. This allows subimages to be placed into preexisting image data. (For subimages to be copied into preexisting image data, the format of the subimage data must be the same as that of the preexisting image data; otherwise, the results of read_image is undefined.) If stride is set to 0, the method sets stride to the number of bytes in the display width, in the case when rect is NULL or filled with zeroes, or to the number of bytes in one line of the subimage width, in the case of a defined subimage. read_image sets buffer._length to the number of bytes actually changed. See the Usage of read_image figure for more information.
The caller is responsible for allocating buffer._buffer, which must be large enough to accomodate rect. Note that, depending on the format selected, the size of the buffer could be up to four times larger than the number of pixels in the image. (For example, this would be the case for format IF_PadRGB24, since it requires four bytes for each pixel of image data.) The image format is set by calling set_format. The default transform for the image is whatever transform produces the image right-side-up. However, if the image transform has been changed by the caller, that transform is used by read_image. For data formats with pad bytes, the pad byte is not written to (or read from) by read_image. To ensure that the pad byte is set to the desired value, you should initialize the pad bytes in buffer to that value before passing it to read_image. read_image uses the current settings for transform, resolution, color format, color rendering, plane offset, and pixel offset when reading data, all of which are controlled by other methods.
To read a subimage into a pixmap that is not the size of the image and to not have the subimage scaled (when using an image reader class that supports scaling), the caller must define the display size to be the same size as the image size. Additionally, stride must be set to the number of bytes in the pixmap width.
For JPEG, the image reader's performance in reading images is affected by its state. To maximize performance when reading JPEG images, the image and display sizes should be the same. In addition, the entire image (as opposed to a subimage) should be read, and stride should be set to 0 (In other words, set rect to NULL and stride to 0, with the display size set to the image size). buffer._maximum must equal the display size multiplied by the display width multiplied by the required number of bytes per pixel.
ComponentNumberAndFormatMismatch
StrideAndCurrentFormatConflict
The only valid image size for the format IF_RGB24Plane is the entire image; subimages cannot be read with this format.
Reading subimages of overviews is not supported. rect must either be NULL, set to 0, or set to the size of a full image. Two image sizes are supported, BASE/64 and BASE/16.
The method allows the caller to change the brightness, saturation, and red, blue, and green color balances of an image when reading it from disk. Each setting is a signed short value. The default setting for all values is 0, which signifies that no change is made to the property. A negative number reduces the associated color property, while a positive number increases it. The internal state of the image reader's color property values are reset to 0 whenever an image file is opened. If color properties cannot be set for a particular type of image reader and set_color_properties is called, the default value for all properties is returned in outProperties.
The method allows the caller to determine the current color property settings used when reading an image.
| out UMSImageColorProperties properties | properties returns the current color property settings. |
The method returns TRUE if changing color properties is supported for the current image format. FALSE is returned if it is not supported. Changing color properties is supported only for Photo CD images.
The method closes an image file and releases all memory allocated by open.
The method returns the applicable detector file type alias defined in "MetaClass Objects" .
| out string image_type | image_type returns a string that specifies the alias of the object's file type. |
The method is used to determine the fully qualified filename of the image file associated with any currently selected image, if any. filename is set to NULL if there is no associated image file. The method allocates filename; the caller deallocates it. The method does not verify that the returned pathname represents an actual file; the file may not exist.
Note: out string filename translates to char **filename in C.
| out string filename | filename returns the fully qualified filename of the image file associated with the currently selected image, if any. |
For a Photo CD overview file, this would return the fully qualified filename of the Image Pac associated with the currently selected thumbnail. If there is no associated image file, the method returns NULL. (This would be the case if the currently selected image was an Image Pac and get_associated_image_path was called.)
The method returns the full pathname of the current image file in pathname. The method allocates pathname, and the caller is responsible for deallocating the storage. The method also allocates and returns info._buffer, a pointer to the first pointer in an array of string pointers; the caller is responsible for deallocating the storage. The number of strings is specified in info._maximum and info._length. The contents of the string are image format dependent, but are related to the current image file. If there is no such information, info._buffer is set to NULL and info._length is set to 0.
The method allocates and returns info._buffer, a pointer to the first pointer in an array of string pointers; the caller is responsible for deallocating the storage. The number of strings is specified in info._maximum and info._length. The contents of the string are image format dependent, but are related to the current image. If there is no such information, info._buffer is set to NULL and info._length is set to 0.
The method returns the progress of the current image read operation, expressed as a percentage of the entire operation. If no reads have ever been made when get_read_progress is called, 0 is returned. If the most recent read operation has completed before get_read_progress is called, 100 is returned. The internal state for percent is reset to 0 whenever set_image is called successfully. The progress reported is that of the read operation only; in some cases, further processing of data can occur, and the time required for such processing is not reported by get_read_progress.
| out unsigned long percent | percent returns the progress of the read operation currently in progress as a percentage of the operation. |
The method returns any copyright information that is associated with the current image. If there is no information, info._length is set to 0 and info._buffer is set to NULL. If there is copyright information, info._length and info._maximum is set to the size of the buffer that contains this information, and info._buffer points to the first byte of that buffer.
| out sequence<octet> info | info contains a pointer to any copyright information associated with the current image (if any) and the size in bytes of the buffer that contains this information. |
The method returns the number of bytes required to contain the image data returned by read_image. This number can be either for a subimage or the entire image. To obtain the buffer size for the full image, rect can be set to NULL or all of rect's fields be set to 0. The buffer size is calculated using the currently defined image data format. The subimage can be defined either in the source or destination coordinate system, but in both cases the buffer size applies to the size of the destination image (for example, if the subimage is specified in source coordinates and scaling is involved, the buffer size returned is the buffer size required for the scaled subimage). The method also returns in depth the number of bytes per pixel for the current format.
The method returns an array of UMSImageDitherTypes enumerations that specify which dither algorithms are supported for the current format. If dithering is not supported for the current format, dithers->_length is set to 1 (for one element), and the one element pointed to by dithers->_buffer contains the value NO_DITHER. The method allocates the array, and the caller must deallocate it. (The method returns an array of unsigned longs.)
The method allows dithering to be turned off or set to one of several dithering algorithms. If the requested dither type specified by inDither is not supported, the return code UMSImageReader_ValueChanged is returned and outDither set to a supported UMSImageDitherTypes value. outDither is set to the current dither type.
For introductory information, see Formatted File Access Objects.
