The "viewimg" Package

These routines are meant to provide a high level mechanism to create and manipulate viewable images (2-dimensional slices of Karma data structures). These viewable images utilise the world canvases available in the canvas package, hence the resulting code is device independent.

Library: karmagraphics
Link With: -lkarmagraphics

Functions

viewimg_draw_edit_listDraw edit list into array associated with viewable image.
viewimg_draw_edit_objectDraw edit object into array associated with viewable image.
viewimg_initInitialise the package for a particular canvas.
viewimg_create_restrCreate viewable image from 2D slice with restrictions.
viewimg_createCreate viewable image from 2D slice.
viewimg_create_from_iarrayCreate a viewable image from an Intelligent Array.
viewimg_create_sequenceCreate a sequence of viewable images from a 3D slice.
viewimg_create_rgbCreate a TrueColour viewable image.
viewimg_create_rgb_sequenceCreate sequence of TrueColour viewable images from 3D slice.
viewimg_make_activeMake viewable image active and possibly refresh.
viewimg_set_activeMake viewable image active with controlled refresh.
viewimg_register_data_changeNotify data for viewable image has changed.
viewimg_destroyDestroy viewable image.
viewimg_get_activeGet the active ViewableImage associated with a world canvas.
viewimg_test_activeTest if viewable image is active.
viewimg_register_position_event_funcRegister position event callback.
viewimg_fill_ellipseDraw an ellipse into an array associated with a viewable image.
viewimg_fill_polygonDraw a polygon into an array associated with a viewable image.
viewimg_get_canvas_attributesGet the viewable image attributes for a world canvas.
viewimg_set_canvas_attributesSet the viewable image attributes for a world canvas.
viewimg_get_attributesGet the attributes for a viewable image.
viewimg_get_worldcanvasGet the world canvas for a viewable image.

Prototype Functions

VIEWIMG_PROTO_position_funcPosition event callback.

Tables

VIEWIMG_CANVAS_ATTRIBUTESList of canvas attributes for viewable images
VIEWIMG_VIEWIMG_ATTRIBUTESList of attributes for viewable images


Functions


flag viewimg_draw_edit_list (ViewableImage vimage, KImageEditList ilist)

This routine will draw a list of edit objects to the 2-dimensional data associated with a viewable image object.

Parameters:

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


flag viewimg_draw_edit_object (ViewableImage vimage, char *object)

This routine will draw one edit object to the 2-dimensional data associated with a viewable image object.

Parameters:

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


void viewimg_init (KWorldCanvas canvas)

This routine will initialise the viewimg 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). The use of this routine is optional at the moment: the routines which create viewable images perform this function automatically. In version 2.0 of Karma, this use of this routine before creating viewable images will become mandatory.

Parameters:

Returns: Nothing.
Multithreading Level: Unsafe


ViewableImage viewimg_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 num_restr, char **restr_names, double *restr_values)

This routine will create a PseudoColour viewable image object from a 2-dimensional slice of a Karma data structure. At a later time, this viewable image may be made visible. This routine will not cause the canvas to be refreshed.

Parameters:

Returns: A viewable image on success, NULL.
Multithreading Level: Unsafe
Note:


ViewableImage viewimg_create (KWorldCanvas canvas, multi_array *multi_desc, array_desc *arr_desc, char *slice, unsigned int hdim, unsigned int vdim, unsigned int elem_index)

This routine will create a PseudoColour viewable image object from a 2-dimensional slice of a Karma data structure. At a later time, this viewable image may be made visible. This routine will not cause the canvas to be refreshed.

Parameters:

Returns: A viewable image on success, NULL.
Multithreading Level: Unsafe
Note:


ViewableImage viewimg_create_from_iarray (KWorldCanvas canvas, iarray array, flag swap)

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

Parameters:

Returns: A viewable image on success, else NULL.
Multithreading Level: Unsafe
Note:


ViewableImage * viewimg_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)

This routine will create a sequence of viewable image objects from a 3-dimensional cube of a Karma data structure. At a later time, this sequence of viewable images may be made visible in any order. This routine will not cause the canvas to be refreshed.

Parameters:

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


ViewableImage viewimg_create_rgb (KWorldCanvas canvas, multi_array *multi_desc, array_desc *arr_desc, char *slice, unsigned int hdim, unsigned int vdim, unsigned int red_index, unsigned int green_index, unsigned int blue_index, unsigned num_restr, char **restr_names, double *restr_values)

This routine will create a TrueColour viewable image object from a 2-dimensional slice of a Karma data structure. At a later time, this viewable image may be made visible. This routine will not cause the canvas to be refreshed.

Parameters:

Returns: A viewable image on success, else NULL.
Multithreading Level: Unsafe
Note:


ViewableImage * viewimg_create_rgb_sequence (KWorldCanvas canvas, multi_array *multi_desc, array_desc *arr_desc, char *cube, unsigned int hdim, unsigned int vdim, unsigned int fdim, unsigned int red_index, unsigned int green_index, unsigned int blue_index, unsigned num_restr, char **restr_names, double *restr_values)

This routine will create a sequence of TrueColour viewable image objects from a 3-dimensional cube of a Karma data structure. At a later time, this sequence of viewable images may be made visible in any order. This routine will not cause the canvas to be refreshed.

Parameters:

Returns: A viewable image on success, else NULL.
Multithreading Level: Unsafe
Note:


flag viewimg_make_active (ViewableImage vimage)

