Image.GetPixelArray

Description

Returns a 2-dimensional array containing the RGBA value for each pixel requested or for every pixel of the Image.

Warning: Getting the entire pixel array for a large image could fail because of insufficient RAM. For large images it is recommended that the image be read one row or column at a time.

C# Syntax

Object Image.GetPixelArray( Object in_saPositionArray );

Scripting Syntax

oArray = Image.GetPixelArray( [PositionArray] );

Return Value

A two-dimensional SAFEARRAY containing the normalized RGBA value for every pixel (see Array). The first dimension contains the RGBA values of each pixel and the second dimension contains the pixels lined up row by row, starting at the bottom left of the image.

Parameters

Parameter Type Description
PositionArray SAFEARRAY (see Array) A 1-dimensional or 2-dimensional array listing the coordinates of each desired pixel.

Examples

1. VBScript Example

'
' This example illustrates how to retrieve the PixelArray using a 
' 2-dimensional pixel position array.
'
' This is an example of a huge JPG image that would be too large 
' to read with a single call to GetPixelArray. Instead we will 
' request only a subset of pixel values.
'
CreateImageClip "$SI_HOME\Data\XSI_SAMPLES\Pictures\jio.jpg"
SelectObj "Clips.jio_jpg"
set oImageClip = Selection(0)
set oImage = oImageClip.GetImage()
' Request the values of 4 pixels of the first column of the image, 
' starting at the bottom pixel and moving upwards
dim aPixelWanted(1,3)
aPixelWanted(0,0) = 0 : aPixelWanted(1,0) = 0
aPixelWanted(0,1) = 0 : aPixelWanted(1,1) = 1
aPixelWanted(0,2) = 0 : aPixelWanted(1,2) = 2
aPixelWanted(0,3) = 0 : aPixelWanted(1,3) = 3
rgba = oImage.GetPixelArray( aPixelWanted )
for i=LBound(rgba,2) to UBound(rgba,2)
	LogMessage "Pixel i :" & i
	LogMessage "R :" & rgba(0,i)
	LogMessage "G :" & rgba(1,i)
	LogMessage "B :" & rgba(2,i)
	LogMessage "A :" & rgba(3,i)
next

2. JScript Example

/*
	This example illustrates how to retrieve the PixelArray using a 
	1-dimensional pixel position array.
*/
CreateImageClip("$SI_HOME\\Data\\XSI_SAMPLES\\Pictures\\jio.jpg", null, null);
SelectObj("Clips.jio_jpg", null, null);
var oImageClip = Selection(0);
var oImage = oImageClip.GetImage()
// Request the values of 4 pixels of the first column of the image, 
// starting at the bottom pixel and moving upwards
var aPixelWanted = new Array();
aPixelWanted[0] = 0;  aPixelWanted[1] = 0;
aPixelWanted[2] = 0;  aPixelWanted[3] = 1;
aPixelWanted[4] = 0;  aPixelWanted[5] = 2;
aPixelWanted[6] = 0;  aPixelWanted[7] = 3;
var aRGBA = new VBArray(oImage.GetPixelArray( aPixelWanted ));
for (i = 0; i <= aRGBA.ubound(2); i++) 
{	LogMessage("Pixel i :"  + i);
	LogMessage("R :" + aRGBA.getItem(0,i));
	LogMessage("G :" + aRGBA.getItem(1,i));
	LogMessage("B :" + aRGBA.getItem(2,i));
	LogMessage("A :" + aRGBA.getItem(3,i));
}