APPENDIX C:

List of Current Operators

 

 


Arithmetic Operators: +, - , *, /

For example, (A1[[1]] + B1[[1]]) / 2. Valid operands are Frame references, image data sets and real numbers; frames are the most complex type of operand, real numbers the least. When two operands differ in level of complexity, the following rules apply: a real number is converted to an array of constant value, and correct dimension, when applied to an image; a frame reference contributes its base image data either grayscale data for a single-channel frame, or R (red), G (green), and B (blue) components for a three-channel frame.


Bitwise Operators: >>, <<, &, |, ^, ~

Valid operands are Frame references,image data sets and unsigned 8 bit. Some of the bitwise operators do not work with floating point datasets.
Usage : Operand1 bitwise operator Operand2
Note :
a) If the operand1 is right shifted (>>) by operand2 whose value is greater than 8, then operand1 will be shifted by operand2 mod 8.
b) If the resultant obtained as a result of performing left shift operation (<<) is greater than 256, then the effective resultant will be modular 256 of the result.


Col[]

This is a convenience function. If frame F contains this function in its formula, the function returns the column index of frame F. For example, for frame C2[[10]], the Col function returns 2.


Convert

[

data, frame or image dataset,
out_datatype, Datatype*
in_min, scalar default: min of data
in_max, scalar default: max of data
in_min_percent, scalar default: 0, max value: 100
in_max_percent, scalar default: 0, max value: 100
out_min, scalar default: min of out_datatype
out_max, scalar default: max of out_datatype
out_min_clip, scalar default: out_min
out_max_clip, scalar default: out_max
scale Boolean default: TRUE

]

Special types:

Datatype = {U_8, S_16, U_16, S_32, FLOAT }

See full explanation in the Read_band[] entry.

All arguments without defaults are required. Argument names are mandatory. The convert function converts image data into the specified datatype. If the datatype is higher precision than the input data, a direct casting of values is done (i.e., no scaling). If the datatype is of equal or lower precision than the input data, linear rescaling is done by default; disable this by setting scale to FALSE. The default scaling converts the minimum data value in the input to the minimum value of the target datatype, and it converts the maximum data value in the input to the maximum value of the target datatype. All points in between are linearly scaled. To change the default scaling, use in_min to specify explicitly the min endpoint in the input, use in_min_percent,to specify percentage offset from the min in the input, use out_min to specify the target endpoint, and use out_min_clip to specify the value to be used in the result when the input value falls below the min. The arguments specifying maximum values are defined analagously.


Depth[]

This is a convenience function. If frame F contains this function in its formula, the function returns the depth index of frame F. For example, for frame C2[[10]], the Depth function returns 10.


Frame

[

image, frame or image dataset
overlay, frame or image dataset
text frame, text dataset, or quoted string

]

All arguments are optional. A frame specified for the image component is shorthand for that frame's base image. A frame specified for the overlay component is shorthand for that frame's overlay image, or if none exists, for that frame's base image.

