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_contour	Extract contours from a 2-dimensional 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_get_nD_from_multi	Get a n-dimensional array 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_create2	Create an Intelligent Array.
iarray_get_from_multi_array	Create an Intelligent Array from a Karma data structure.
iarray_create_from_array_desc	Create an Intelligent Array from a preallocated nD array.
iarray_dealloc	Deallocate an Intelligent Array.
iarray_dealloc2	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_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_get_sub_array_3D	Create a 3-dimensional alias Intelligent Array.
iarray_get_3D_slice_from_4D	Create a 3-dimensional Intelligent Array alias from a slice.
iarray_remap_torus	Remap Intelligent Array into a torus.
iarray_dim_length	Get length of a dimension in an Intelligent Array.
iarray_dim_name	Get dimension name in an Intelligent Array.
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_get_restrictions	Get restriction information.
iarray_is_full_array	Test if iarray is the same size as the underlying array.
iarray_compare_sizes	Compare if two Intelligent Arrays are the same size.
iarray_copy_data	Copy data between Intelligent Arrays.
iarray_clear	Clear (set to zero) an Intelligent Array.
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_clip_scale_and_offset	Clip, scale and offset an Intelligent Array.
iarray_add_and_scale	Add Intelligent Arrays and scale.
iarray_add_and_scale2	Add Intelligent Arrays and scale.
iarray_sub_and_scale	Subtract Intelligent Arrays and scale.
iarray_multiply_divide	Multiply or divide Intelligent Arrays and scale.
iarray_compute_histogram	Compute a histogram of an "Intelligent Array".
iarray_sum	Determine the sum of an Intelligent Array.
iarray_matrix_multiply	Perform a matrix multiply.
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_get_data_range	Get the range of data in an Intelligent Array.
iarray_set_data_range	Set the range of data in an Intelligent Array.
iarray_format_value	Format a data value into a string.
iarray_create_from_template	Create an Intelligent Array from a template array.
iarray_create_from_template2	Create an Intelligent Array from a template array.
iarray_get_coordinate	Get a co-ordinate along a dimension.
iarray_set_dim_name	Change the name of a dimension of an Intelligent Array.
iarray_append_history_string	Add a history string to an Intelligent Array.
iarray_copy_named_element	Copy a named element from one Intelligent Array to another.
iarray_get_fits_axis	Get the FITS axis number of a dimension.
iarray_create_and_setup	Create an Intelligent Array and setup.
iarray_get_associated_wcs_astro	Get the KwcsAstro object associated with an Intelligent Array.
iarray_set_value_name	Change the data name of an Intelligent Array.
iarray_find_centroid	Find the centroid inside an ellipse.
iarray_copy_attached	Copy attached data from one Intelligent Array to another.
iarray_compare_grids_2D	Compare if two image slices have the same world co-ordinate grid.
iarray_get_beam_correction	Get the beam correction for an area in an array.
iarray_register_data_change	Notify data for Intelligent Array has changed.
iarray_get_values	Convert Intelligent Array data to double precision complex values
iarray_moment_compute	Compute the 0th and 1st moments along the Z axis of a cube.
iarray_moment_create	Create 2-D arrays to contain computed moment maps.
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_regrid_2D	Regrid an array by iterating over the output array.
iarray_regrid_3D	Regrid an array by iterating over the output array.
iarray_scroll	Scroll an Intelligent Array.
iarray_rect_to_polar	Transform an image from rectangular to polar co-ordinates.
iarray_transform_3D	Transform an array by iterating over the input array.
iarray_untransform_3D	Transform an array by iterating over the output array.
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_create_shm	Create an n-dimensional Intelligent Array in shared memory.
iarray_put_double	Attach a double precision data value to an 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_double	Get attached double float from 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_double	Fill an Intelligent Array with a double precision float value.
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.
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_multi_array	Get the multi_array for an Intelligent Array.
iarray_multi_index	Get the index of the Intelligent Array within the multi_array.
iarray_array_desc	Get the array_desc for an Intelligent Array.
iarray_arrayp	Get the array_pointer for an Intelligent Array.
iarray_register_data_change_func	Register data change function for an Intelligent Array.