This routine will make a viewable image the active image for its associated world canvas. The canvas is then refreshed (possibly resized), provided that the new viewable image was not already active.

Parameters:

Returns: TRUE on success, else FALSE.
Multithreading Level: Unsafe
See Also: ALSO] viewimg_set_active.


flag viewimg_set_active (ViewableImage vimage, flag refresh)

This routine will make a viewable image the active image for its associated world canvas.

Parameters:

Returns: TRUE on success, else FALSE.
Multithreading Level: Unsafe
See Also: ALSO] viewimg_make_active.


flag viewimg_register_data_change (ViewableImage vimage)

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

Parameters:

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


void viewimg_destroy (ViewableImage vimage)

This routine will destroy a viewable image. If this is not called prior to process exit, shared memory segments could remain after the process exits.

Parameters:

Returns: Nothing.
Multithreading Level: Unsafe
Note:


ViewableImage viewimg_get_active (KWorldCanvas canvas)

Get the active ViewableImage associated with a world canvas.

Parameters:

Returns: The active viewable image on success, else NULL (indicating no viewable image is active for the canvas).
Multithreading Level: Unsafe


flag viewimg_test_active (ViewableImage vimage)

This routine will test if a viewable image is the active image for its associated world canvas.

Parameters:

Returns: TRUE if the viewable image is actice, else FALSE.
Multithreading Level: Unsafe


KCallbackFunc viewimg_register_position_event_func (KWorldCanvas canvas, flag (*func) (), void *f_info)

This routine will register a position event function for a world canvas which has a number of ViewableImage objects associated with it. The position event function will be called whenever a position event on the canvas has not been consumed. Many position event functions may be registered per canvas. The first function registered is the first function called upon a position event.

Parameters:

Returns: A handle to a KWorldCanvasPositionFunc object.
Multithreading Level: Unsafe


flag viewimg_fill_ellipse (ViewableImage vimage, double centre_x, double centre_y, double radius_x, double radius_y, double value[2])

This routine will draw a filled ellipse into a 2 dimensional slice of data associated with a viewable image.

Parameters:

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


flag viewimg_fill_polygon (ViewableImage vimage, edit_coord *coords, unsigned int num_vertices, double value[2])

This routine will draw a filled polygon into a 2 dimensional slice of data associated with a viewable image.

Parameters:

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


void viewimg_get_canvas_attributes (KWorldCanvas canvas, ...)

Get the viewable image attributes for a world canvas.

Parameters:

Returns: Nothing.
Multithreading Level: Unsafe


void viewimg_set_canvas_attributes (KWorldCanvas canvas, ...)

This routine will control the autoscaling options used when viewable images are displayed on their associated world canvas.

Parameters:

Returns: Nothing.
Multithreading Level: Unsafe
Note:


void viewimg_get_attributes (ViewableImage vimage, ...)

Get the attributes for a viewable image.

Parameters:

Returns: Nothing.
Multithreading Level: Unsafe


KWorldCanvas viewimg_get_worldcanvas (ViewableImage vimage)

Get the world canvas for a viewable image.

Parameters:

Returns: The KWorldCanvas object.
Multithreading Level: Unsafe


Prototype Functions


flag VIEWIMG_PROTO_position_func (ViewableImage vimage, double x, double y, void *value, unsigned int event_code, void *e_info, void **f_info, double x_lin, double y_lin, unsigned int value_type)

This routine is a position event consumer for a world canvas which has a number of ViewableImage objects associated with it.

Parameters:

Returns: TRUE if the event was consumed, else FALSE indicating that the event is still to be processed.
Multithreading Level: Unsafe


Tables


VIEWIMG_CANVAS_ATTRIBUTES

Name Get Type Set Type Meaning
VIEWIMG_ATT_END End of varargs list
VIEWIMG_ATT_AUTO_X flag * flag Enable automatic horizontal scaling
VIEWIMG_ATT_AUTO_Y flag * flag Enable automatic vertical scaling
VIEWIMG_ATT_AUTO_V flag * flag Enable automatic intensity scaling
VIEWIMG_ATT_INT_X flag * flag Force integer horizontal zoom-in/zoom-out factor
VIEWIMG_ATT_INT_Y flag * flag Force integer vertical zoom-in/zoom-out factor
VIEWIMG_ATT_MAINTAIN_ASPECT flag * flag Maintain data image aspect ratio
VIEWIMG_ATT_ALLOW_TRUNCATION flag * flag Allow shrunken images to be truncated.


VIEWIMG_VIEWIMG_ATTRIBUTES

Name Get Type Set Type Meaning
VIEWIMG_VATT_END End of varargs list
VIEWIMG_VATT_TRUECOLOUR flag * flag Image is TrueColour
VIEWIMG_VATT_ARRAY_DESC array_desc ** array_desc * The array descriptor for the image
VIEWIMG_VATT_SLICE char ** char * Start of the image data
VIEWIMG_VATT_HDIM unsigned int * unsigned int The horizontal dimension
VIEWIMG_VATT_VDIM unsigned int * unsigned int The vertical dimension
VIEWIMG_VATT_PSEUDO_INDEX unsigned int * unsigned int The PseudoColour element index
VIEWIMG_VATT_RED_INDEX unsigned int * unsigned int The TrueColour red element index
VIEWIMG_VATT_GREEN_INDEX unsigned int * unsigned int The TrueColour green element index
VIEWIMG_VATT_BLUE_INDEX unsigned int * unsigned int The TrueColour blue element index


Contact: Richard Gooch
Web Development: Ariel Internet Services