PHOTO_CREATE Function

Creates an image associative array. Refer to File Name Formats for PHOTO for a list of supported file types.

Note:

The PHOTO routines are only available on 64-bit PV-WAVE.

Usage

image = PHOTO_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 PHOTO for a list of valid file types.

Note:

If File_Type is set to ‘DICM’, PHOTO_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 PHOTO_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' or 'plane' — The RGB pixel array arrangement is (xy3) for 3 image-interleaved channels of x-by-y pixels.

'row' or 'line' — The RGB pixel array arrangement is (x3y) for 3 row-interleaved channels of x-by-y pixels.

'pixel' or 'none' — The RGB pixel array arrangement is (3xy) 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 PHOTO_CREATE function creates an image associative array. Complete image information is stored in this type of array, which is used by all of the PHOTO_* 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.

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 PHOTO_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 PHOTO_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:

  1 = BYTE

  2 = INT

  3 = LONG

13 = INT32

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

Pixel Arrays

Valid Pixel Arrays describes valid pixel arrays.

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

 

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.

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 PHOTO_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 -- an associative array of image-related 
; data. Next, use INFO to display the contents of the array.
image = PHOTO_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 = PHOTO_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 = PHOTO_WRITE('image_create_ex2.tif', $
   PHOTO_CREATE(img, Comments='little', Depth=16))
; Read it back in.
new_img = PHOTO_READ('image_create_ex2.tif')
INFO, new_img, /Full
TVSCL, new_img('pixels'), 400, 0

See Also

PHOTO_DISPLAYPHOTO_READ, PHOTO_WRITE 

System Variables:  !Quiet