Prototype Functions

iarray_PROTO_destroy_func

Functions

EXPERIMENTAL FUNCTION: subject to change without notice

void iarray_contour (iarray array, unsigned int num_levels, CONST double *contour_levels, uaddr structure_size, uaddr *buffer_sizes, double **x0_arr, double **y0_arr, double **x1_arr, double **y1_arr, uaddr *num_segments)

This routine will extract contours from a 2-dimensional Intelligent Array, producing a list of line segments that approximate the countours. The co-ordinates of the line segments are in linear world co-ordinates.

Parameters:

array : The array.
num_levels : The number of contour levels.
contour_levels : The array of contour levels.
structure_size : The size (in bytes) of the per-level data structure. The calling function is expected to pass pointers to various fields in the first structure. The fields are modified.
buffer_sizes : A pointer to the first co-ordinate buffer size field.
x0_arr : A pointer to the first x0 co-ordinate array field. The co-ordinate array may be internally reallocated.
y0_arr : A pointer to the first y0 co-ordinate array field. The co-ordinate array may be internally reallocated.
x1_arr : A pointer to the first x1 co-ordinate array field. The co-ordinate array may be internally reallocated.
y1_arr : A pointer to the first y1 co-ordinate array field. The co-ordinate array may be internally reallocated.
num_segments : A pointer to the first number of segments field.

Returns: Nothing.
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

EXPERIMENTAL FUNCTION: subject to change without notice

flag iarray_get_nD_from_multi (multi_array *multi_desc, CONST char *name, unsigned int num_dim, iarray *pseudo, iarray *red, iarray *green, iarray *blue, unsigned int *cmap_index)

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

Parameters:

multi_desc : The Karma data structure.
name : The name of the general data structure. This may be NULL.
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.
num_dim : The number of dimensions the array must have. Passing 0 will cause the programme to abort.
red : If a TrueColour array is found, the red component Intelligent Array is written here. If no TrueColour array is found, NULL is written here.
green : If a TrueColour array is found, the green component Intelligent Array is written here. If no TrueColour array is found, NULL is written here.
blue : If a TrueColour array is found, the blue component Intelligent Array is written here. If no TrueColour array is found, NULL is written here.
cmap_index : If the array found is a single-channel array 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_names 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

EXPERIMENTAL FUNCTION: subject to change without notice

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

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_names 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.
clear : If TRUE, the array is filled with zeros, otherwise the contents will be random.

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", and if that is not found, the first general data structure is used. 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

EXPERIMENTAL FUNCTION: subject to change without notice

iarray iarray_create_from_array_desc (array_desc *arr_desc, CONST array_pointer *arrayp, unsigned int elem_index)

Create an Intelligent Array from a preallocated nD array.

Parameters:

arr_desc : The array descriptor. This may be modified.
arrayp : The array data pointer. If this is NULL the array data is internally allocated.
elem_index : The index of the element in the array packet descriptor.

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

EXPERIMENTAL FUNCTION: subject to change without notice

void iarray_dealloc2 (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. If this is NULL, nothing is done.

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, CONST char *string)

This routine will addor update 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

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.

EXPERIMENTAL FUNCTION: subject to change without notice

iarray iarray_get_sub_array_3D (iarray array, int startz, int starty, int startx, unsigned int zlen, unsigned int ylen, unsigned int xlen)

Parameters:

array : The original array.
startz : The starting z (plane) index in the original array corresponding to the first plane of the alias 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.
zlen : The number of z co-ordinates (planes) in 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.

EXPERIMENTAL FUNCTION: subject to change without notice

iarray iarray_get_3D_slice_from_4D (iarray hcube, unsigned int zdim, unsigned int ydim, unsigned int xdim, unsigned int cube_pos)

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

