The "iarray" Package

These routines provide a simple interface to the recursive, heirarchical data structure supported in Karma, when only n-dimensional data is to be represented.

Library: karma
Link With: -lkarma

Functions

iarray_num_dim	Get number of dimensions in an Intelligent Array
iarray_type	Get type of data in an Intelligent Array
iarray_value_name	Get name of data in an Intelligent Array
iarray_register_destroy_func	Register destroy function for an Intelligent Array
iarray_get_image_from_multi	Get an image from a Karma data structure.
iarray_get_movie_from_multi	Get a movie from a Karma data structure.
iarray_read_nD	Read in a Karma arrayfile and yield an "Intelligent Array".
iarray_write	Write an "Intelligent Array" in the Karma data format.
iarray_create	Create an Intelligent Array.
iarray_get_from_multi_array	Create an Intelligent Array from a Karma data structure.
iarray_dealloc	Deallocate an Intelligent Array.
iarray_put_named_value	Attach a data value to an Intelligent Array.
iarray_put_named_string	Attach a string to an Intelligent Array.
iarray_get_named_value	Get attached data from an Intelligent Array.
iarray_get_named_string	Get attached string from an Intelligent Array.
iarray_copy_data	Copy data between Intelligent Arrays.
iarray_get_sub_array_2D	Create a 2-dimensional alias Intelligent Array.
iarray_get_2D_slice_from_3D	Create a 2-dimensional Intelligent Array alias from a slice.
iarray_dim_length	Get length of a dimension in an Intelligent Array.
iarray_get_restrictions	Get restriction information.
iarray_fill	Fill an Intelligent Array with a single value.
iarray_min_max	Determine the minimum and maximum value of an Intelligent Array.
iarray_scale_and_offset	Scale and offset an Intelligent Array.
iarray_add_and_scale	Add Intelligent Arrays and scale.
iarray_sub_and_scale	Subtract Intelligent Arrays and scale.
iarray_dim_name	Get dimension name in an Intelligent Array.
iarray_remap_torus	Remap Intelligent Array into a torus.
iarray_set_world_coords	Set the world co-ordinates of an Intelligent Array dimension.
iarray_get_world_coords	Get the world co-ordinates of an Intelligent Array dimension.
iarray_get_dim_desc	Get a dimension descriptor from an Intelligent Array.
iarray_compute_histogram	Compute a histogram of an "Intelligent Array".
iarray_dim_index	This routine will find the index of a named dimension.
iarray_get_data_scaling	Get the scale and offset for data in an Intelligent Array.
iarray_set_data_scaling	Set the scale and offset for data in an Intelligent Array.
iarray_write_mono_ps	Write an Intelligent Array as monochrome PostScript.
iarray_write_pseudocolour_ps	Write an Intelligent Array as PseudoColour PostScript.
iarray_write_rgb_ps	Write an Intelligent Array as TrueColour PostScript.
iarray_create_1D	Create a 1-dimensional Intelligent Array.
iarray_create_2D	Create a 2-dimensional Intelligent Array.
iarray_create_3D	Create a 3-dimensional Intelligent Array.
iarray_create_4D	Create a 4-dimensional Intelligent Array.
iarray_put_float	Attach a float data value to an Intelligent Array.
iarray_put_int	Attach an integer data value to an Intelligent Array.
iarray_get_float	Get attached float from an Intelligent Array.
iarray_get_int	Get attached integer from an Intelligent Array.
iarray_fill_float	Fill an Intelligent Array with a single float value.
iarray_fill_int	Fill an Intelligent Array with a single integer value.
iarray_min_max_float	Determine the minimum and maximum value of an Intelligent Array.
iarray_min_max_int	Determine the minimum and maximum value of an Intelligent Array.
iarray_scale_and_offset_float	Scale and offset an Intelligent Array.
iarray_scale_and_offset_int	Scale and offset an Intelligent Array.

Prototype Functions

IARRAY_PROTO_destroy_func

Functions

unsigned int iarray_num_dim (iarray array)

Get number of dimensions in an Intelligent Array

Parameters:

array : The Intelligent Array.

Returns: The number of dimensions.
Multithreading Level: Unsafe

unsigned int iarray_type (iarray array)

Get type of data in an Intelligent Array

Parameters:

array : The Intelligent Array.

