Image Class Reference
#include <xsi_image.h>
This class provides read-access to the representation of an image in memory.
For the vast majority of image files XSI will represent the data in memory as uncompressed 8-bit RGBA. This is true even if the original file has no alpha information. However, high quality 16-bit and floating point images can also be read via Image::GetPixelArray. You can determine what format the image data contains by means of Image::GetNumChannels and Image::GetChannelSize.
using namespace XSI;
Application app ;
// Create an image clip based on one of the
// image files from the XSI installation
CString strImagePath ;
strImagePath = app.GetInstallationPath( siFactoryPath );
strImagePath += L"/Data/XSI_SAMPLES/Pictures/upper_eyelash.jpg" ;
CValueArray args(2);
CValue retVal;
args[0] = strImagePath ;
args[1] = L"MySmallClip" ;
app.ExecuteCommand( L"CreateImageClip", args, retVal ) ;
ImageClip2 newClip = retVal ;
Image myImage = newClip.GetImage() ;
app.LogMessage( L"Image has resolution " + CValue( myImage.GetResX() ).GetAsText() +
L" by " + CValue( myImage.GetResY() ).GetAsText() ) ;
app.LogMessage( L"Image has " + CValue( myImage.GetNumChannels() ).GetAsText() +
L" channels and " + CValue( myImage.GetChannelSize() ).GetAsText() +
L" bytes per channel" ) ;
app.LogMessage( L"Total size of the uncompressed image data is "
+ CValue( myImage.GetPixelArraySize() / 1024l ).GetAsText()
+ L" kb" ) ;
// Get the pixel value at (45, 25)
unsigned char aColor[4] ;
myImage.GetPixelValue( 45.0, 25.0, aColor[0], aColor[1], aColor[2], aColor[3] ) ;
// Alternatively we can use the CColor object, which holds the color as
// normalized doubles
CColor myColor ;
myImage.GetPixelValue( 45.0, 25.0, myColor ) ;
// Expect results of running this example:
// INFO : "Image has resolution 875 by 300"
// INFO : "Image has 4 channels and 1 bytes per channel"
// INFO : "Total size of the uncompressed image data is 1025 kb"
Public Member Functions |
|
| Image () | |
| ~Image () | |
| Image (const CRef &in_ref) | |
| Image (const Image &in_obj) | |
| bool | IsA (siClassID in_ClassID) const |
| siClassID | GetClassID () const |
| Image & | operator= (const Image &in_obj) |
| Image & | operator= (const CRef &in_ref) |
| CStatus | GetPixelValue (float in_X, float in_Y, CColor &out_Pixels) const |
| CStatus | GetPixelValue (float in_X, float in_Y, unsigned char &out_R, unsigned char &out_G, unsigned char &out_B, unsigned char &out_A) const |
| LONG | GetResX () const |
| LONG | GetResY () const |
| LONG | GetNumChannels () const |
| LONG | GetChannelSize () const |
| const void * | GetPixelArray () const |
| LONG | GetPixelArraySize () const |
| Image | ( | ) |
Default constructor.
| ~Image | ( | ) |
Default destructor.
| bool IsA | ( | siClassID | in_ClassID | ) | const [virtual] |
Returns true if a given class type is compatible with this API class.
| in_ClassID | class type. |
Reimplemented from CBase.
| siClassID GetClassID | ( | ) | const [virtual] |
Creates an object from another object. The newly created object is set to empty if the input object is not compatible.
| in_obj | constant class object. |
Creates an object from a reference object. The newly created object is set to empty if the input reference object is not compatible.
| in_ref | constant class object. |
Reads the color value at a specified pixel value in the image.
When in_X or in_Y are not whole numbers
Bilinear interpolation is used to determine a subpixel value. The
bottom left of the image is considered pixel 0,0.
| in_X | X coordinate on the image. |
| in_Y | Y coordinate on the image. |
| out_Pixels | The color of the image at the given coordinate |
| CStatus GetPixelValue | ( | float | in_X, |
| float | in_Y, | ||
| unsigned char & | out_R, | ||
| unsigned char & | out_G, | ||
| unsigned char & | out_B, | ||
| unsigned char & | out_A | ||
| ) | const |
Alternative signature of GetPixelValue which retrieves the color of the pixel as 4 RGBA bytes.
Currently this function only works for 8-bit RGBA images. For other image formats it is possible to read pixel values by calling Image::GetPixelArray.
| in_X | X coordinate on the image. |
| in_Y | Y coordinate on the image. |
| out_R | The red component value of the color of the image at the given coordinate |
| out_G | The green component value of the color of the image at the given coordinate |
| out_B | The blue component value of the color of the image at the given coordinate |
| out_A | The alpha component value of the color of the image at the given coordinate |
| LONG GetResX | ( | ) | const |
Returns the resolution, in pixels, of the horizontal dimension.
| LONG GetResY | ( | ) | const |
Returns the resolution, in pixels, of the vertical dimension.
| LONG GetNumChannels | ( | ) | const |
Returns the number of channels per pixel. Normally this returns 4, representing RGBA. XSI will often represent an image in memory with 4 channels even if the underlying file format has no alpha information.
| LONG GetChannelSize | ( | ) | const |
Returns the number of bytes per channel. Normally this returns 1, but 16-bit images will return 2 and 32-bit float images will return 4.
| const void* GetPixelArray | ( | ) | const |
Provides low level access to the image data. The returned buffer should not be modified and the pointer should not be cached outside the lifetime of the Image object. The data is formatted as an array of pixel color values, row by row.
You can find the exact format of each pixel by calling Image::GetNumChannels and Image::GetChannelSize. In the normal case, each pixel is represented by 4 bytes.
| LONG GetPixelArraySize | ( | ) | const |
Returns the total size, in bytes, of the array returned by Image::GetPixelArray. It is expected that this is equal to the product of Image::GetResX, Image::GetResY, Image::GetNumChannels and Image::GetChannelSize.