Parameters:

hcube : The input 4-D array.
zdim : The dimension in the 4-D array which will become the z dimension (most significant) of the output array.
ydim : The dimension in the 4-D array which will become the y dimension of the output array.
xdim : The dimension in the 4-D array which will become the x dimension (least significant) of the output array.
cube_pos : The position of the slice along the unspecified (remaining) dimension in the 4-D array.

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

Alias arrays cannot be saved to disc.

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

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

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_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

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

EXPERIMENTAL FUNCTION: subject to change without notice

flag iarray_is_full_array (iarray array, flag *all_contiguous)

This routine will test if an Intelligent Array is the same size and dimensionality as the underlying array descriptor.

Parameters:

array : The Intelligent Array.
all_contiguous : TRUE is written here if all dimensions are contiguous, else FALSE is written here. This may be NULL. Nothing is written here if the array is not full size.

Returns: TRUE if the Intelligent Array is the same size, else FALSE.
Multithreading Level: Unsafe

EXPERIMENTAL FUNCTION: subject to change without notice

flag iarray_compare_sizes (iarray array1, iarray array2, flag message)

Compare if two Intelligent Arrays are the same size.

Parameters:

array1 : One of the Intelligent Arrays to compare.
array2 : The other Intelligent Array to compare.
message : If TRUE, explanatory messages are displayed.

Returns: TRUE of the number of dimensions and dimension lengths are the same, else FALSE.
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.

EXPERIMENTAL FUNCTION: subject to change without notice

flag iarray_clear (iarray array)

Clear (set to zero) an Intelligent Array.

Parameters:

array : The Intelligent Array.

Returns: TRUE on success, else FALSE.
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. A complex scale or offset value will not result in a complex output if the input is real.

EXPERIMENTAL FUNCTION: subject to change without notice

flag iarray_clip_scale_and_offset (iarray out, iarray inp, double scale, double offset, double lower_clip, double upper_clip, flag blank)

This routine will perform a clipping operation followed by a scale and offset on every element in an "Intelligent Array". The operation following the clipping is: (output = input * scale + offset).

Parameters:

out : The output Intelligent Array.
inp : The input Intelligent Array.
scale : The scale value.
offset : The offset value.
lower_clip : The input data is clipped so that no value is below this.
upper_clip : The input data is clipped so that no value is above this.
blank : If TRUE, clipped values are blanked.

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). Both arrays must be real.

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.

EXPERIMENTAL FUNCTION: subject to change without notice

