The "contour" Package

These routines are meant to provide a high level mechanism to create and manipulate contour images (2-dimensional slices of Karma data structures). These contour images utilise the world canvases available in the canvas package, hence the resulting code is device independent. NOTE: THIS PACKAGE IS WORK IN PROGRESS. THE INTERFACE MAY CHANGE IN THE NEXT RELEASE, POSSIBLY WITHOUT NOTICE.

Library: karmagraphics
Link With: -lkarmagraphics

Functions

contour_init	Initialise the package for a particular canvas.
contour_create_group	Create a container to hold a group of KContourImage objects.
contour_destroy_group	Destroy a group of KContourImage objects.
contour_create_restr	Create contour image from 2D slice with restrictions.
contour_create_from_iarray	Create a contour image from an Intelligent Array.
contour_create_sequence	Create a sequence of contour images from a 3D slice.
contour_create_sequence_from_iarray	Create a sequence of contour images from an Intelligent Array.
contour_destroy	Destroy contour image.
contour_create_viewable_group	Create container to hold group of KViewableContourImage objects.
contour_destroy_viewable_group	Destroy a group of KViewableContourImage objects.
contour_create_viewable	Create viewable contour image.
contour_create_viewable_sequence	Create a sequence of viewable contour images.
contour_destroy_viewable	Destroy a viewable contour image.
contour_set_active	Set active state for a viewable contour image.
contour_set_all_inactive	Clear active state for all viewable contour images in a group.
contour_register_data_change	Notify data for contour image has changed.
contour_set_canvas_attributes	Set the contour image attributes for a world canvas.
contour_set_levels	Set/update the contour levels for a KContourImage object.
contour_set_group_levels	Set/update contour levels for a group of KContourImage objects.
contour_set_level_styles	Set/update contour level styles for KViewableContourImage object.
contour_set_group_level_styles	Set/update clevel styles for KViewableContourImage objects.
contour_get_worldcanvas	Get the world canvas for a viewable contour image.
contour_parse_levels	Parse a textual contour level specification.
contour_unscale_levels	Unscale contour levels.

Tables

contour_CANVAS_ATTRIBUTES	List of canvas attributes for contourable images
contour_CONTOUR_ATTRIBUTES	List of attributes for contourable images

Functions

EXPERIMENTAL FUNCTION: subject to change without notice

void contour_init (KWorldCanvas canvas, ...)

This routine will initialise the contour package for a particular world canvas. Calling this routine causes a number of callback routines internal to the package to be registered with the canvas (such as refresh and position event callbacks). This routine must be called before creating contour images.

Parameters:

canvas : The world canvas object.
... : The list of parameter attribute-key attribute-value-ptr pairs must follow. This list must be terminated with the CONTOUR_CANVAS_ATT_END. See contour_CANVAS_ATTRIBUTES for the list of attributes.

Returns: Nothing.
Multithreading Level: Unsafe

EXPERIMENTAL FUNCTION: subject to change without notice

KContourImageGroup contour_create_group ()

Create a container to hold a group of KContourImage objects.

Parameters:

Returns: The group container on success, else NULL.
Multithreading Level: Unsafe

EXPERIMENTAL FUNCTION: subject to change without notice

void contour_destroy_group (KContourImageGroup group)

Destroy a group of KContourImage objects.

Parameters:

group : The group to destroy. The group container is also destroyed.

Returns: Nothing.
Multithreading Level: Unsafe

EXPERIMENTAL FUNCTION: subject to change without notice

KContourImage contour_create_restr (multi_array *multi_desc, array_desc *arr_desc, char *slice, unsigned int hdim, unsigned int vdim, unsigned int elem_index, unsigned int num_restr, char **restr_names, double *restr_values, KContourImageGroup group)

This routine will create a contour image object from a 2-dimensional slice of a Karma data structure. At a later time, this contour image may be used to create a viewable contour image.

Parameters:

multi_desc : The multi_array descriptor which contains the Karma data structure. The routine increments the attachment count on the descriptor on successful completion. This may be NULL.
arr_desc : The array descriptor.
slice : The start of the slice data.
hdim : The dimension index of the horizontal dimension.
vdim : The dimension index of the vertical dimension.
elem_index : The element index in the data packets.
num_restr : The number of matched restrictions.
restr_names : The restriction names.
restr_values : The restriction values.
group : The KContourImageGroup to add the new object too. If NULL, it is not added to any group.

Returns: A KContourImage object on success, NULL.
Multithreading Level: Unsafe
Note:

Restriction information is automatically deallocated when contour_destroy is called.

EXPERIMENTAL FUNCTION: subject to change without notice

KContourImage contour_create_from_iarray (iarray array, flag swap, KContourImageGroup group)

This routine will create a contour image object from a 2-dimensional Intelligent Array. At a later time, this contour image may be used to create a viewable contour image.

Parameters:

array : The Intelligent Array. The underlying multi_array data structure will have its attachment count incremented upon successful completion.
swap : If TRUE the y axis will be displayed horizontally.
group : The KContourImageGroup to add the new object too. If NULL, it is not added to any group.

Returns: A KContourImage object on success, else NULL.
Multithreading Level: Unsafe

EXPERIMENTAL FUNCTION: subject to change without notice

KContourImage * contour_create_sequence (multi_array *multi_desc, array_desc *arr_desc, char *cube, unsigned int hdim, unsigned int vdim, unsigned int fdim, unsigned int elem_index, KContourImageGroup group)

This routine will create a sequence of contour image objects from a 3-dimensional cube of a Karma data structure. At a later time, this sequence of contour images may be used to create a sequence of viewable contour images.

Parameters:

multi_desc : The multi_array descriptor which contains the Karma data structure. The routine increments the attachment count on the descriptor on successful completion. This may be NULL.
arr_desc : The array descriptor.
cube : The start of the cube data.
hdim : The dimension index of the horizontal dimension.
vdim : The dimension index of the vertical dimension.
fdim : The dimension index of the frame dimension (dimension containing the sequence). The number of frames is the same as the length of this dimension.
elem_index : The element index in the data packets.
group : The KContourImageGroup to add the new objects too. If NULL, it is not added to any group.

Returns: A pointer to a dynamically allocated array of contour image objects on success, else NULL.
Multithreading Level: Unsafe

EXPERIMENTAL FUNCTION: subject to change without notice

KContourImage * contour_create_sequence_from_iarray (iarray array, unsigned int hdim, unsigned int vdim, unsigned int fdim, KContourImageGroup group)

This routine will create a sequence of contour image objects from a 3-dimensional Intelligent Array. At a later time, this sequence of contour images may be used to create a sequence of viewable contour images.

Parameters:

array : The Intelligent Array. The underlying multi_array data structure will have its attachment count incremented upon successful completion.
hdim : The dimension index of the horizontal dimension.
vdim : The dimension index of the vertical dimension.
fdim : The dimension index of the frame dimension (dimension containing the sequence). The number of frames is the same as the length of this dimension.
group : The KContourImageGroup to add the new objects too. If NULL, it is not added to any group.

Returns: A pointer to a dynamically allocated array of contour image objects on success, else NULL.
Multithreading Level: Unsafe

EXPERIMENTAL FUNCTION: subject to change without notice

void contour_destroy (KContourImage cimage)

This routine will destroy a contour image.

Parameters:

cimage : The contour image.

Returns: Nothing.
Multithreading Level: Unsafe
Note:

The associated multi_array descriptor is also deallocated (or at least, the attachment count is decreased).

EXPERIMENTAL FUNCTION: subject to change without notice

KViewableContourImageGroup contour_create_viewable_group ()

Create container to hold group of KViewableContourImage objects.

Parameters:

Returns: The group container on success, else NULL.
Multithreading Level: Unsafe

EXPERIMENTAL FUNCTION: subject to change without notice

void contour_destroy_viewable_group (KViewableContourImageGroup group)

Destroy a group of KViewableContourImage objects.

Parameters:

group : The group to destroy. The group container is also destroyed.

Returns: Nothing.
Multithreading Level: Unsafe

EXPERIMENTAL FUNCTION: subject to change without notice