Returns: The type of the data in the array.
Multithreading Level: Unsafe

CONST char * iarray_value_name (iarray array)

Get name of data in an Intelligent Array

Parameters:

array : The Intelligent Array.

Returns: The name of the data in the array.
Multithreading Level: Unsafe

KCallbackFunc iarray_register_destroy_func (iarray array, void (*destroy_func) (iarray array, void *info), void *info)

Parameters:

array : The Intelligent Array.
destroy_func : The routine that is called when the array is destroyed. The prototype function is IARRAY_PROTO_destroy_func.
info : The arbitrary information pointer.

Returns: The name of the data in the array.
Multithreading Level: Unsafe

flag iarray_get_image_from_multi (multi_array *multi_desc, iarray *pseudo, iarray *red, iarray *green, iarray *blue, unsigned int *cmap_index)

This routine will find an image embedded in a Karma data structure. The image may be single-channel (PseudoColour) or it may be a TrueColour image (red, green and blue components).

Parameters:

multi_desc : The Karma data structure.
pseudo : If a single-channel image is found, the corresponding Intelligent Array is written here. If no single-channel image is found, NULL is written here.
red : If a TrueColour image is found, the red component Intelligent Array is written here. If no TrueColour image is found, NULL is written here.
green : If a TrueColour image is found, the green component Intelligent Array is written here. If no TrueColour image is found, NULL is written here.
blue : If a TrueColour image is found, the blue component Intelligent Array is written here. If no TrueColour image is found, NULL is written here.
cmap_index : If the image found is a single-channel image and the data structure has an associated RGBcolourmap, the index to the colourmap structure is written here. If no colourmap is found, the value written here is set to the number of general data structures in multi_desc.

Returns: TRUE on succes, else FALSE.
Multithreading Level: Unsafe

flag iarray_get_movie_from_multi (multi_array *multi_desc, iarray *pseudo, iarray *red, iarray *green, iarray *blue, unsigned int *cmap_index)

This routine will find a movie embedded in a Karma data structure. The movie may be single-channel (PseudoColour) or it may be a TrueColour movie (red, green and blue components).

Parameters:

multi_desc : The Karma data structure.
pseudo : If a single-channel movie is found, the corresponding Intelligent Array is written here. If no single-channel movie is found, NULL is written here.
red : If a TrueColour movie is found, the red component Intelligent Array is written here. If no TrueColour movie is found, NULL is written here.
green : If a TrueColour movie is found, the green component Intelligent Array is written here. If no TrueColour movie is found, NULL is written here.
blue : If a TrueColour movie is found, the blue component Intelligent Array is written here. If no TrueColour movie is found, NULL is written here.
cmap_index : If the movie found is a single-channel movie and the data structure has an associated RGBcolourmap, the index to the colourmap structure is written here. If no colourmap is found, the value written here is set to the number of general data structures in multi_desc.

Returns: TRUE on succes, else FALSE.
Multithreading Level: Unsafe

iarray iarray_read_nD (CONST char *object, flag cache, CONST char *arrayname, unsigned int num_dim, CONST char **dim_names, CONST char *elem_name, unsigned int mmap_option)

Read in a Karma arrayfile and yield an "Intelligent Array".

Parameters:

object : The name of the arrayfile to read. This parameter is passed directly to the dsxfr_get_multi routine. In order to understand the operation of this routine, the operation of the dsxfr_get_multi routine must be understood.
cache : This is passed directly to the dsxfr_get_multi routine. This controls whether disc arrayfiles are cached in memory for later use.
arrayname : The name of the general data structure in the arrayfile to search for. If this is NULL, the routine searches for the default name "Intelligent Array". If the arrayfile has only one general data structure, then this parameter is ignored.
num_dim : The routine searches for an n-dimensional array with a single atomic element at each point in multi-dimensional space. If this parameter is greater than 0, the routine will only return an array with the specified number of dimensions. If the value is 0, then the routine will return an n-dimensional array.
dim_names : If num_dim is not 0, then if this parameter is NULL, the routine will search for and return an array with the default dimension names (see iarray_create for a list of these) if more than one n-dimensional, single element array exists in the general data structure, or the only n-dimensional array with the specified number of dimensions. If the routine can't find an adequate default, it will not return an array. If num_dim is not 0, and this parameter points to an array of strings, then the routine will only return an array which matches the specified dimension names. The first name in the array of strings must be the highest order dimension.
elem_name : If this is NULL, the routine will ignore the element name of the array which is located, else it will insist on the array element name matching the specified name.
mmap_option : This is passed directly to the dsxfr_get_multi routine. This parameter controls the memory mapping of disc arrayfiles. If the data structure is likely to be subsequently modified, the value must be K_CH_MAP_NEVER, otherwise the data may be read-only memory mapped and writing to it will cause a segmentation fault.

