READ IMAGE

READ IMAGE

Input Command

Reads an image file that is in JPEG, PNG, or GIF format.

Scientific data is increasingly collected in the form of images. Although Dataplot does not currently support an explicit image data type, the READ IMAGE command can be used to read images into Dataplot in the form of real numbers (i.e., each real number represents the intensity value of a given pixel in the image).

There are two forms for this command:

1. You can read the image data into a matrix.

2. You can read the image data into a response variable, a row-id variable, and a column-id variable.

The best choice depends on what analysis you intend to perform on the data. If you will not be using the matrix specific commands, the second form is typically more useful.

Images can be either grey scale (i.e., a single color with varying intensity levels) or color. Color images are represented with intensity values for red, green, and blue (RGB). Although RGB is not the only color model used, it is currently the only one supported in Dataplot.

Dataplot implements the READ IMAGE command using the GD library. The GD library was developed by the Boutell company. GD in turn uses three additional libraries: zlib, libpng, and libjpeg. These libraries are all freely downloadable from the web. The URL for GD is (this site contains links to the other three libraries):

http://www.libgd.org

The READ IMAGE command depends on the GD library being integrated into Dataplot. Currently, it should be available on most Linux and Mac OSX implementations. However, it is not currently available on the Microsoft Windows implementation.

Note that the primary purpose of reading images into Dataplot is in order to perform data analysis on the image data. Although you can use the LET comamnd to perform some basic image manipulation tasks, image manipulation is not a primary goal for the Dataplot developers.

READ IMAGE <file> <m>
where <file> is the name of the file containing the image;
and     <m> is the matrix where the image will be saved.

This syntax is used to save a grey scale image into a matrix.

READ IMAGE <file> <r> <g> <b>
where <file> is the name of the file containing the image;
            <r> is the matrix where the red component of the image will be saved;
            <g> is the matrix where the green component of the image will be saved;
and     <b> is the matrix where the blue component of the image will be saved.

This syntax is used to save an RGB image into 3 separate matrices (one matrix for each color).

READ IMAGE TO VARIABLES <file> <y> <rowid> <colid>
where <file> is the name of the file containing the image;
            <y> is the variable where the image data will be saved;
            <rowid> is a variable that identifies the row of the image;
and     <colid> is a variable that identifies the column of the image.

This syntax is used to save a grey scale image into a single response variable and corresponding row-id and column-id variables.

READ IMAGE TO VARIABLES <file> <r> <b> <g> <rowid> <colid>
where <file> is the name of the file containing the image;
            <r> is the variable where the red component of the image data will be saved;
            <b> is the variable where the blue component of the image data will be saved;
            <g> is the variable where the green component of the image data will be saved;
            <rowid> is a variable that identifies the row of the image; and     <colid> is a variable that identifies the column of the image.

This syntax is used to save an RGB image into a three response variables (one for each color component) and corresponding row-id and column-id variables.

READ IMAGE TO VARIABLES IMAGE_GREY.JPG Y ROW COL
READ IMAGE TO VARIABLES IMAGE_COLOR.JPG RED BLUE GREEN
READ IMAGE IMAGE_GREY.JPG M
READ IMAGE IMAGE_COLOR.JPG RED BLUE GREEN

The current implementation supports a limited number of image file formats. If you have image data in some other format (and there is a long list of available image formats), you will need to convert the image to either JPEG, PNG, or GIF format.

ImageMagick and Netpbm are two freely downloadable software suites that are capable of converting image formats for a wide variety of image formats (they also contains many image manipulation tools). ImageMagick and Netpbm will often be installed on Unix/Linux platforms and they are freely downloadable for most common computer platforms. In addition, programs such as Perl have integrated the Image Magick libraries to provide image conversion and manipulation capabilities.

If you need to perform some basic image manipulation tasks, it is probably easier to use one of these software programs (or some other image manipulation tool) first before reading the image into Dataplot.

The ImageMagick software can be downloaded from the following web site:

http://www.imagemagick.org/

The Netpbm software can be downloaded from the following web site:

http://netpbm.sourceforge.net/

Windows users may find it more convenient to use

http://gnuwin32.sourceforge.net/packages/netpbm.htm

We are investigating the possibility of integrating one or both of these libraries into a future release of Dataplot in order to provide direct access to a greater range of image formats and to provide some basic image manipulation capabilities.

There are some limitations on the size of the images that Dataplot can handle.

If you use the READ IMAGE TO VARIABLES form of the command, the limiting factor is the maximum number of rows for a single variable. On most platforms, the default is to have 10 columns with a maximum of 1,000,000 rows. You can use the DIMENSION command to create more columns at the expense of fewer rows. However, you cannot create more rows (i.e., the minimum number of columns is 10).

So multiply the number of rows by the number of columns in your image to see the minimum number of rows you need. For example, if you have a 512x512 image, you need 262,144 rows of data. If your version of Dataplot has a maximum of 1,000,000 rows, then you can accomodate images up to 1,000x1,000.

You may want to do something like the following before using the READ IMAGE TO VARIABLES command:

LET NUMROW = 512
LET NUMCOL = 512
LET MAXROW = NUMROW*NUMCOL
DIMENSION MAXROW ROWS


If you use the READ IMAGE command, you will typically need to create a large number of columns (which means you will be able to accomodate fewer rows in any variables you create). You may want to do something like the following before using the READ IMAGE command:

LET NUMROW = 512
LET NUMCOL = 512
DIMENSION NUMROW
MATRIX DIMENSION ROWS NROWS


This will give you the maximum number of columns based on the number of rows in your image. The MATRIX DIMENSION is used to dimension temporary matrices in the various Dataplot MATRIX commands.

The maximum row size is set before Dataplot is built. To see what it is on your platform, you can enter the command

DIMENSION 10 COLUMNS

The value given for the line MAXIMUM NUMBER OBS/VARIABLE (ROWS) specifies the maximum number of rows for your implementation.

Unlike most of the other READ commands, the file name argument is required on the READ IMAGE command.

DATAPLOT has no restrictions on the file name other than it be a valid file name on the local operating system and that it contain a period "." in the file name itself or as a trailing character. DATAPLOT strips off trailing periods on those systems where it is appropriate to do so. On systems where trailing periods can be a valid file name (e.g., Unix), DATAPLOT tries to open the file with the trailing period. If this fails, it then tries to open the file with the trailing period stripped off.

Although Dataplot does not require specific file extensions for the other READ commands, it does require them for the READ IMAGE command. The file extension is used to determine whether a JPEG, PNG, or GIF file is being read. JPEG files should have a ".jpeg", ".jpg", ".JPEG", or ".JPG" extension, GIF files should have a ".gif" or ".GIF" extension, and PNG files should have a ".png" or ".PNG" extension.

File names are case sensitive on Unix file systems. For Unix, DATAPLOT attempts to open the file as given. If this fails, it attempts to open the file as all upper case characters. If this fails, it attempts to open the file as all lower case characters. All other currently supported systems are not case sensitive regarding file names.

As a further caution for Unix hosts, certain expansion characters (specifically ~ to refer to your home directory) are interpreted by the shell and are not recognized by the Fortran compiler. These expansion characters are interpreted as literal characters and do not yield the intended file name.

None

None

IMAGE PLOT	= Display an image.
READ	= Read variables.
READ MATRIX	= Read matrix data.
READ STACKED VARIABLES	= Read a list of variables into a single response variable and a group-id variable.
CREATE MATRIX	= Create a matrix from a list of variables.

Data Input

2008/3

 
dimension 10 variables
read image to variables takashi.jpg  red blue green rowid colid
.
probe iopsy1
if probeval = 1
  device 1 x11
  device 1 picture points 600 600
  erase
  erase
end of if
.
set ipl1na takashi_image.jpg
set gd color true
device 2 gd jpg
device 2 picture points 600 600
.
char size 1
frame off
frame corner coordinates 5 5 95 95
.
image plot red rowid colid
.
device 2 close