Reference Guide > I–L Routines > IMAGE_CREATE Function
  
IMAGE_CREATE Function
Creates an image associative array. Refer to File Name Formats for IMAGE for a list of supported file types.
 
note
If you have 64-bit PV-WAVE and need to read and write images up to 32-bits without constraints on data size, use the PHOTO OPI routines.
Usage
image = IMAGE_CREATE(pixel_array)
Input Parameters
pixel_array—An array containing image data. 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 (RGB) images, pixel interleaved
*(w, 3, h[, img_count])—24-bit (RGB) images, row interleaved
*(w, h, 3[, img_count])—24-bit (RGB) images, image interleaved
Returned Value
image—An image associative array.
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 (Currently not supported)
*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
Refer to File Name Formats for IMAGE for a list of valid file types.
 
note
If File_Type is set to ‘DICM’, IMAGE_CREATE adds the following File Meta Information and DICOM tags to the ‘comments’ key of the image associative array:
 
*(0002,0000) FileMetaInformationGroupLength
*(0002,0001) FileMetaInformationVersion
*(0002,0002) MediaStorageSOPClassUID
*(0002,0003) MediaStorageSOPInstanceUID
*(0002,0010) TransferSyntaxUID
*(0002,0012) ImplementationClassUID
*(0002,0013) ImplementationVersionName
*(0002,0016) SourceApplicationEntityTitle
*(0002,0100) PrivateInformationCreatorUID
*(0002,0102) PrivateInformation
*(0008,0016) SOPClassUID
*(0008,0018) SOPInstanceUID
*(0008,0064) ConversionType
*(0020,000D) StudyInstanceUID
*(0020,000E) SeriesInstanceUID
*(0028,0002) SamplesPerPixel
*(0028,0004) PhotometricInterpretation
*(0028,0006) Planar Configuration
*(0028,0010) Rows
*(0028,0011) Columns
*(0028,0030) PixelSpacing
*(0028,0100) BitsAllocated
*(0028,0101) BitsStored
*(0028,0102) HighBit
*(0028,0103) PixelRepresentation
*(7FE0,0010) PixelData
Getcolormap—When specified IMAGE_CREATE uses the current colormap.
 
note
The Colormap and Getcolormap keywords are mutually exclusive and cannot be used in the same call to this function.
Img_Count—A long integer specifying the number of images in the output array image. (Default: 1)
Intleave—A scalar STRING indicating the interleaving of the pixel array when it cannot be determined by examining the pixel array itself.
PV-WAVE attempts to determine the interleaving of the pixel array by locating the smallest dimension. In cases where this is ambiguous, for example the pixel data has multiple dimensions of size '3' or the height and/or width of the image is less than '3', PV-WAVE may fail to create the image. In these cases, use the Intleave keyword to indicate to PV-WAVE what the interleaving of your pixel array is.
Valid strings and the corresponding interleaving methods are:
'image'—The RGB pixel array arrangement is (x, y, 3) for 3 image-interleaved channels of x-by-y pixels.
'row'—The RGB pixel array arrangement is (x, 3, y) for 3 row-interleaved channels of x-by-y pixels.
'pixel'—The RGB pixel array arrangement is (3, x, y) for 3 pixel-interleaved channels of x-by-y pixels.
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 PV‑WAVE Programmer’s Guide for additional information on associative arrays.)
 
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 or less. For example, if the dimensions of your data are 100 × 3 × 3 and the data is image interleaved, it could be interpreted incorrectly unless you explicitly set the Interleave keyword to the correct interleaving method.
The image 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
Image Associative Array’s Keys describes each key of the image associative array.
 
Table 10-1: Image Associative Array’s Keys  
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 = INT **
  3 = LONG **
13 = INT32**
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
INT **
LONG **
INT32 **
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
INT **
LONG **
INT32 **
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
Valid Pixel Arrays describes valid pixel arrays.
Table 10-2: Valid Pixel Arrays
Color Model
Color Channels, Number
(nr_cc)
Bits per pixel
Colormap
Color Channels in Colormap, Number
Dimensions, pixel array
RGB
3
24
Optional
3, if colormap present
3D **
GrayScale
1
8
Yes
3
2D **
Pseudo Color
1
8
Yes
3
2D **
** Refer to the Pixel Array Dimensions table for more information.
Pixel Array Dimensions
Pixel Array Dimensions 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.
 
Table 10-3: Pixel Array Dimensions
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 (RGB) image, pixel interleaved
(width, nr_cc, height[, img_count])
24-bit (RGB) image, row interleaved
(width, height, nr_cc[, img_count])
24-bit (RGB) image, image interleaved
Example 1
This example demonstrates how IMAGE_CREATE creates an image associative array. The associative array is listed using the INFO command. 
; Create some pixel data (all zeros).
pixels = BYTARR(100, 200)
 
; Create a colormap (all zeros).
cmap = BYTARR(3, 50)
; Create the image associative array. Next, use 
; INFO to display the contents of the array.
image = IMAGE_CREATE(pixels, File_name='test.tif', $
   Colormap=cmap, File_type='tif') 
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
Example 2
; Make up some unsigned 16-bit data and put it in a long array.
img = IMAGE_READ(!Dir + '/demo/gallery3/data/veggies.jpg')
img = SCL(img('pixels'), 65535, /Long)
WINDOW, Xsize=800
TVSCL, img
 
; Write a 16-bit tiff file.
status = IMAGE_WRITE('image_create_ex2.tif', $
   IMAGE_CREATE(img, Comments='little', Depth=16))
 
; Read it back in.
new_img = IMAGE_READ('image_create_ex2.tif', File_type='tiff16')
 
INFO, new_img, /Full
TVSCL, new_img('pixels'), 400, 0
See Also
IMAGE_DISPLAY,    IMAGE_READ,   IMAGE_WRITE
System Variables:  !Quiet
Version 2017.0
Copyright © 2017, Rogue Wave Software, Inc. All Rights Reserved.