Returns: A dynamically allocated intelligent array on success, else an error message is printed to the standard output and NULL is returned.
Multithreading Level: Unsafe

flag iarray_write (iarray array, CONST char *arrayfile)

Write an "Intelligent Array" in the Karma data format.

Parameters:

array : The "Intelligent Array".
arrayfile : The name of the arrayfile to write. See dsxfr_put_multi for details on the interpretation of this.

Returns: TRUE on success, else an error message is printed to the standard output and FALSE is returned.
Multithreading Level: Unsafe

iarray iarray_create (unsigned int type, unsigned int num_dim, CONST char **dim_names, CONST unsigned long *dim_lengths, CONST char *elem_name, iarray old_array)

This routine will create an "Intelligent Array", using the Karma general data structure format as the underlying data format. If the environment variable "IARRAY_ALLOC_DEBUG" is set to "TRUE" then the routine will print allocation debugging information.

Parameters:

type : The desired type of the data elements. See DS_KARMA_DATA_TYPES for a list of defined data types.
num_dim : The number of dimensions the array must have.
dim_names : The names of the dimensions. If this is NULL, the default names "Axis 0", "Axis 1", etc. are used.
dim_lengths : The lengths of the dimensions. The first entry in this array and the dim_lengths array refers to the most significant dimension (i.e. the dimension with the greatest stride in memory).
elem_name : The name of the element. If this is NULL, the default name "Data Value" is choosen.
old_array : Any auxilary information not representable with "Intelligent Arrays" which is to be included in the Karma data format is copied from here. If this is NULL, no auxilary information is copied.

Returns: A dynamically allocated intelligent array on success, else an error message is printed to the standard output and NULL is returned.
Multithreading Level: Unsafe

iarray iarray_get_from_multi_array (multi_array *multi_desc, CONST char *arrayname, unsigned int num_dim, CONST char **dim_names, CONST char *elem_name)

This routine will yield an "Intelligent Array" from a multi array Karma general data structure. The routine searches for a n-dimensional array with a single atomic element at each point in multi-dimensional space

Parameters:

multi_desc : The multi array header pointer. The attachment count is incremented on successful completion of this routine.
arrayname : The name of the general data structure in the arrayfile to search for. If this is NULL, the routine searches for the default name "Intelligent Array". If the arrayfile has only one general data structure, then this parameter is ignored.
num_dim : If greater than 0, the routine will only return an array with this many dimensions. If 0, then the routine will return an n-dimensional array.
dim_names : If num_dim is not 0, then if this NULL, the routine will search for and return an array with the default dimension names (see iarray_create for a list of these) if more than one n-dimensional, single element array exists in the general data structure, or the only n-dimensional array with the specified number of dimensions. If the routine can't find an adequate default, it will not return an array. If num_dim is not 0, and this points to an array of strings, then the routine will only return an array which matches the specified dimension names. The first name in the array of strings must be the highest order dimension.
elem_name : If NULL, the routine will ignore the element name of the array which is located, else it will insist on the array element name matching this name.

Returns: A dynamically allocated intelligent array on success, else an error message is printed to the standard output and NULL is returned.
Multithreading Level: Unsafe

void iarray_dealloc (iarray array)

This routine will deallocate an "Intelligent Array". If the environment variable "IARRAY_ALLOC_DEBUG" is set to "TRUE" then the routine will print deallocation debugging information.

Parameters:

array : The Intelligent Array.

Returns: Nothing.
Multithreading Level: Unsafe

flag iarray_put_named_value (iarray array, CONST char *name, unsigned int type, double value[2])

This routine will add a unique named value to the underlying Karma general data structure of an "Intelligent Array".

Parameters:

array : The Intelligent Array.
name : The name of the element to add.
type : The type of the data which is to be written.
value : The value of the data.