flag iarray_add_and_scale2 (iarray out, iarray inp1, iarray inp2, double scale[2], double offset[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 + offset 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.
offset : The complex offset 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.

EXPERIMENTAL FUNCTION: subject to change without notice

flag iarray_multiply_divide (iarray out, iarray inp1, iarray inp2, flag multiply, double scale[2], double offset[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 op (INP2 * scale + offset) where op is the multiply or divide operation. 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.
offset : The complex offset 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_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.

flag iarray_sum (iarray array, double sum[2])

Determine the sum of an Intelligent Array.

Parameters:

array : The Intelligent Array.
sum : The routine will write the sum here.

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

EXPERIMENTAL FUNCTION: subject to change without notice

flag iarray_matrix_multiply (iarray out, iarray in1, iarray in2, flag thread)

Perform a matrix multiply.

Parameters:

out : The output array (matrix).
in1 : The first input array.
in2 : The second input array.
thread : If TRUE, the operation may be threaded, else it will not be.

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

Only double precision arrays are supported.

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_value_name). If no scaling value is found, 1.0 is written here. As a fallback, if the FITS-style "BSCALE" keyword is found and is appropriate, this is used.
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_value_name). If no offset value is found, 0.0 is written here. As a fallback, if the FITS-style "BZERO" keyword is found and is appropriate, this is used.

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

EXPERIMENTAL FUNCTION: subject to change without notice

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_value_name) If appropriate, the FITS-style "BSCALE" keyword is written instead.
offset : The offset value. The name of the offset value is constructed by appending "__OFFSET" to the array value name(see iarray_value_name) If appropriate, the FITS-style "BZERO" keyword is written instead.

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

EXPERIMENTAL FUNCTION: subject to change without notice

flag iarray_get_data_range (iarray array, double *minimum, double *maximum)

This routine will determine the range of data in an Intelligent Array. Range information should be attached to the header.

Parameters:

array : The array.
minimum : The minimum value will be written here. The name of the minimum value is constructed by appending "__MINIMUM" to the element name. If no minimum value is found, -TOOBIG is written here. As a fallback, if the FITS-style "DATAMIN" keyword is found and is appropriate, this is used.
maximum : The minimum value will be written here. The name of the minimum value is constructed by appending "__MINIMUM" to the element name. If no minimum value is found, TOOBIG is written here. As a fallback, if the FITS-style "DATAMAX" keyword is found and is appropriate, this is used.

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

EXPERIMENTAL FUNCTION: subject to change without notice

flag iarray_set_data_range (iarray array, double minimum, double maximum)

This routine will set the range of data in an Intelligent Array. The range information will be attached to the header.

Parameters:

array : The array.
minimum : The minimum value. The name of the minimum value is constructed by appending "__MINIMUM" to the array value name (see iarray_value_name). If appropriate, the FITS-style "DATAMIN" keyword is written instead.
maximum : The maximum value. The name of the maximum value is constructed by appending "__MAXIMUM" to the array value name (see iarray_value_name). If appropriate, the FITS-style "DATAMAX" keyword is written instead.

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

EXPERIMENTAL FUNCTION: subject to change without notice

void iarray_format_value (iarray array, char string[STRING_LENGTH], double value, double scale, double offset)

Format a data value into a string.

Parameters:

array : The Intelligent Array the value is associated with.
string : The string to write to.
value : The value to format.
scale : The scale value to apply to the data. If this is TOOBIG the routine uses the scale and offset attached to the array. See iarray_set_data_scaling for details.
offset : The offset to apply after scaling the data.

Returns: Nothing.
Multithreading Level: Unsafe

iarray iarray_create_from_template (iarray template_arr,unsigned int elem_type, flag copy_world_coords, flag copy_names, flag copy_aux_info)

This routine will create an Intelligent Array of a specified type using an existing Intelligent Array as the template for the size, dimensionality and other attributes.

Parameters:

template_arr : The template Intelligent Array.
elem_type : The element type for the new Intelligent Array.
copy_world_coords : If TRUE, the world co-ordinates for each dimension in the template array are copied, otherwise the defaults are used.
copy_names : If TRUE, the dimension names and the value name of the template array are copied, else the defaults are used.
copy_aux_info : If TRUE, auxilary information (attachments) in the template array is copied to the new array.

Returns: An Intelligent Array on success, else NULL.
Multithreading Level: Unsafe

EXPERIMENTAL FUNCTION: subject to change without notice

iarray iarray_create_from_template2 (iarray template_arr, unsigned int elem_type, flag copy_world_coords, flag copy_names, flag copy_aux_info, flag clear)

This routine will create an Intelligent Array of a specified type using an existing Intelligent Array as the template for the size, dimensionality and other attributes.

Parameters:

template_arr : The template Intelligent Array.
elem_type : The element type for the new Intelligent Array.
copy_world_coords : If TRUE, the world co-ordinates for each dimension in the template array are copied, otherwise the defaults are used.
copy_names : If TRUE, the dimension names and the value name of the template array are copied, else the defaults are used.
copy_aux_info : If TRUE, auxilary information (attachments) in the template array is copied to the new array.
clear : If TRUE, the array is filled with zeros, otherwise the contents will be random.

Returns: An Intelligent Array on success, else NULL.
Multithreading Level: Unsafe

double iarray_get_coordinate (iarray array, unsigned int dim_index, double coord_index)

Get a co-ordinate along a dimension.

Parameters:

array : The Intelligent Array.
dim_index : The dimension index.
coord_index : The co-ordinate index.

Returns: The co-ordinate on success, else TOOBIG.
Multithreading Level: Unsafe

void iarray_set_dim_name (iarray array, unsigned int index, CONST char *name, flag new_alloc)

Change the name of a dimension of an Intelligent Array.

Parameters:

array : The Intelligent Array.
index : The index of the dimension.
name : The new dimension name.
new_alloc : If TRUE, the routine will allocate a new copy of the dimension name, else it will copy the pointer (in which case the name must never be externally deallocated or changed).

Returns: Nothing.
Multithreading Level: Unsafe

flag iarray_append_history_string (iarray array, CONST char *string, flag new_alloc)

Add a history string to an Intelligent Array.

Parameters:

array : The Intelligent Array.
string : The history string to add.
new_alloc : If TRUE, the routine will allocate a new copy of the history string, else it will copy the pointer (in which case the string must never be externally deallocated or changed).

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

flag iarray_copy_named_element (iarray out, iarray in, CONST char *name, flag fail_if_not_found, flag fail_on_duplicate, flag replace)

Copy a named element from one Intelligent Array to another.

Parameters:

out : The output Intelligent Array.
in : The input Intelligent Array.
name : The name of the element to copy.
fail_if_not_found : If TRUE, the routine will fail if the element does not exist in the input packet.
fail_on_duplicate : If TRUE, the routine will fail if the element already exists in the output packet.
replace : If TRUE and the element already exists in the output packet, it is replaced.

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

unsigned int iarray_get_fits_axis (iarray array, unsigned int index)

Get the FITS axis number of a dimension.

Parameters:

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

Returns: The FITS axis number on success, else 0.
Multithreading Level: Unsafe

EXPERIMENTAL FUNCTION: subject to change without notice

flag iarray_create_and_setup (iarray *array, multi_array *multi_desc, flag inform, unsigned int num_dim, unsigned int required_type, double *min, double *max, flag discard_zero_range, KwcsAstro *ap)

This routine will attempt to guess the filetype of a file and in the file, converting to an Intelligent Array if possible. The routine then performs some simple checks and some other convenience functions.

Parameters:

array : The Intelligent Array is written here. An existing array pointed to by this is deallocated.
multi_desc : The multi_array descriptor. If this is NULL, any existing data is deallocated and no further action is taken.
inform : If TRUE, the routine displays some informative messages.
num_dim : The number of dimensions required. If this is 0, any number of dimensions is allowed.
required_type : The required data type. If this is NONE, then no type is required.
min : The minimum data value in the array is written here. If this is NULL nothing is written here.
max : The maximum data value in the array is written here. If this is NULL nothing is written here.
discard_zero_range : If TRUE, and the range of the data is zero, the routine fails.
ap : The KwcsAstro object is written here. This may be NULL.

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

EXPERIMENTAL FUNCTION: subject to change without notice

KwcsAstro iarray_get_associated_wcs_astro (iarray array)

Get the KwcsAstro object associated with an Intelligent Array.

Parameters:

array : The Intelligent Array.

Returns: The KwcsAstro object if associated, else NULL.
Multithreading Level: Unsafe

EXPERIMENTAL FUNCTION: subject to change without notice

void iarray_set_value_name (iarray array, CONST char *name, flag new_alloc)

Change the data name of an Intelligent Array.

Parameters:

array : The Intelligent Array.
name : The new data value name. If the is NULL, the programme will abort.
new_alloc : If TRUE, the routine will allocate a new copy of the value name, else it will copy the pointer (in which case the name must never be externally deallocated or changed).

Returns: Nothing.
Multithreading Level: Unsafe

EXPERIMENTAL FUNCTION: subject to change without notice

flag iarray_find_centroid (iarray array, double *background, flag *inverted, double *xpos, uaddr xradius, double *ypos, uaddr yradius)

This routine will search for the centroid of an object inside a specified ellipse.

Parameters:

array : The Intelligent Array.
inverted : If TRUE the algorithms should search for a minimum, rather than a maximum.
background : The background value is written here. This may be NULL.
inverted : The value TRUE will be written here if the image values are inverted (i.e. the object of interested is in a local minimum rather than a maximum).
xpos : The horizontal data pixel position. The original value must be a reasonable approximation. This is modified to the centroid position.
xradius : The horizontal radius of the ellipse.
ypos : The vertical data pixel position. The original value must be a reasonable approximation. This is modified to the centroid position.
yradius : The vertical radius of the ellipse.

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

(0.0, 0.0) corresponds to the centre of the first pixel.

EXPERIMENTAL FUNCTION: subject to change without notice

flag iarray_copy_attached (iarray output, iarray input, flag fail_on_duplicate, flag replace)

Copy attached data from one Intelligent Array to another.

Parameters:

output : The output Intelligent Array.
input : The input Intelligent Array.
fail_on_duplicate : If TRUE, the routine will fail if the element already exists in the output packet.
replace : If TRUE and the element already exists in the output packet, it is replaced.

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

EXPERIMENTAL FUNCTION: subject to change without notice

flag iarray_compare_grids_2D (iarray array1, unsigned int hdim1, unsigned int vdim1, iarray array2, unsigned int hdim2, unsigned int vdim2, flag *same)

Compare if two image slices have the same world co-ordinate grid.

Parameters:

array1 : The array containing the first image slice.
hdim1 : The horizontal dimension of the first image slice.
vdim1 : The vertical dimension of the first image slice.
array2 : The array containing the second image slice.
hdim2 : The horizontal dimension of the second image slice.
vdim2 : The vertical dimension of the second image slice.
same : TRUE is written here if the grids are the same, else FALSE is written here.

Returns: TRUE on success, else FALSE, indicating that comparison failed.
Multithreading Level: Unsafe

EXPERIMENTAL FUNCTION: subject to change without notice

double iarray_get_beam_correction (iarray array, unsigned int dim1, unsigned int dim2)

Get the beam correction for an area in an array.

Parameters:

array : The array.
dim1 : One of the dimensions.
dim2 : The other dimension.

Returns: The beam correction, if available, else TOOBIG.
Multithreading Level: Unsafe

EXPERIMENTAL FUNCTION: subject to change without notice

void iarray_register_data_change (iarray array, void *call_data)

Notify data for Intelligent Array has changed.

Parameters:

array : The array.
call_data : The call data.

Returns: Nothing.
Multithreading Level: Unsafe

EXPERIMENTAL FUNCTION: subject to change without notice

void iarray_get_values (iarray array, CONST uaddr *coords, double *values, flag *complex, unsigned int num_values)

This routine will convert many values along the least significant axis of an Intelligent Array to an array of double precision complex values.

Parameters:

array : The array.
coords : The co-ordinate position to start converting from. The length of this array must equal the number of dimensions in the Intelligent Array.
values : The data values will be written here. Must be a double boundary.
complex : If the data are a complex type, then the value of TRUE is written here, else the value FALSE is written here. If this is NULL, nothing is written here.
num_values : The number of data values to convert.

Returns: Nothing.
Multithreading Level: Safe.

EXPERIMENTAL FUNCTION: subject to change without notice

flag iarray_moment_compute (iarray mom0, iarray mom1, iarray cube, float lower_clip, float sum_clip, unsigned int moment1_algorithm, unsigned int start_z, unsigned int stop_z, float *mom0_min, float *mom0_max)

Compute the 0th and 1st moments along the Z axis of a cube.

Parameters:

mom0 : The 0th moment array.
mom1 : The 1st moment array.
cube : The cube.
lower_clip : Values in the cube lower than this value are not used in the computation of the moments.
sum_clip : Values in the 0th moment map lower than this value are not used in the computation of the 1st moment.
moment1_algorithm : The 1st moment algorithm.
start_z : The start channel.
stop_z : The stop channel.
mom0_min : The minimum value in the 0th moment image is written here.
mom0_max : The maximum value in the 0th moment image is written here.

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

EXPERIMENTAL FUNCTION: subject to change without notice

flag iarray_moment_create (iarray *mom0, iarray *mom1, iarray cube)

Create 2-D arrays to contain computed moment maps.

Parameters:

mom0 : The Intelligent Array for the 0th moment is written here.
mom1 : The Intelligent Array for the 1st moment is written here.
cube : The cube from which the moment maps are created.

Returns: TRUE on success, 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.

EXPERIMENTAL FUNCTION: subject to change without notice

flag iarray_regrid_2D (iarray out_arr, KwcsAstro out_ap, iarray in_arr, KwcsAstro in_ap, unsigned int sample_option, float *min, float *max, flag verbose)

Regrid an array by iterating over the output array.

Parameters:

out_arr : The output array. The new grid must already be defined.
out_ap : The output KwcsAstro object.
in_arr : The input array.
in_ap : The input KwcsAstro object.
sample_option : The sample option to use.
min : The minimum value is written here. This is updated. This may be NULL.
max : The maximum value is written here. This is updated. This may be NULL.
verbose : If TRUE, diagnostic messages are displayed.

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

The pair of axes in each array must correspond, otherwise no regridding is performed. Axes may be swapped and have different projections but different reference frames (for velocity axes) or equinoxes (for equatorial co-ordinates) are not permitted.

EXPERIMENTAL FUNCTION: subject to change without notice

flag iarray_regrid_3D (iarray out_arr, KwcsAstro out_ap, iarray in_arr, KwcsAstro in_ap, unsigned int sample_option, float *min, float *max, flag verbose)

Regrid an array by iterating over the output array.

Parameters:

out_arr : The output array. The new grid must already be defined.
out_ap : The output KwcsAstro object.
in_arr : The input array.
in_ap : The input KwcsAstro object.
sample_option : The sample option to use.
min : The minimum value is written here. This is updated. This may be NULL.
max : The maximum value is written here. This is updated. This may be NULL.
verbose : If TRUE, diagnostic messages are displayed.

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

EXPERIMENTAL FUNCTION: subject to change without notice

void iarray_scroll (iarray array, unsigned long num_to_scroll, unsigned int scroll_mode)

This routine will scroll "down" an array by a specified number of co-ordinates along the major dimension (dimension 0).

Parameters:

array : The Intelligent Array to scroll.
num_to_scroll : The number of co-ordinates to scroll by.
scroll_mode : The scroll mode.

Returns: Nothing.
Multithreading Level: Unsafe

EXPERIMENTAL FUNCTION: subject to change without notice

void iarray_rect_to_polar (iarray out, iarray in, double centre_x, double centre_y, double radius_major, double radius_minor, double rotation)

This routine will transform an input image with a rectangular co-ordinate system to an output image with a polar co-ordinate system. Lines of constant radius in the output image correspond to the points around an ellipse in the input image. The X axis in the output image will correspond to different radii bins, while the Y axis will correspond to different angle bins. The last X axis index will correspond to the outer ellipse.

Parameters:

out : The output 2D Intelligent Array of type K_FLOAT. The polar image is written here. This must be externally allocated.
in : The input 2D Intelligent Array of type K_FLOAT. This must contain the input rectangular image.
centre_x : The X centre of the new polar co-ordinate system in the input.
centre_y : The Y centre of the new polar co-ordinate system in the input.
radius_major : The radius of the major axis of the outer ellipse.
radius_minor : The radius of the minor axis of the outer ellipse.
rotation : The rotation of the ellipse, in degrees. An angle of 0 would mean the major axis is parallel to the input image X axis.

Returns: Nothing.
Multithreading Level: Unsafe

EXPERIMENTAL FUNCTION: subject to change without notice

flag iarray_transform_3D (iarray out_arr, KwcsAstro out_ap, iarray in_arr, KwcsAstro in_ap, void (*func) (void *info, unsigned long length, double *x, double *y, double *z), void *info)

Transform an array by iterating over the input array.

Parameters:

out_arr : The output array. The new grid must already be defined.
out_ap : The output KwcsAstro object.
in_arr : The input array.
in_ap : The input KwcsAstro object.
func : The function used to convert from input world co-ordinates to output world co-ordinates.
info : An arbitrary information pointer passed to func.

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

Aliasing artefacts may appear if the output grid resolution is too high. This is an inherent problem with forward transform algorithms. If an inverse co-ordinate transform function is available, then use iarray_untransform_3D instead, which avoids these artefacts.

EXPERIMENTAL FUNCTION: subject to change without notice

flag iarray_untransform_3D (iarray out_arr, KwcsAstro out_ap, iarray in_arr, KwcsAstro in_ap, void (*func) (void *info, unsigned long length, double *x, double *y, double *z), void *info)

Transform an array by iterating over the output array.

Parameters:

out_arr : The output array. The new grid must already be defined.
out_ap : The output KwcsAstro object.
in_arr : The input array.
in_ap : The input KwcsAstro object.
func : The function used to convert from output world co-ordinates to input world co-ordinates.
info : An arbitrary information pointer passed to func.

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

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".

EXPERIMENTAL FUNCTION: subject to change without notice

iarray iarray_create_shm (unsigned int type, unsigned int num_dim, CONST char **dim_names, CONST uaddr *dim_lengths, CONST char *elem_name, flag force)

Create an n-dimensional Intelligent Array in shared memory.

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_names 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.
force : If TRUE the routine will fail if shared memory could not be allocated or is not available, otherwise the routine falls back to ordinary memory if shared memory could not be allocated.

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

flag iarray_put_double (iarray array, CONST char *name, double 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_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

flag iarray_get_double (iarray array, CONST char *name, double *value, flag abort_on_error)

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

Parameters:

array : The Intelligent Array.
name : The name of the element.
value : The value is written here.
abort_on_error : If TRUE, the routine aborts on error.

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_double (iarray array, double value)

Fill an Intelligent Array with a double precision 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_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.

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: A KCallbackFunc object. On failure, the process aborts.
Multithreading Level: Unsafe

multi_array * iarray_multi_array (array)

Get the multi_array for an Intelligent Array.

Parameters:

array : The Intelligent Array.

Returns: The multi_array.
Multithreading Level: Unsafe

unsigned int iarray_multi_index (array)

Get the index of the Intelligent Array within the multi_array.

Parameters:

array : The Intelligent Array.

Returns: The index.
Multithreading Level: Unsafe

multi_array * iarray_array_desc (array)

Get the array_desc for an Intelligent Array.

Parameters:

array : The Intelligent Array.

Returns: The array_desc.
Multithreading Level: Unsafe

EXPERIMENTAL FUNCTION: subject to change without notice

array_pointer * iarray_arrayp (array)

Get the array_pointer for an Intelligent Array.

Parameters:

array : The Intelligent Array.

Returns: A pointer to the array_pointer. This pointer is invalidated by any operation that causes the top level packet data to be reallocated.
Multithreading Level: Unsafe

EXPERIMENTAL FUNCTION: subject to change without notice

KCallbackFunc iarray_register_data_change_func (iarray array, void (*func) (void *info), void *info)

Parameters:

array : The Intelligent Array.
func : The routine that is called when the the underlying array data are changed.
info : The arbitrary information pointer.

Returns: A KCallbackFunc object. On failure, the process aborts.
Multithreading Level: Unsafe

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

Back to Karma Home Page

Contact: Richard Gooch
Web Development: Ariel Internet Services