The Image3 Script

The Image3 Script
by Zachary X. Reiter and Clifford A. Reiter
October 2002

The image3 addon script, image3.ijs, contains the main functions used for reading, writing and converting image files. While the emphasis is on 24 bit images, there is some support for movies and 8-bit images. File extensions of *.bmp, *.jpg, *.jpeg, *.png, *.pnm, *.tga, *.pgm, and *.ppm are the listed image types which may be read (although not every variant of the image formats is necessarily supported). Movie *.mov and *.avi support requires loading the script movie3.ijs.

The Data Forms for Images are:

h by w by 3 array of integers (range 0-255): this is the main data form
h by w by 3 array of bytes (characters): compact data form
h by w by 1 array of integers (range 0-255) or bytes: Grayscale image
(p;B) where p is an integer palette of RGB values (0-255) and B is an h by w array of indices into the palette.

The left argument (adverb) of write_image may be data in any of those forms. The grayscale format is primarily intended for access to Jpeg grayscale images. Paletted images are promoted to 24 bit images before being saved except for *.bmp and *.png files which are saved as 8-bit images.

The Main Functions

The syntax for using the main functions follows. The filename extension is used to determine the image file type both for reading and writing images. See the Image3 lab for active illustrations and the script itself for many utilities which are used indirectly.

read_image 'imagefile' results in an h by w by 3 array of integers representing the rgb triples for each pixel
raw_read_image 'imagefile' results in an h by w by 3 array of bytes representing the rgb triples for each pixel
[options] data write_image 'filename' where data has one of the above image data forms and the options are specific to the image type.
image_wh 'filename' results in the width and height of the image
[options] conv_image 'in_filename';'out_filename' reads an image and writes the result to a file

See also the section on Palette Utilities for reading paletted images.

General and File List Utilities

Pathnames are assumed to always end with a directory seperator.

wh_bounds resize_image B which resizes the 2 or 3 dimensional array B into an image fitting into the wh_bounds while preserving the aspect ratio of the original image.
'pattern' files_in 'path' results in the images in the given directory matching the given pattern. For example: 'pic*.bmp' files_in 'my_images\'
file_selector fseq_adjoin path1;path2[...] uses file_selector to select files from each directory in the list of directories and moves those selected files to a list in the first directory. Files moved from other directories are renamed with sequencial suffices. This is useful for merging directories of digital camera pictures with overlapping file names into one directory with a single sequence of names.
fn_num_suffix 'filename' results in the numeric suffix of a filename; empty if none.
num new_fn_seq oldfilenameseq results in a filename sequence with numeric suffix "num" and name similar to the first name in the name sequence.
nx_fn 'filename' results in the filename with numeric suffix, if any, incremented; otherwise, the same filename is given.
numdig nfmt n formats n with leading 0's and "numdig" number of digits (default 3).
short_fn 'filename' results in the filename with path removed up to the level given by the left argument. The default argument is 0 which gives a pathless name.
path_fn 'filename' results in the path of the full filename.
fn_ext 'filename' results in the extention of the filename.
'new_ext' ch_ext 'filename' results the filename with the extention changed to the left argument.
to_lc 'string' changes any uppercase characters in 'string' to lower case.
default_th_nm d_fn_ck y checks (rank 1) that y is a filename/thumbnail pair; if not, ending blanks in the filename are removed and the left function, defaut_th_nm is applied to produce the thumbnail name.
exif_info 'filename' gets the exif data (camera exposure data for the image), if any, from the image specified by the filename.

Palette Utilities

The script also contains some utilities for working with paletted images:

Hue y gives a pure hue (along the "line" segments from red-yellow-green-cyan-blue-magenta and back to red) as y runs from 0 to 1.
[pal_sz] quantize_image B results in a paletted image with no more than pal_sz<:256 number of entries.
[pal_sz [sampling]] quantize_image_nn B results in a paletted image with no more than pal_sz<:256 number of entries. The algorithm is based upon neural nets. Sampling may be set to in the range 1-30 with lower numbers giving improved quality and requiring more processing time.
'p b'=:pal_read_bmp 'file.bmp' reads a paletted *.bmp file resulting in the palette p and the indices b
'p b'=:pal_read_png 'file.png' reads a paletted *.png file resulting in the palette p and the indices b

The jpeg Options

The jpeg options are, in order, jpeg_quality, progressive, grayscaling; their default values are:

jpeg_quality=: 75  Range (1-100), default is 75
progressive=:      Default is 0 (false), 1 is true
gray_scaling=:  0  NB.  _1 never (promote to rgb) 
                   NB.   0 preserve;ie, use trailing axis; (default)
                   NB.   1 always (make gray)
                   NB.   2 when gray, save as gray scale

Using jpeg_quality near 100 results in large, high quality image files; values near 75 are average quality and much smaller. Values near 0 result in very small images, but the quality is extremely poor.

The png Options

Png options allow improvements in file size (usually only small changes occur) in exchange for longer processing.

png_compression=: _1  NB. default (seems to be 6)
                      NB. 0 best speed
                      NB. 9 best compression

Link to:
Image3 Main Help