Returns: TRUE on success, else FALSE.
Multithreading Level: Unsafe

flag iarray_put_named_string (iarray array, CONST char *name, char *string)

This routine will add a unique named string to the underlying Karma general data structure of an "Intelligent Array".

Parameters:

array : The Intelligent Array.
name : The name of the element to add.
string : The string data.

Returns: TRUE on success, else FALSE.
Multithreading Level: Unsafe

flag iarray_get_named_value (iarray array, CONST char *name, unsigned int *type, double value[2])

This routine will get a unique named value from the underlying Karma general data structure of an "Intelligent Array".

Parameters:

array : The Intelligent Array.
name : The name of the element.
type : The type of the input data found will be written here. If this is NULL, nothing is written here.
value : The value of the converted data will be written here.

Returns: TRUE on success, else FALSE.
Multithreading Level: Unsafe

char * iarray_get_named_string (iarray array, CONST char *name)

This routine will get a unique named string from the underlying Karma general data structure of an "Intelligent Array".

Parameters:

array : The Intelligent Array.
name : The name of the element.

Returns: A pointer to a dynamically allocated copy of the string on success, else NULL.
Multithreading Level: Unsafe

flag iarray_copy_data (iarray output, iarray input, flag magnitude)

This routine will copy data from one "Intelligent Array" to another. The sizes of the two arrays must be identical. The routine can deal with the types of the two arrays being different

Parameters:

output : The output Intelligent Array.
input : The input Intelligent Array.
magnitude : If TRUE then when converting from a complex array to a real array, the magnitude of the complex data is taken, else the real component is copied.

Returns: TRUE on success, else FALSE.
Multithreading Level: Unsafe
Note:

When converting from a real array to a complex data array, the imaginary components are set to zero.

iarray iarray_get_sub_array_2D (iarray array, int starty, int startx, unsigned int ylen, unsigned int xlen)

This routine will create an "Intelligent Array" which is an alias or a sub-array of another "Intelligent Array". Subsequent modification of the alias array will modify the data of the original array. Sub-arrays may be created from other sub-arrays. The attachment count of the underlying multi_array data structure is incremented on successful completion.

Parameters:

array : The original array.
starty : The starting y (row) index in the original array corresponding to the first row of the alias array.
startx : The starting x (column) index in the original array corresponding to the first column of the alias array.
ylen : The number of y co-ordinates (rows) in the alias array.
xlen : The number of x co-ordinates (columns) in the alias array.

Returns: A dynamically allocated intelligent array on success, else NULL.
Multithreading Level: Unsafe
Note:

Sub-arrays cannot be saved to disc.

iarray iarray_get_2D_slice_from_3D (iarray cube, unsigned int ydim, unsigned int xdim, unsigned int slice_pos)

This routine will create a 2-D "Intelligent Array" which is an alias of an arbitrary slice of a 3-D array.

Parameters:

cube : The input 3-D array.
ydim : The dimension in the 3-D array which will become the y dimension (most significant) of the output array.
xdim : The dimension in the 3-D array which will become the x dimension (least significant) of the output array.
slice_pos : The position of the slice along the unspecified (remaining) dimension in the 3-D array.

Returns: A dynamically allocated intelligent array on success, else NULL.
Multithreading Level: Unsafe
Note:

Alias arrays cannot be saved to disc.

unsigned long iarray_dim_length (iarray array, unsigned int index)

Get length of a dimension in an Intelligent Array.

Parameters:

array : The Intelligent Array.
index : The index of the dimension.

Returns: The length of the specified dimension.
Multithreading Level: Unsafe

unsigned int iarray_get_restrictions (iarray array, char ***restr_names, double **restr_values)

This routine will get any associated restrictions for an Intelligent Array. The routine will dynamically allocate space for the restriction data, which must be externally freed.

Parameters:

array : The Intelligent Array.
restr_names : The array of pointers to restrictions names will be written here.
restr_values : The array of restriction values will be written here.

Returns: The number of restrictions. This may be 0.
Multithreading Level: Unsafe

flag iarray_fill (iarray array, double value[2])

Fill an Intelligent Array with a single value.

Parameters:

array : The Intelligent Array.
value : The fill value.

Returns: TRUE on success, else FALSE.
Multithreading Level: Unsafe

