Images

This module defines COM interfaces for dealing with pixel-map images. Greyscale, color and alpha mapped images can be read, written, loaded and saved using these interfaces. All images present consistent features regardless of their internal representation.

Pixel Formats

Images are defined by their pixel format which consists of a datatype and vector size. There are two data types. The BYTE type is an 8 bit integer in the range is 0 to 255. The FLOAT type is a 32-bit floating point number in the nominal range of 0.0 to 1.0. Operations on integer pixel values are clamped so the results are always in the valid range. Floating point colors are not clamped, so the images can represent superbright and superdark pixels.

(1) SDK: LXiIMD_BYTE, etc. defines

The vector sizes are GREY which is one monochrome component; RGB which is a vector of three color components; or RGBA which is a vector of three color components and alpha. The alpha channel is represented by 0 for transparent, 255 for opaque if in byte format, and 1.0 for opaque if floating point format.

(7) SDK: LXiIMC_RED, etc. defines

Image Interfaces

There are several image interfaces, but they all start with the following two methods. The first gets the width and height of the image in pixels. The second returns the pixel format closest to the native storage format for the image data. Both must always return reasonable values, so there are no error conditions.

(11) PY Common: Image methods

Adding Image Attributes

Arbitrary attributes may be added to writeable image objects. These can be read and set using the image ILxAttributes interface.

This function allows a client to add an attribute to an ILxImageWrite object by providing an attribute name and an exotype name. If the attribute has been added successfully, its index will be returned.

Color Image

The basic image interface allows clients to read colored pixels or entire lines. When reading pixels the client should always ask for an RGBA format, but for lines the full range of format conversions is possible.

(25) PY: ImageWrite method

''[[#C11|PY Common: Image methods]]''

Index Image

An index image is one that stores index values at the pixel locations and uses a lookup table to get the color. While the ILxImage interface gets the color values at each pixel, this interface allows access to the underlying index and color map.

(33) PY: IndexImageWrite method

''[[#C11|PY Common: Image methods]]''

Layered Images

In many cases it is useful to add channels to images beyond the basic R, G, B, and A. In other cases, it is useful to preserve multiple sub-images in a composition. These requirements can be met with a layered image object, consisting of a list of named, independent sub-images, each with their own dimensions, offset, and pixel type. Interlayer blending information is also associated with each layer, Photoshop style.

Size

This returns the bounds of the image composition. While the combination of layer sizes and offsets makes it possible that some layers' pixels will not all be in bounds, the entire composition will be cropped at (0,0) to (w,h).

(41) PY: empty LayeredImage user class

pass

Writing Layered Images

Layered image objects will provide an ILxLayeredImageWrite interface for writing.

AddLayer

This is the way a layered image is actually created, adding layers by passing in ILxImage objects. The image object will be locked and released by the layered image, so clients may release the image after setting the layer.

SetType

Layer type and flags can be set using this function.

SetOffset

Pixel offsets for a layer are set with this function.

SetBlending

The blending parameter (or opacity) and the blending mode are set with this function. A list of modes should appear here shortly...

(43) SDK: LXu_LAYEREDIMAGEWRITE define

(44) SDK: empty LayeredImageWrite User Class

Empty LayeredImageWrite Python user class.

(45) PY: empty LayeredImageWrite user class

pass

Tile Image Interface

The tiled image interface provides a way for clients to implement images using tile trees. Tiles will themselves simply be images, so we can manage a global cache of them internally rather than depending on each implementation to manage an internal cache.

A tile tree is a collection of "levels", which are intended to be images of decreasing size. Each image level is broken into tiles, which allows us to only work on small portions of the image instead of loading an entire image. Typically, the image levels decrease in size by power of two.

For example, one dimension of a normal tile tree of an image with size 1024x1024, and tiles of size 256x256, would look like this:

Level 2 _ Level 1 _ _ Level 0 _ _ _ _

Where each _ represents a tile.

One thing to note is that the meaning of "level" is reverse from ImageLevelSample; level 0 is the base of the tile tree, where each tile is the original size, and the highest value of level will have a single tile.

Implementations of the TileImage interface are only required to be able to get the tiles at level 0; they may require the clients to generate tiles above level 0 by resizing the tiles below them.

LevelCount

LevelCount returns the number of levels in the tile tree.

(46) SDK: TileImage::LevelCount

GetTile is the direct way of getting a tile from the tile image. In general, this will be loaded directly from the file off disk. Tiles will simply be an ILxImageID. These should be created by the implementation, and the client will release them.

It should return LXe_OK if it's okay, but LXe_OUTOFBOUNDS if the tile isn't in the image.

(52) SDK: LXu_TILEIMAGE, etc. defines

(53) SDK: empty TileImage User Class

Empty TileImage Python user class.

(54) PY: empty TileImage user class

pass

Image I/O

Images can be loaded and saved with appropriate servers of the loader and saver class. Loading can be opaque for disk-based access, although most loaders are currently direct, so a format, type, size and number of colors must be specified by the recognition method to allow the host to create a suitable image object to receive the data. This is done using a target interface.

(60) SDK: LXu_IMAGELOADERTARGET define

(61) SDK: empty ImageLoaderTarget User Class

Empty ImageLoaderTarget Python user class.

(62) PY: empty ImageLoaderTarget user class

pass

Image Level Access

Images can present an alternate interface that allows them to be accessed as a set of levels. The levels are filtered versions of the image at different scales, and typically are arranged in power-law series. The underlying implementation may be tiled, enabling access to images that are larger than the available memory, since the image server only needs sufficient memory for a single tile. Levels can be used directly when rendering so that the only levels used are those approximating the visual scale of the image in the rendered scene.

The count returns the number of different levels in the image.

(63) SDK: ImageLevelSample::Count

Each resolution level should be twice the size of the previous level, starting at 1x1 pixels for level zero, although the tiled image load can pass back slightly different dimensions for each resolution level, according to the needs of the tiled format. The image may or may not provide the full image as a level, although the full image must be accessible through the required ILxImage interface.

(67) SDK: ImageLevelSample::GetPixel

Levels also support line-by-line access through a modified version of the GetLine() method, which uses a y-coordinate in the local coordinate system of the specified level. The data returned is always RGBA in floating point.

(76) PY: empty Service.Image user class

pass

Image Compression

Image block codec interfaces allow an image to be compressed into a block of data which can then be included in other files, such as for thumbnails. Compress() allocates and returns a block encoding the image. Free() frees the block when the client is done. Decompress() creates an image from a block.

(78) SDK: LXu_IMAGEBLOCKCODEC, etc. defines

Animation Creation

Since there's really no better place for this we'll put the simple animation interface here. This is a very simple API for creating animations.

The LXsMOVIE_OPTIONSCOMMAND tag identifies a command that should be executed to set options for the movie saver. It is commonly called when the user has chosen the movie saver from a file dialog, and in any other situation where the user needs to be presented with saver options before actually saving the movie.

(79) SDK: LXu_MOVIE, etc. defines

Movie creation API is pretty simple - you begin a movie, add a bunch of images in sequence, and then end it. The movie itself lives on disk at the path specified. There are currently no flags defined, but there may be in the future. Default format is MP4 and default framerate is 15 fps.