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_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_set_active	Set active state for a contour image controlled refresh.
contour_set_all_inactive	Clear active state all contour images controlled refresh.
contour_register_data_change	Notify data for contour image has changed.
contour_destroy	Destroy contour image.
contour_set_canvas_attributes	Set the contour image attributes for a world canvas.
contour_set_attributes	Set the attributes for a KContourImage object.
contour_set_levels	Set/update the contour levels for a KContourImage object.
contour_get_worldcanvas	Get the world canvas for a 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

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

KContourImage contour_create_restr (KWorldCanvas canvas, multi_array *multi_desc, array_desc *arr_desc, char *slice, unsigned int hdim, unsigned int vdim, unsigned int elem_index, unsigned int num_levels, CONST double *contour_levels, unsigned num_restr, char **restr_names, double *restr_values, uaddr key)

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 made visible. This routine will not cause the canvas to be refreshed.

Parameters:

canvas : The world canvas onto which the contour image may be drawn. Many contour images may be associated with a single canvas.
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_levels : The number of contour levels. This may be 0.
contour_levels : The array of contour levels.
num_restr : The number of matched restrictions.
restr_names : The restriction names.
restr_values : The restriction values.
key : The key to associate with this contour image.

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

Restriction information is automatically deallocated when contour_destroy is called.

KContourImage contour_create_from_iarray (KWorldCanvas canvas, iarray array, flag swap, unsigned int num_levels, CONST double *contour_levels, uaddr key)

This routine will create a contour image object from a 2-dimensional Intelligant Array. At a later time, this contour image may be made visible. This routine will not cause the canvas to be refreshed. Many contour images may be associated with a single canvas.

Parameters:

canvas : The world canvas object.
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.
num_levels : The number of contour levels. This may be 0.
contour_levels : The array of contour levels.
key : The key to associate with this contour image.

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

KContourImage * contour_create_sequence (KWorldCanvas canvas, multi_array *multi_desc, array_desc *arr_desc, char *cube, unsigned int hdim, unsigned int vdim, unsigned int fdim, unsigned int elem_index, unsigned int num_levels, CONST double *contour_levels, uaddr key)

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 made visible in any order. This routine will not cause the canvas to be refreshed.

Parameters:

canvas : The world canvas object.
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.
num_levels : The number of contour levels. This may be 0.
contour_levels : The array of contour levels.
key : The key to associate with this contour image.

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

KContourImage * contour_create_sequence_from_iarray (KWorldCanvas canvas, iarray array, unsigned int hdim, unsigned int vdim, unsigned int fdim, unsigned int num_levels, CONST double *contour_levels, uaddr key)

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 made visible in any order. This routine will not cause the canvas to be refreshed.

Parameters:

canvas : The world canvas object.
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.
num_levels : The number of contour levels. This may be 0.
contour_levels : The array of contour levels.
key : The key to associate with this contour image.

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

flag contour_set_active (KContourImage cimage, flag active, flag force_refresh, flag refresh_if_changed, flag exclusive, uaddr key)

This routine will make a contour image active or inactive.

Parameters:

cimage : The contour image.
active : If TRUE, the contourable 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 contourable image active state changed.
exclusive : If TRUE and active is TRUE, make this contour image the only active one for this canvas. Other contour images for this canvas will be made inactive.
key : The key to use for inactivation of other contour images. If this is 0 then all other contour images will be made inactive.

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

flag contour_set_all_inactive (KWorldCanvas canvas, flag force_refresh, flag refresh_if_changed, uaddr key)

This routine will make all contour images associated with a world canvas inactive.

Parameters:

canvas : The world canvas.
force_refresh : If TRUE, the canvas is always refreshed.
refresh_if_changed : If TRUE, the canvas is refreshed if the active state of any contourable image changed.
key : The key to use for inactivation of contour images. If this is 0 then all contour images will be made inactive.

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

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

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

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.

void contour_set_attributes (KContourImage cimage, ...)

Set the attributes for a KContourImage object.

Parameters:

cimage : The KContourImage object.
... : The list of parameter attribute-key attribute-value-ptr pairs must follow. This list must be terminated with the CONTOUR_CIMAGE_ATT_END. See contour_CONTOUR_ATTRIBUTES for the list of attributes.

Returns: Nothing.
Multithreading Level: Unsafe
Note:

The canvas is not refreshed by this operation.

void contour_set_levels (KContourImage cimage, unsigned int num_levels, CONST double *contour_levels, CONST unsigned long *contour_pixels, CONST flag *dash, CONST double *linewidths)

This routine will set/update the contour levels for a KContourImage object. The canvas is not refreshed by this operation.

Parameters:

cimage : The KContourImage object.
num_levels : The number of contour levels.
contour_levels : The array of contour levels.
contour_pixels : The array of contour pixels. 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

KWorldCanvas contour_get_worldcanvas (KContourImage cimage)

Get the world canvas for a contour image.

Parameters:

cimage : The KContourImage 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 TRUE 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

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

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