flag iarray_min_max (iarray array, unsigned int conv_type, double *min, double *max)

Determine the minimum and maximum value of an Intelligent Array.

Parameters:

array : The Intelligent Array.
conv_type : The conversion type to use for complex numbers. This is ignored if the array is not complex. See DS_COMPLEX_CONVERSIONS for legal values.
min : The routine will write the minimum value here.
max : The routine will write the maximum value here.

Returns: TRUE on success, else FALSE.
Multithreading Level: Unsafe.

flag iarray_scale_and_offset (iarray out, iarray inp, double scale[2], double offset[2], flag magnitude)

This routine will perform a scale and offset on every element in an "Intelligent Array" (output = input * scale + offset).

Parameters:

out : The output Intelligent Array.
inp : The input Intelligent Array.
scale : The complex scale value.
offset : The complex offset value.
magnitude : If TRUE and converting from a complex to a real array, the magnitude of the complex data (after scale and offset have been applied) is used, else the real component of the complex scaled data is used.

Returns: TRUE on success, else FALSE.
Multithreading Level: Unsafe
Note:

The input and output arrays MUST be the same size (though not necessarily the same type).
When converting from a real to a complex array, the imaginary component of the output array is set to 0.

flag iarray_add_and_scale (iarray out, iarray inp1, iarray inp2, double scale[2], flag magnitude)

This routine will add two "Intelligent Array" to each other and scales the result. The sizes of the two input arrays and the output must be identical. The routine performs the following computation: OUT = INP1 + INP2 * scale The routine will automatically perform type conversions if necessary.

Parameters:

out : The output Intelligent Array.
inp1 : The first input Intelligent Array.
inp2 : The second input Intelligent Array.
scale : The complex scale value.
magnitude : If TRUE then when converting from a complex to a real data type, the magnitude is taken, else the real component is copied.

Returns: TRUE on success, else FALSE.
Multithreading Level: Unsafe
Note:

When converting from a real to a complex data type, the imaginary component is set to zero.

flag iarray_sub_and_scale (iarray out, iarray inp1, iarray inp2, double scale[2], flag magnitude)

This routine will subtract two "Intelligent Array" from each other and scales the result. The sizes of the two input arrays and the output must be identical. The routine performs the following computation: OUT = INP1 - INP2 * scale The routine will automatically perform type conversions if necessary.

Parameters:

out : The output Intelligent Array.
inp1 : The first input Intelligent Array.
inp2 : The second input Intelligent Array.
scale : The complex scale value.
magnitude : If TRUE then when converting from a complex to a real data type, the magnitude is taken, else the real component is copied.

Returns: TRUE on success, else FALSE.
Multithreading Level: Unsafe
Note:

When converting from a real to a complex data type, the imaginary component is set to zero.

CONST char * iarray_dim_name (iarray array, unsigned int index)

This routine will get the name of a specified dimension in a simple, n-dimensional array.

Parameters:

array : The Intelligent Array.
index : The index of the dimension.

Returns: A pointer to the name of the specified dimension.
Multithreading Level: Unsafe

void iarray_remap_torus (iarray array, unsigned int boundary_width)

This routine will remap an N-dimensional "Intelligent Array" to a pseudo-toroidal array.

Parameters:

array : The Intelligent Array.
boundary_width : The width of the array boundary within which the array appears to be toroidal.

Returns: Nothing.
Multithreading Level: Unsafe

void iarray_set_world_coords (iarray array, unsigned int index, double first, double last)

Set the world co-ordinates of an Intelligent Array dimension.

Parameters:

array : The Intelligent Array.
index : The index of the dimension.
first : The first real world co-ordinate.
last : The last real world co-ordinate.

Returns: Nothing.
Multithreading Level: Unsafe

void iarray_get_world_coords (iarray array, unsigned int index, double *first, double *last)

Get the world co-ordinates of an Intelligent Array dimension.

Parameters:

array : The Intelligent Array.
index : The index of the dimension.
first : The first real world co-ordinate is written here.
last : The last real world co-ordinate is written here.

Returns: Nothing.
Multithreading Level: Unsafe

dim_desc * iarray_get_dim_desc (iarray array, unsigned int index)

Get a dimension descriptor from an Intelligent Array.

Parameters:

array : The Intelligent Array.
index : The index of the dimension.