KViewableContourImage contour_create_viewable (KContourImage cimage, KWorldCanvas canvas, KViewableContourImageGroup group)

This routine will create a viewable contour image object from a contour image. At a later time, this viewable contour image may be made visible. This routine will not cause the canvas to be refreshed.

Parameters:

cimage : The contour image.
canvas : The world canvas onto which the viewable contour image may be drawn. Many viewable contour images may be associated with a single canvas.
group : The KViewableContourImageGroup to add the new object too. If NULL, it is not added to any group.

Returns: A KViewableContourImage object on success, NULL.
Multithreading Level: Unsafe
Note:

The KViewableContourImage will be automatically destroyed if the canvas is destroyed.

EXPERIMENTAL FUNCTION: subject to change without notice

KViewableContourImage * contour_create_viewable_sequence (KContourImage *cimages, unsigned int num, KWorldCanvas canvas, KViewableContourImageGroup group)

This routine will create a sequence of viewable contour image objects from a sequence of contour images. At a later time, these viewable contour images may be made visible. This routine will not cause the canvas to be refreshed.

Parameters:

cimage : The contour images.
num : The number of contour images in the sequence.
canvas : The world canvas onto which the viewable contour images may be drawn. Many viewable contour images may be associated with a single canvas.
group : The KViewableContourImageGroup to add the new objects too. If NULL, it is not added to any group.

Returns: A pointer to a dynamically allocated array of viewable contour image objects on success, else NULL.
Multithreading Level: Unsafe
Note:

The KViewableContourImage objects will be automatically destroyed if the canvas is destroyed.

EXPERIMENTAL FUNCTION: subject to change without notice

void contour_destroy_viewable (KViewableContourImage vcimage)

This routine will destroy a viewable contour image.

Parameters:

vcimage : The viewable contour image.

Returns: Nothing.
Multithreading Level: Unsafe

EXPERIMENTAL FUNCTION: subject to change without notice

flag contour_set_active (KViewableContourImage vcimage, flag active, flag force_refresh, flag refresh_if_changed)

This routine will make a viewable contour image active or inactive.

Parameters:

vcimage : The viewable contour image.
active : If TRUE, the viewable contour image is made active, else it is made inactive.
force_refresh : If TRUE, the canvas is always refreshed.
refresh_if_changed : If TRUE, the canvas is refreshed if the viewable contour image active state changed.

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

EXPERIMENTAL FUNCTION: subject to change without notice

flag contour_set_all_inactive (KViewableContourImageGroup group, flag refresh_if_changed)

This routine will make all viewable contour images in a group inactive.

Parameters:

group : The group of viewable contour images.
refresh_if_changed : If TRUE, canvases are refreshed if the active state of any viewable contour image changed.
key : The key to use for inactivation of viewable contour images. If this is 0 then all viewable contour images will be made inactive.

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

EXPERIMENTAL FUNCTION: subject to change without notice

flag contour_register_data_change (KContourImage cimage)

This routine will register a change in the Karma data structure associated with a contour image. If the contour image is active, it will be immediately redrawn on its canvas.

Parameters:

cimage : The contour image.

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

EXPERIMENTAL FUNCTION: subject to change without notice

void contour_set_canvas_attributes (KWorldCanvas canvas, ...)

Set the contour image attributes for a world canvas.

Parameters:

canvas : The world canvas.
... : The list of parameter attribute-key attribute-value-ptr pairs must follow. This list must be terminated with the CONTOUR_CANVAS_ATT_END. See contour_CANVAS_ATTRIBUTES for the list of attributes.

Returns: Nothing.
Multithreading Level: Unsafe
Note:

The canvas is not refreshed by this operation.

EXPERIMENTAL FUNCTION: subject to change without notice

void contour_set_levels (KContourImage cimage, unsigned int num_levels, CONST double *contour_levels)

This routine will set/update the contour levels for a KContourImage object. Canvases are not refreshed by this operation.

Parameters:

cimage : The KContourImage object.
num_levels : The number of contour levels.
contour_levels : The array of contour levels. These are copied.

Returns: Nothing.
Multithreading Level: Unsafe

