IMAGE_CREATE Function

Creates an associative array in image format.

Usage

Input Parameters

The input array must be in one of the following forms, where w is the image width, h is the height, and img_count, an optional parameter, is the number of images in the array:


(w, h [, img_count])	8-bit (pseudo-color) images
(3, w, h [, img_count])	24-bit (direct color) images, pixel interleaved
(w, 3, h [, img_count])	24-bit (direct color) images, row interleaved
(w, h, 3 [, img_count])	24-bit (direct color) images, image interleaved

Returned Value

image

An associative array in image format.

Keywords

Colormap

A 3-by-n colormap array.

NOTE: If the input pixel_array is 2D and the Colormap keyword is not specified, the returned image is assumed to be grayscale.

Colormodel

A long integer specifying the color model:


0	Monochrome or gray scale
1	RGB
2	CMY *
3	HSV *
* Currently not supported

Comments

A string containing additional information about the image. This feature is supported for GIF, JPEG, MIFF, PNG, TGA, and TIFF formats.

Depth A long integer specifying the number of bits per channel. (Default: 8)

File_Name A string containing a default filename for the image.

File_Type A string specifying the type of image file to create. For example, 'sun' denotes a Sun Rasterfile. (Default: TIFF)

NOTE: See the Discussion section of the IMAGE_READ function for a list of valid file types.

Img_Count

A long integer specifying the number of images in the output array image. (Default: 1)

Intleave A scalar string indicating the desired type of interleaving of 3D image arrays. (Default: image)

Valid strings and the corresponding interleaving methods are:

'image'

The resulting 3D image array arrangement is (x, y, p) for p image-interleaved images of x-by-y. (Default)

'row' The resulting 3D image array arrangement is (x, p, y) for p row-interleaved images of x-by-y.

'pixel' The resulting 3D image array arrangement is (p, x, y) for p pixel-interleaved images of x-by-y.

Quiet

Suppresses successive levels of error messages, depending on the value set. This keyword accepts the same integer values used with the system variable !Quiet.

Units Units of pixel size. (1 = inches; 2 = millimeters)

X_resolution Pixel size in Units.

Y_resolution Pixel size in Units.

Discussion

The IMAGE_CREATE function creates an image associative array. Complete image information is stored in this type of array, which is used by all of the IMAGE_* routines in PV-WAVE. (Refer to the

-WAVE Programmer's Guide

NOTE: When creating an image that contains 3D pixel data, you must specify the interleaving method if either the width or height has a value of 3. For example, if the dimensions of your data are 100 x 3 x 3 and the data is plane interleaved, it will be interpreted as line interleaved unless you explicitly set the Interleave keyword to the correct value.

The image format associative array allows the following operations:

File I/O of images to and from different file formats
Displaying images
Processing images

Image Associative Array Structure

The following table describes each key of the image associative array.


Array Key Name	Variable Type	Description
file_name	STRING	Absolute or relative pathname of an image file
file_type	STRING	The type of image file. (See IMAGE_READ for a list of supported file types.)
width	LONG	Image width
height	LONG	Image height
img_num	LONG	Index number in the range {0...n} of a subimage in the file (if the image was created with IMAGE_READ)
img_count	LONG	Number of subimages in the pixel array
PIXELS:
nr_cc	LONG	Number of color channels. This item specifies how many storage units are allocated per pixel. (Supported values: 1 and 3)
depth	LONG	Bits per color channel
pixel_dtype	LONG	Data type of the pixel array: 1 BYTE 2 SHORT 3 LONG
interleave	LONG	Interleave method used: 1 = Pixel interleaving 2 = Row interleaving 3 = Image interleaving
color_model	LONG	Color model: 0 Monochrome or gray scale 1 RGB 2 CMY (currently not supported) 3 HSV (currently not supported)
pixels	BYTE SHORT LONG	A multidimensional array describing an 8-bit or 24-bit image. Refer to the Pixel Arrays section later for a description of supported pixel arrays.
x_resolution	FLOAT	Pixel size in units
y_resolution	FLOAT	Pixel size in units
units	LONG	Units of pixel size: 1 (inches) 2 (mm)
COLORMAP:
cmap_type	LONG	Type of colormap: 0 No colormap 1 1 colormap vector (not supported) 2 Multiple colormap vectors
cmap_dtype	LONG	Data type of colormap (only BYTE (1) is supported)
n_colors	LONG	Number of entries in the colormap
colormap	BYTE SHORT LONG	Array whose dimensions depend on cmap_type and n_colors. cmap_type: 1 : not supported 2 : (3 , n_colors)
SUPPLEMENTARY and CONTROL:
label	STRING	Optional annotation (NOTE: None of the supported graphics file types currently support labels.)
comments	STRING	Optional information about source, etc.
status	LONG	0 = success; 0 = error
** This data type is currently not supported for IMAGE_READ and IMAGE_WRITE. IMAGE_CREATE accepts an array in this data type, but before writing the image to a file the pixel array must be converted to BYTE.

Pixel Arrays

This table describes valid pixel arrays.


Color Model	Number of color channels (nr_cc)	Bits per pixel	Colormap	Number of color channels in colormap	Dimensionsof pixel array
True Color RGB	3	24	No	N/A	3D **
GrayScale	1	8	Yes	3	2D **
Pseudo Color	1	8	Yes	3	2D **
Direct Color	3	24	Yes	3	3D **
** Refer to the Pixel Array Dimensions table for more information.

Pixel Array Dimensions

This table describes the valid pixel array dimensions. The dimensions of the pixel array (width, height, nr_images, etc.) refer to keys in the image associative array.


Type of Array	Description
2D Pixel Arrays:
(width, height, [nr_images])	8-bit (pseudo-color) image
3D Pixel Arrays:
(nr_cc, width, height [, img_count])	24-bit (direct color) image, pixel interleaved
(width, nr_cc, height [, img_count])	24-bit (direct color) image, row interleaved
(width, height, nr_cc [, img_count])	24-bit (direct color) image, image interleaved

Example

This example demonstrates how IMAGE_CREATE creates an image associative array. The associative array is listed using the INFO command.

pixels = BYTARR(100, 200)

; Create some pixel data (all zeros).

cmap = BYTARR(3, 50)

; Create a colormap (all zeros).

image = IMAGE_CREATE(pixels, File_name='test.tif', $
    Colormap = cmap, File_type = 'tif')

; Create the image -- an associative array of image-related ; data. Next, use INFO to display the contents of the array.

INFO, image, /Full


IMAGE	AS. ARR	=	Associative Array(22)
label	STRING	=	''
file_type	STRING	=	'tif'
height	LONG	=	200
units	LONG	=	2
img_num	LONG	=	0
y_resolution	FLOAT	=	72.0000
pixels	BYTE	=	Array(100, 200)
color_model	LONG	=	1
n_colors	LONG	=	50
file_name	STRING	=	'test.tif'
width	LONG	=	100
cmap_type	LONG	=	2
x_resolution	FLOAT	=	72.0000
status	LONG	=	0
img_count	LONG	=	1
nr_cc	LONG	=	1
depth	LONG	=	8
colormap	BYTE	=	= Array(3, 50)
cmap_dtype	LONG	=	1
comments	STRING	=	' '
pixel_dtype	LONG	=	1
interleave	LONG	=	3

IMAGE_CREATE Function

Usage

Input Parameters

Returned Value

Keywords

Discussion

Image Associative Array Structure

Pixel Arrays

Pixel Array Dimensions

Example

See Also