Returns: A pointer to the dimension descriptor.
Multithreading Level: Unsafe

flag iarray_compute_histogram (iarray array, unsigned int conv_type, double min, double max, unsigned long num_bins, unsigned long *histogram_array, unsigned long *histogram_peak, unsigned long *histogram_mode)

Compute a histogram of an "Intelligent Array".

Parameters:

array : The array.
conv_type : The conversion type to use for complex numbers. See DS_COMPLEX_CONVERSIONS for legal values. CONV_CtoR_ENVELOPE is not legal.
min : Data values below this will be ignored.
max : Data values above this will be ignored.
num_bins : The number of histogram bins.
histogram_array : A pointer to the histogram array. The values in this array are updated, and hence must be initialised externally.
histogram_peak : The peak of the histogram is written here. This value is updated, and hence must be externally initialised to 0.
histogram_mode : The mode of the histogram (index value of the peak) will be written here. This value is updated, and hence must be externally initialised to 0.

Returns: TRUE on success, else FALSE.
Multithreading Level: Unsafe.

unsigned int iarray_dim_index (iarray array, CONST char *name)

This routine will find the index of a named dimension.

Parameters:

array : The array.
name : The name of the dimension.

Returns: The dimension index if found, else the number of dimension in the array is returned.
Multithreading Level: Unsafe

flag iarray_get_data_scaling (iarray array, double *scale, double *offset)

This routine will determine the scale and offset for data in an Intelligent Array. This may be important when a floating-point array has been converted to an integer array to save space. Scaling information should be attached to the array so that the original data values may be reconstructed (aside from quantisation effects). The following expression may be used to convert scaled values to real values: (output = input * scale + offset). The scaling and offset values should previously have been attached to the Intelligent Array using the iarray_set_data_scaling routine.

Parameters:

array : The array.
scale : The scaling value will be written here. The name of the scaling value is constructed by appending "__SCALE" to the array value name (see iarray_get_value_name). If no scaling value is found, 1.0 is written here.
offset : The offset value will be written here. The name of the offset value is constructed by appending "__OFFSET" to the array value name (see iarray_get_value_name). If no offset value is found, 0.0 is written here.

Returns: TRUE if either the scaling or offset value were found, else FALSE
Multithreading Level: Unsafe

flag iarray_set_data_scaling (iarray array, double scale, double offset)

This routine will set the scale and offset for data in an Intelligent Array. This may be important when a floating-point array has been converted to an integer array to save space. The scaling information will be attached to the array so that the original data values may be reconstructed (aside from quantisation effects). The following expression may be used to convert scaled values to real values: (output = input * scale + offset).

Parameters:

array : The array.
scale : The scaling value. The name of the scaling value is constructed by appending "__SCALE" to the array value name (see iarray_get_value_name)
offset : The offset value. The name of the offset value is constructed by appending "__OFFSET" to the array value name(see iarray_get_value_name)

Returns: TRUE if the scaling information is different from what was already attached to the array, else FALSE.
Multithreading Level: Unsafe

flag iarray_write_mono_ps (iarray image, PostScriptPage pspage, double xstart, double ystart, double xend, double yend, flag iscale)

This routine will convert a 2-dimensional Intelligent Array to monochrome PostScript. The routine does NOT write PostScript headers or tails.

Parameters:

image : The Intelligent Array.
pspage : The PostScriptPage object.
xstart : The x starting point (scaled from 0.0 to 1.0).
ystart : The y starting point (scaled from 0.0 to 1.0).
xend : The x ending point (scaled from 0.0 to 1.0).
yend : The y ending point (scaled from 0.0 to 1.0).
iscale : If FALSE and the input Intelligent Array is of type K_UBYTE the images values will be unscaled prior to PostScript conversion (0 = black, 255 = white), otherwise (min = black, max = white).

Returns: TRUE on success, else FALSE.
Multithreading Level: Unsafe

flag iarray_write_pseudocolour_ps (iarray image, PostScriptPage pspage, double xstart, double ystart, double xend, double yend, unsigned short *cmap,unsigned int cmap_size)

This routine will convert a 2-dimensional Intelligent Array to colour PostScript. The routine does NOT write PostScript headers or tails.

Parameters:

image : The Intelligent Array.
pspage : The PostScriptPage object.
xstart : The x starting point (scaled from 0.0 to 1.0).
ystart : The y starting point (scaled from 0.0 to 1.0).
xend : The x ending point (scaled from 0.0 to 1.0).
yend : The y ending point (scaled from 0.0 to 1.0).
cmap : The colourmap. This must be the same format as returned by ds_cmap_find_colourmap.
cmap_size : The size of the colourmap. The maximum size is 256.

Returns: TRUE on success, else FALSE.
Multithreading Level: Unsafe

flag iarray_write_rgb_ps (iarray image_red, iarray image_green, iarray image_blue, PostScriptPage pspage, double xstart, double ystart, double xend, double yend)

This routine will convert three 2-dimensional Intelligent Arrays to colour PostScript. The routine does NOT write PostScript headers or tails.

Parameters:

image_red : The Intelligent Array containing the red image component.
image_green : The Intelligent Array containing the green image component.
image_blue : The Intelligent Array containing the blue image component.
pspage : The PostScriptPage object.
xstart : The x starting point (scaled from 0.0 to 1.0).
ystart : The y starting point (scaled from 0.0 to 1.0).
xend : The x ending point (scaled from 0.0 to 1.0).
yend : The y ending point (scaled from 0.0 to 1.0).
cmap : The colourmap. This must be the same format as returned by ds_cmap_find_colourmap.
cmap_size : The size of the colourmap. The maximum size is 256.

Returns: TRUE on success, else FALSE.
Multithreading Level: Unsafe
Note:

Each of these Intelligent Arrays must be of type K_UBYTE.

iarray iarray_create_1D (unsigned long xlen, unsigned int type)

This routine will create a 1-dimensional "Intelligent Array", using the Karma general data structure format as the underlying data format

Parameters:

xlen : The length of the dimension. The name of the dimension will be the default: "Axis 0".
type : The type of the data. See DS_KARMA_DATA_TYPES for a list of defined data types.

Returns: A dynamically allocated intelligent array on success, else NULL.
Multithreading Level: Unsafe
Note:

The name of the element will be the default name: "Intensity".

iarray iarray_create_2D (unsigned long ylen, unsigned long xlen, unsigned int type)

This routine will create a 2-dimensional "Intelligent Array", using the Karma general data structure format as the underlying data format

Parameters:

ylen : The length of the most significant dimension (ie. the dimension with the greatest stride in memory.
xlen : The length of the least significant dimension.
type : The type of the data. See DS_KARMA_DATA_TYPES for a list of defined data types.

Returns: A dynamically allocated intelligent array on success, else NULL.
Multithreading Level: Unsafe
Note:

The names of the dimensions will be the defaults: "Axis 0" and "Axis 1", respectively.
The name of the element will be the default name: "Intensity".

iarray iarray_create_3D (unsigned long zlen, unsigned long ylen, unsigned long xlen, unsigned int type)

This routine will create a 3-dimensional "Intelligent Array", using the Karma general data structure format as the underlying data format

Parameters:

zlen : The length of the most significant dimension (ie. the dimension with the greatest stride in memory).
ylen : The length of the middle dimension.
xlen : The length of the least significant dimension.
type : The type of the data. See DS_KARMA_DATA_TYPES for a list of defined data types.

Returns: A dynamically allocated intelligent array on success, else NULL.
Multithreading Level: Unsafe
Note:

The names of the dimensions will be the defaults: "Axis 0", "Axis 1" and "Axis 2", respectively.
The name of the element will be the default name: "Intensity".

iarray iarray_create_4D (unsigned long zlen, unsigned long ylen, unsigned long xlen, unsigned int wlen, unsigned int type)

This routine will create a 4-dimensional "Intelligent Array", using the Karma general data structure format as the underlying data format

Parameters:

zlen : The length of the most significant dimension (ie. the dimension with the greatest stride in memory).
ylen : The length of the second most significant dimension.
xlen : The length of the second least significant dimension.
wlen : The length of the least significant dimension.
type : The type of the data. See DS_KARMA_DATA_TYPES for a list of defined data types.

Returns: A dynamically allocated intelligent array on success, else NULL.
Multithreading Level: Unsafe
Note:

The names of the dimensions will be the defaults: "Axis 0", "Axis 1", "Axis 2" and "Axis 3", respectively.
The name of the element will be the default name: "Intensity".

flag iarray_put_float (iarray array, CONST char *name, float value)

This routine will put a unique named float value into the underlying Karma general data structure of an "Intelligent Array".

Parameters:

array : The Intelligent Array.
name : The name of the element.
value : The value of the data.

Returns: TRUE on success, else FALSE.
Multithreading Level: Unsafe

flag iarray_put_int (iarray array, CONST char *name, int value)

This routine will put a unique named integer value into the underlying Karma general data structure of an "Intelligent Array".

Parameters:

array : The Intelligent Array.
name : The name of the element.
value : The value of the data.

Returns: TRUE on success, else FALSE.
Multithreading Level: Unsafe

float iarray_get_float (iarray array, CONST char *name)

This routine will get a unique named float value from the underlying Karma general data structure of an "Intelligent Array".

Parameters:

array : The Intelligent Array.
name : The name of the element.

Returns: The value on success, else the process is aborted on error.
Multithreading Level: Unsafe

int iarray_get_int (iarray array, CONST char *name)

This routine will get a unique named integer value from the underlying Karma general data structure of an "Intelligent Array".

Parameters:

array : The Intelligent Array.
name : The name of the element.

Returns: The value on success, else the process is aborted on error.
Multithreading Level: Unsafe

flag iarray_fill_float (iarray array, float value)

Fill an Intelligent Array with a single float value.

Parameters:

array : The Intelligent Array.
value : The fill value.

Returns: TRUE on success, else FALSE.
Multithreading Level: Unsafe
Note:

If filling a complex array, both the real and imaginary components are filled with the fill value.

flag iarray_fill_int (iarray array, int value)

Fill an Intelligent Array with a single integer value.

Parameters:

array : The Intelligent Array.
value : The fill value.

Returns: TRUE on success, else FALSE.
Multithreading Level: Unsafe
Note:

If filling a complex array, both the real and imaginary components are filled with the fill value.

flag iarray_min_max_float (iarray array, float *min, float *max)

Determine the minimum and maximum value of an Intelligent Array.

Parameters:

array : The Intelligent Array.
min : The routine will write the minimum value here.
max : The routine will write the maximum value here.

Returns: TRUE on success, else FALSE.
Multithreading Level: Unsafe.
Note:

If the array is a complex array, then the routine computes the minimum and maximum magnitudes.

flag iarray_min_max_int (iarray array, int *min, int *max)

Determine the minimum and maximum value of an Intelligent Array.

Parameters:

array : The Intelligent Array.
min : The routine will write the minimum value here.
max : The routine will write the maximum value here.

Returns: TRUE on success, else FALSE.
Multithreading Level: Unsafe.
Note:

If the array is a complex array, then the routine computes the minimum and maximum magnitudes.

flag iarray_scale_and_offset_float (iarray out, iarray inp, float scale, float offset)

This routine will perform a scale and offset on every element in an "Intelligent Array" (output = input * scale + offset).

Parameters:

out : The output Intelligent Array.
inp : The input Intelligent Array.
scale : The complex scale value.
offset : The complex offset value.

Returns: TRUE on success, else FALSE.
Multithreading Level: Unsafe
Note:

The input and output arrays MUST be the same size (though not necessarily the same type).
When converting from a complex to a real array, the magnitude is scaled and offset.
When converting from a real to a complex array, the imaginary component of the output array is set to 0.

flag iarray_scale_and_offset_int (iarray out, iarray inp, int scale,int offset)

This routine will perform a scale and offset on every element in an "Intelligent Array" (output = input * scale + offset).

Parameters:

out : The output Intelligent Array.
inp : The input Intelligent Array.
scale : The complex scale value.
offset : The complex offset value.

Returns: TRUE on success, else FALSE.
Multithreading Level: Unsafe
Note:

The input and output arrays MUST be the same size (though not necessarily the same type).
When converting from a complex to a real array, the magnitude is scaled and offset.
When converting from a real to a complex array, the imaginary component of the output array is set to 0.

Prototype Functions

void IARRAY_PROTO_destroy_func (iarray array, void *info)

Parameters:

array The Intelligent Array. :
info A pointer to the arbitrary information. :

Returns: Nothing.
Multithreading Level: Unsafe

Contact: Richard Gooch
Web Development: Ariel Internet Services