EXPERIMENTAL FUNCTION: subject to change without notice

void contour_set_group_levels (KContourImageGroup group, unsigned int num_levels, CONST double *contour_levels)

This routine will set/update the contour levels for a group of KContourImage objects. Canvases are not refreshed by this operation.

Parameters:

group : The group of KContourImage objects.
num_levels : The number of contour levels.
contour_levels : The array of contour levels. These are copied.

Returns: Nothing.
Multithreading Level: Unsafe

EXPERIMENTAL FUNCTION: subject to change without notice

void contour_set_level_styles (KViewableContourImage vcimage, CONST unsigned long *contour_pixels, CONST flag *dash, CONST double *linewidths)

This routine will set/update the contour level tyles for a KViewableContourImage object. No canvas is refreshed by this operation.

Parameters:

vcimage : The KViewableContourImage object.
contour_pixels : The array of contour pixels. These are copied. This may be NULL.
dash : The array of dash flags. This may be NULL.
linewidths : The array of line widths. This may be NULL.

Returns: Nothing.
Multithreading Level: Unsafe

EXPERIMENTAL FUNCTION: subject to change without notice

void contour_set_group_level_styles (KViewableContourImageGroup group, CONST unsigned long *contour_pixels, CONST flag *dash, CONST double *linewidths)

This routine will set/update the contour level styles for a group of KViewableContourImage objects. No canvas is refreshed by this operation.

Parameters:

group : The group of KViewableContourImage objects.
contour_pixels : The array of contour pixels. These are copied. This may be NULL.
dash : The array of dash flags. This may be NULL.
linewidths : The array of line widths. This may be NULL.

Returns: Nothing.
Multithreading Level: Unsafe

EXPERIMENTAL FUNCTION: subject to change without notice

KWorldCanvas contour_get_worldcanvas (KViewableContourImage vcimage)

Get the world canvas for a viewable contour image.

Parameters:

vcimage : The KViewableContourImage object.

Returns: The KWorldCanvas object.
Multithreading Level: Unsafe

EXPERIMENTAL FUNCTION: subject to change without notice

unsigned int contour_parse_levels (double *contour_levels, unsigned int max_levels, CONST char *string, double min, double max)

Parse a textual contour level specification.

Parameters:

contour_levels : The raw contour levels are written here.
max_levels : The maximum number of levels.
string : The string to parse.
min : The minimum value in the data range.
max : The maximum value in the data range.

Returns: The number of levels. On error 0 is returned.
Multithreading Level: Unsafe

EXPERIMENTAL FUNCTION: subject to change without notice

void contour_unscale_levels (double *contour_levels, flag *dash, double *linewidths, unsigned int num_levels, double scale, double offset, double neg_width, double pos_width)

Unscale contour levels.

Parameters:

contour_levels : The scaled contour levels. This is updated with the raw (unscaled) contour levels.
dash : An array of booleans will be written here. TRUE is written if the corresponding scaled contour level is negative, else FALSE is written.
linewidths : An array of linewidths will be written here.
num_levels : The number of levels.
scale : The scale factor.
offset : The offset.
neg_width : The linewidth for negative contours.
pos_width : The linewidth for positive contours.

Returns: Nothing.
Multithreading Level: Unsafe
Note:

scaled = raw * scale + offset.

Tables

contour_CANVAS_ATTRIBUTES List of canvas attributes for contourable images

Name Get Type Set Type Meaning

CONTOUR_CANVAS_ATT_END End of varargs list
CONTOUR_CANVAS_ATT_COLOURNAME CONST char * Colour name

contour_CONTOUR_ATTRIBUTES List of attributes for contourable images

Name Get Type Set Type Meaning

CONTOUR_CIMAGE_ATT_END End of varargs list
CONTOUR_CIMAGE_ATT_ACTIVE flag * flag Active state

Back to Karma Home Page

Contact: Richard Gooch
Web Development: Ariel Internet Services

Name	Get Type	Set Type	Meaning

CONTOUR_CANVAS_ATT_END			End of varargs list
CONTOUR_CANVAS_ATT_COLOURNAME		CONST char *	Colour name