See Section 4.6 on overlays on how to set up the colormap used to display the overlay image. Up to 15 different colors (4-bits) for the overlay image is supported in hardware and these colors MUST be specified in the *.iss header file. It is currently not possible to interactively define the 15 colors or the image values associated with the colors. That is the image index must range from 0 to 15 (i.e. just the least 4-bits of the image pixel value is used for the overlay index with zero being reserved for transparent.


Invert

[

frame or image dataset

]

No argument name is used. The function returns a frame or image, depending on the type of the argument. The pixel data returned is the complement of the input data (255 - source data) for 8-bit datasets. Only 8-bit datasets are currently supported.


Log, Log10

[

frame or image dataset or scalar

]

One unnamed argument is accepted. The log function returns log base e. Both functions return 0.0 for input values less than or equal to 0.0 .


Nav

[

name, quoted string
min_lat, scalar lower left corner
min_lon, scalar lower left corner
max_lat, scalar upper right corner
max_lon, scalar upper right corner
xscale, scalar default: 1.0
yscale, scalar default: 1.0
xpos, scalar normalized position, default: 0.5
ypos scalar normalized position, default: 0.5

]

All arguments without defaults are required. Argument names are mandatory. The navigation function constructs a Navigation Dataset using an internal representation based on the proj package (USGS). Currently supported projections are those which are are defined as both forward and inverse projections in proj. (See the proj User's Manual, USGS Open File Report 90-284.) Scale and position arguments refer to the application of a navigation onto an image (see the Remap[] operator). Setting xscale to 0.5 for example, will position the min and max points to cover half of an image's pixels in the xdimension; the default positions put this coverage at the center of the resulting image; by setting both positions to 0.25, one could center the navigation in the lower left corner of the resulting image.


Power

[

frame or image dataset or scalar,
frame or image dataset or scalar

]

Two unnamed arguments are required. The power function returns a scalar if both arguments are scalars; otherwise the result contains an image equal to the first argument raised to the value of the second argument.


Read

[

filename quoted string default: ""
interleave quoted string default: "none"

]

Read[] is used for reading generic image types. These types include PNM, SGI, JPEG, GIF, and TIFF. Requires a filename argument which can either be a filename or URL. Optional interleave argument can be either "none" or "pixel_rgb". For remote file reads the path is specified using a URL such as HTTP or FTP.

Example: Read[filename->"http://rsd.gsfc.nasa.gov/GOES-8/4km/vis/latest.jpg", interleave->"none"]

Additionally, authenticated FTP is supported within iiss:
Read[filename->"ftp://user:password@rsd.gsfc.nasa.gov/pub/GOES-8/4km/vis/latest.jpg", interleave->"pixel_rgb"]
where user is the FTP username and password is the FTP password for rsd.gsfc.nasa.gov.

NOTE: While the generic read panel is used for reading MPEG and VSLCCA sequences, the actual operators used are Read_MPEG[] and Read_VSLCCA--not Read[]. See Read_MPEG[] and Read_VSLCCA[].

Interleave options for GIF: GIF images are inherently color-indexed images. For this reason, if the interleave option is "none" while reading a GIF, it will be installed as one channel image with the colormap available from the display panel. The colormap is automatically added to the colormap pool, but requires the user to manually select the correct colormap in the display panel. For the case of Read[] with interleave->"pixel_rgb", the GIF is converted to a 24-bit pixel interleave image.


Read_band

[

filename, quoted string default ""
datatype, Datatype # bytes default: 0
flip, Boolean default: FALSE
rotate, {0, 90, 180, 270} default: 0
header_size, int # bytes default: 0
src_xdim, int # pixels default: 512
src_ydim, int # pixels default: 512
frame_index_in_file, int default: 1
bands_per_frame, int default: 1
band_index_in_frame, int default: 1
bytes_between_bands int # bytes default: 0

]

Additional parameters that will be made available include:
roi_xdim
roi_ydim
roi_xoffset
roi_yoffset

Special types:

Datatype = {.U_8. S_16. U_16, S_32, FLOAT }

Token Meaning C equivalent Supported
S_8 signed 8 bit char
U_8 unsigned 8 bit unsigned char *
S_16 signed 16 bit short int *
U_16 unsigned 16 bit unsigned short int *
S_32 signed 32 bit int *
U_32 unsigned 32 bit unsigned int
S_64 signed 64 bit long
U_64 unsigned 64 bit unsigned long
FLOAT single precision floating pt float *
DOUBLE double precision floating pt double

Read_band[] reads data from a RAW (flat binary) format disk file. The file is assumed to be of a format wherein images are located in contiguous space (i.e. not interleaved with other images). Several contiguous images ("bands") may be considered grouped together into a "frame". For example, if a file contains a time series of datasets, and each dataset is comprised of n images, there would be n bands per frame, the band index could be assigned a value between 1 and n, and the frame index would correspond to the time step. Both band and frame indices start counting at 1, not 0. Flipping and rotation (by right angles) can be done during the read process, in that order. Rotation during reading does not require space for an additional copy of the image in RAM.

Read_band formulas can be constructed using the Read Panel. All options can be specified using the panel, except bands_per_frame, band_index_in_frame, and frame_index_in_file.


Read_HDFL2

[

filename quoted string default: ""
dataset_number int default: 1
datagroup_number int default: 1

]

Read_HDFL2[] reads data from a Level 2 HDF file (native format for Goddard Code 912), and returns it in a Frame data structure. The Level 2 format has a two-tiered organization, wherein datagroups (images) are collected into datasets. Text and navigation (lat/lon tag arrays) are included in the Frame which is returned.


Read_multiband

[

filename, quoted string default ""
datatype, Datatype # bytes default: 0
flip, Boolean default: FALSE
src_interleave, quoted string default: "pixel"
header_size, int # bytes default: 0
src_xdim, int # pixels default: 512
src_ydim, int # pixels default: 512
frame_index_in_file, int default: 1
src_num_channels, int default: 3
dest_num_channels, int default: 3
dest_one_channel int default: 1
dest_red_channel int default: 1
dest_green_channel int default: 2
dest_blue_channel int default: 3
dest_interleave quoted string default: "none"

]

Read_multiband[] reads raw data from a file that can have an arbitrary number of channels interleaved in one of three ways: pixel, row, or channel. src_num_channels is used to indicate how many channels are present in the file, and dest_num_channels indicates how many channels will be in the resulting frame. dest_num_channels must be either 1 or 3. If dest_num_channels is 3, the arguments dest_red_channel, dest_green_channel, and dest_blue_channel are used to indicate which channel of the file is to be used as the corresponding red, green, and blue channels of the resulting frame. In the case that dest_num_channel is 1, dest_one_channel is used to indicate which of the channels of the file is to be installed in the frame. Possible values for src_interleave are "pixel", "row", and "channel". dest_interleave determines how the resulting frame should be interleaved; options are "pixel_rgb" or "none".

Example: Read one channel of data from a file (in this case channel 3) with these attributes: 6 channels, row interleaved, dimension 7226x6524, flipped, and header size of 128 bytes.

Read_multiband[filename->"tm025033050392.lan",
               src_xdim->7226, 
               src_ydim->6524, src_num_channels->6, 
               dest_num_channels->1, src_interleave->"row", 
               dest_one_channel->3, 
               header_size->128, 
               flip->TRUE]

NOTE: Only the unsigned 8-bit datatype is currently supported. For an explanation of IISS datatypes, see the Read_band[] entry.

NOTE: Currently Read_multiband[] does not support src_interleave->"row" and src_interleave->"channel" in combination with dest_num_channels->3. If you need to create a RGB frame from a row or channel interleaved dataset, create a frame for each of the three channels using Read_multiband[] with dest_num_channels->1, and combine these with the RGB[] operator.


Read_MPEG

[

filename quoted string default: ""
frame_index_in_file int

]

Read_MPEG[] is used for reading a single frame from an MPEG file. Both filename and frame_index_in_file are required. The frame_index_in_file argument indicates which frame of the MPEG sequence to read into the current frame. In order to read an entire MPEG sequence into a cell, use the generic Read Panel. This will construct a series of Read_MPEG[] formulas--one Read_MPEG[] for each frame in the mpeg file.


Read_text

[

filename, quoted string default: ""
offset, int # bytes default: 0
length int # bytes default: 0

]

The offset parameters indicates the number of bytes to skip.


Read_VSLCCA

[

filename quoted string default: ""
frame_index_in_file int

]

Read_VSLCCA[] is used for reading a single frame from a VSLCCA file. Both filename and frame_index_in_file are required. The frame_index_in_file argument indicates which frame of the VSLCCA sequence to read into the current frame. In order to read an entireVSLCCA sequence into a cell, use the generic Read Panel. This will construct a series of Read_VSLCCA[] formulas--one Read_VSLCCA[] for each frame in the vslcca file.


Remap

[

input, Frame with navigation
projection, Navigation Dataset or Frame with navigation,
xdim, int
ydim int

]

All arguments are required. Argument names are mandatory. The remap function reprojects the image from the input frame into the specified projection. The resulting image is generated to be of the specified dimensions.


RGB

[

red, frame or image dataset
green, frame or image dataset
blue, frame or image dataset
interleave quoted string default: "none"

]

All arguments without defaults are required. Argument names are optional, if the order matches that given. A frame argument is interpreted as follows: if the frame is one-channel, the base image dataset is used; if the frame is three-channel, the channel which matches the argument is used (e.g. red->A1[[1]] uses the red dataset from A1[[1]]). Interleaving has been implemented facilitate fast interactive display; if interleave is set to "pixel_rgb", the image data will be pixel interleaved. This results in quick roam and zoom performance, but not all formula operators are currently equipped to operate over interleaved data -- use interleaved data cautiously, or with a sense of humor. Note that a frame that interleaves data from other frames (e.g. A=RGB[X,Y,Z,"pixel_rgb"]) costs extra memory for storing the interleaved version of the data.


Roi

[

data, frame or image dataset,
xdim, int
ydim, int
xoffset, int from the left; default: 0
yoffset int from the bottom; default: 0

]

All arguments without defaults are required. Argument names are optional, if the order matches that given. Roi extracts a subimage from the input data.


Row[]

This is a convenience function. If frame F contains this function in its formula, the function returns the row index of frame F. For example, for frame C2[[10]], the Row function returns the value 3.


Surface

[

height, frame or image dataset
image frame or image dataset

]

The height argument is required. Argument names are optional, if the order matches that given. A frame argument submitted as the height is interpreted as follows: if the frame is a Surface frame, the height field of that frame is referenced; otherwise if the frame is one-channel, the base image dataset is used as the height field; if the frame is three-channel, the red channel dataset is used as the height field. A frame argument submitted as the image is interpreted as follows: if the frame is one-channel, the base image dataset is used to produce a one-channel Surface Frame; if the frame is three-channel, the base image dataset is used to produce a three-channel Surface Frame. If no image is provided, the surface will be rendered only as a gray surface.

Current evaluation methods for one-channel Surface Frames result in colorization based on the colormap which was associated with the Frame at the time of evaluation. If the colormap of such a frame is changed, the user must currently re-evaluate the frame to trigger a revised colorization.


Threshold

[

data, frame or image dataset
lower, scalar default: 128
upper, scalar default: 255
value scalar default: 255

]

Data is the required argument; argument names are optional, if the order matches that given. The function returns a frame or image, depending on the type of the data argument. The pixel data returned is a binary image, with pixels set to 0 and the scalar argument "value", based on the following: a pixel is set to the specified non-zero value if (1) only the lower argument is given and the input pixel value is larger than the lower threshold, (2) only the upper argument is given and the input pixel value is less than the upper threshold, (3) both thresholds are given and the input pixel value is between those thresholds, or (4) both threshold are given and they are both equal to the input pixel value. (See Khoros documentation.)