# 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_colourbar_create | Create a colourbar world canvas for another world canvas.
viewimg_create_drag_and_zoom_interface | Create a drag and zoom user interface for a canvas.
viewimg_draw_edit_list | Draw edit list into array associated with viewable image.
viewimg_draw_edit_object | Draw edit object into array associated with viewable image.
viewimg_header_position_func | Position event callback.
viewimg_init | Initialise the package for a particular canvas.
viewimg_create_restr | Create viewable image from 2D slice with restrictions.
viewimg_create | Create viewable image from 2D slice.
viewimg_create_from_iarray | Create a viewable image from an Intelligent Array.
viewimg_create_sequence | Create a sequence of viewable images from a 3D slice.
viewimg_create_sequence_from_iarray | Create a sequence of viewable images from an Intelligent Array.
viewimg_create_rgb | Create a TrueColour viewable image.
viewimg_create_rgb2 | Create a TrueColour viewable image.
viewimg_create_rgb_sequence | Create sequence of TrueColour viewable images from 3D slice.
viewimg_create_rgb_sequence2 | Create sequence of TrueColour viewable images from 3D slice.
viewimg_make_active | Make viewable image active and possibly refresh.
viewimg_set_active | Make viewable image active with controlled refresh.
viewimg_register_data_change | Notify data for viewable image has changed.
viewimg_destroy | Destroy viewable image.
viewimg_get_active | Get the active ViewableImage associated with a world canvas.
viewimg_test_active | Test if viewable image is active.
viewimg_register_position_event_func | Register position event callback.
viewimg_register_destroy_func | Register destroy callback.
viewimg_fill_ellipse | Draw an ellipse into an array associated with a viewable image.
viewimg_fill_polygon | Draw a polygon into an array associated with a viewable image.
viewimg_get_canvas_attributes | Get the viewable image attributes for a world canvas.
viewimg_set_canvas_attributes | Set the viewable image attributes for a world canvas.
viewimg_get_attributes | Get the attributes for a viewable image.
viewimg_set_attributes | Set the attributes for a viewable image.
viewimg_set_array_attributes | Set the attributes for an array of viewable images.
viewimg_partial_refresh | Perform a partial refresh of a canvas.
viewimg_get_worldcanvas | Get the world canvas for a viewable image.
viewimg_statistics_position_func | Position event callback.
viewimg_statistics_geom_func | Process a geometry editor event on a pixel canvas.
viewimg_statistics_compute | Compute and display statistics for a subimage.
viewimg_track_compute | Compute track strings.
viewimg_values_position_func | Position event callback.
viewimg_values_geom_func | Process a geometry editor event on a pixel canvas.
viewimg_values_display | Compute and display values for a subimage.

#### Prototype Functions

viewimg_PROTO_position_func | Position event callback.
viewimg_PROTO_destroy_func | Process a destroy event on a ViewableImage.

#### Tables

viewimg_CANVAS_ATTRIBUTES | List of canvas attributes for viewable images
viewimg_VIMAGE_ATTRIBUTES | List of attributes for viewable images

## Functions

#### EXPERIMENTAL FUNCTION: subject to change without notice

KWorldCanvas viewimg_colourbar_create (KWorldCanvas main_wc)

Create a colourbar world canvas for another world canvas.

Parameters:

- main_wc : The main world canvas to create the colourbar world canvas for.

Returns: The colourbar world canvas on success, else NULL. This will be automatically destroyed when the main world canvas is destroyed.
Multithreading Level: Unsafe

#### EXPERIMENTAL FUNCTION: subject to change without notice

KPixCanvasEditorContext viewimg_create_drag_and_zoom_interface (KWorldCanvas canvas)

This routine will create a drag and zoom user interface for a world canvas. When the user presses the left mouse button in the canvas and moves the mouse with the button still pressed a rubber-band box will be drawn on the canvas. When the left mouse button is released the image in the rubber-banded box is zoomed to fill as much of the canvas as is possible, depending on the zoom policy.

Parameters:

- canvas : The world canvas object.

Returns: The KPixCanvasEditorContext created for rubber-banding. Extra key bindings may be added to this context.
Multithreading Level: Unsafe

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:

- vimage : The viewable image.
- ilist : The list of edit objects.

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:

- vimage : The viewable image.
- object : The edit object.

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

#### EXPERIMENTAL FUNCTION: subject to change without notice

flag viewimg_header_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:

- viewimg : The active viewable image.
- x : The horizontal world co-ordinate of the event.
- y : The vertical world co-ordinate of the event. These values will have been transformed by the registered transform function (see canvas_register_transforms_func) for the associated world canvas.
- value : A pointer to the data value in the viewable image corresponding to the event co-ordinates.
- event_code : The arbitrary event code.
- e_info : The arbitrary event information.
- f_info : The arbitrary function information pointer.
- x_lin : The linear horizontal world co-ordinate (the co-ordinate prior to the transform function being called).
- y_lin : The linear vertical world co-ordinate (the co-ordinate prior to the transform function being called).
- value_type : The type of the data value. This may be K_DCOMPLEX or K_UB_RGB.

Returns: TRUE if the event was consumed, else FALSE indicating that the event is still to be processed.
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:

- canvas : The world canvas object.

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, CONST char **restr_names, CONST 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:

- canvas : The world canvas onto which the viewable image may be drawn. Many viewable 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_restr : The number of matched restrictions. If this is 0, no restrictions are recorded (this is the same as calling viewimg_create).
- restr_names : The restriction names.
- restr_values : The restriction values.

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

- Restriction information is automatically deallocated when viewimg_destroy is called.
- The routine may produce cache data which will vastly increase the speed of subsequent operations on this data. Prior to process exit, a call MUST be made to viewimg_destroy, otherwise shared memory segments could remain after the process exits.
- The ViewableImage will be automatically destroyed if the canvas is destroyed.

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:

- canvas : The world canvas onto which the viewable image may be drawn. Many viewable 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.

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

- The routine may produce cache data which will vastly increase the speed of subsequent operations on this data. Prior to process exit, a call MUST be made to viewimg_destroy, otherwise shared memory segments could remain after the process exits.
- The ViewableImage will be automatically destroyed if the canvas is destroyed.

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

This routine will create a viewable image object from a 2-dimensional Intelligent 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:

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

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

- The routine may produce cache data which will vastly increase the speed of subsequent operations on this data. Prior to process exit, a call MUST be made to viewimg_destroy, otherwise shared memory segments could remain after the process exits.
- The ViewableImage will be automatically destroyed if the canvas is destroyed.

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:

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

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

- The routine may produce cache data which will vastly increase the speed of subsequent operations on this data. Prior to process exit, a call MUST be made to viewimg_destroy, otherwise shared memory segments could remain after the process exits.
- The ViewableImage objects will be automatically destroyed if the canvas is destroyed.

ViewableImage * viewimg_create_sequence_from_iarray (KWorldCanvas canvas, iarray array, unsigned int hdim, unsigned int vdim, unsigned int fdim)

This routine will create a sequence of viewable image objects from a 3-dimensional Intelligent Array. 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:

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

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

- The routine may produce cache data which will vastly increase the speed of subsequent operations on this data. Prior to process exit, a call MUST be made to viewimg_destroy, otherwise shared memory segments could remain after the process exits.
- The ViewableImage objects will be automatically destroyed if the canvas is destroyed.

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, CONST char **restr_names, CONST 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:

- canvas : The world canvas onto which the viewable image may be drawn. Many viewable 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.
- red_index : The element index of the red component in the data packets.
- green_index : The element index of the green component in the data packets.
- blue_index : The element index of the blue component in the data packets.
- num_restr : The number of matched restrictions. If this is 0, no restrictions are recorded.
- restr_names : The restriction names.
- restr_values : The restriction values.

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

- The 3 colour components must be of type K_UBYTE .
- Restriction information is automatically deallocated when viewimg_destroy is called.
- The routine may produce cache data which will vastly increase the speed of subsequent operations on this data. Prior to process exit, a call MUST be made to viewimg_destroy, otherwise shared memory segments could remain after the process exits.
- The ViewableImage will be automatically destroyed if the canvas is destroyed.

#### EXPERIMENTAL FUNCTION: subject to change without notice

ViewableImage viewimg_create_rgb2 (KWorldCanvas canvas, multi_array *multi_desc, array_desc *arr_desc, array_pointer *arrayp, char *slice, unsigned int hdim, unsigned int vdim, unsigned int red_index, unsigned int green_index, unsigned int blue_index, unsigned num_restr, CONST char **restr_names, CONST 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:

- canvas : The world canvas onto which the viewable image may be drawn. Many viewable 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.
- arrayp : The array_pointer. This may be NULL.
- slice : The start of the slice data.
- hdim : The dimension index of the horizontal dimension.
- vdim : The dimension index of the vertical dimension.
- red_index : The element index of the red component in the data packets.
- green_index : The element index of the green component in the data packets.
- blue_index : The element index of the blue component in the data packets.
- num_restr : The number of matched restrictions. If this is 0, no restrictions are recorded.
- restr_names : The restriction names.
- restr_values : The restriction values.

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

- The 3 colour components must be of type K_UBYTE .
- Restriction information is automatically deallocated when viewimg_destroy is called.
- The routine may produce cache data which will vastly increase the speed of subsequent operations on this data. Prior to process exit, a call MUST be made to viewimg_destroy, otherwise shared memory segments could remain after the process exits.
- The ViewableImage will be automatically destroyed if the canvas is destroyed.

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, CONST char **restr_names, CONST 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:

- canvas : The world canvas onto which the viewable image may be drawn. Many viewable images may be associated with a single canvas.
- multi_desc : The multi_array descriptor which contains the Karma data structure must. 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
- red_index : The element index of the red component in the data packets.
- green_index : The element index of the green component in the data packets.
- blue_index : The element index of the blue component in the data packets.
- num_restr : The number of matched restrictions. If this is 0, no restrictions are recorded.
- restr_names : The restriction names.
- restr_values : The restriction values.

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

- The 3 colour components must be of type K_UBYTE.
- Restriction information is copied into internally allocated storage.
- The routine may produce cache data which will vastly increase the speed of subsequent operations on this data. Prior to process exit, a call MUST be made to viewimg_destroy, otherwise shared memory segments could remain after the process exits.
- The ViewableImage objects will be automatically destroyed if the canvas is destroyed.

ViewableImage * viewimg_create_rgb_sequence2 (KWorldCanvas canvas, multi_array *multi_desc, array_desc *arr_desc, array_pointer *arrayp, 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, CONST char **restr_names, CONST 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:

- canvas : The world canvas onto which the viewable image may be drawn. Many viewable images may be associated with a single canvas.
- multi_desc : The multi_array descriptor which contains the Karma data structure must. The routine increments the attachment count on the descriptor on successful completion. This may be NULL.
- arr_desc : The array descriptor.
- arrayp : The array_pointer. This may be NULL.
- 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
- red_index : The element index of the red component in the data packets.
- green_index : The element index of the green component in the data packets.
- blue_index : The element index of the blue component in the data packets.
- num_restr : The number of matched restrictions. If this is 0, no restrictions are recorded.
- restr_names : The restriction names.
- restr_values : The restriction values.

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

- The 3 colour components must be of type K_UBYTE.
- Restriction information is copied into internally allocated storage.
- The routine may produce cache data which will vastly increase the speed of subsequent operations on this data. Prior to process exit, a call MUST be made to viewimg_destroy, otherwise shared memory segments could remain after the process exits.
- The ViewableImage objects will be automatically destroyed if the canvas is destroyed.

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:

- vimage : The viewable image.

Returns: TRUE on success, else FALSE.
Multithreading Level: Unsafe
See 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:

- vimage : The viewable image.
- refresh : If TRUE, the canvas is always refreshed, if FALSE, the canvas is not refreshed.

Returns: TRUE on success, else FALSE.
Multithreading Level: Unsafe
See 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:

- vimage : The viewable image.

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:

- vimage : The viewable image.

Returns: Nothing.
Multithreading Level: Unsafe
Note:

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

ViewableImage viewimg_get_active (KWorldCanvas canvas)

Get the active ViewableImage associated with a world canvas.

Parameters:

- canvas : The world canvas object.

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:

- vimage : The viewable image.

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:

- canvas : The world canvas object.
- func : The function that is called when a position event occurs. The prototype function is viewimg_PROTO_position_func.
- f_info : The initial arbitrary function information pointer.

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

#### EXPERIMENTAL FUNCTION: subject to change without notice

KCallbackFunc viewimg_register_destroy_func (ViewableImage vimage, void (*func) (), void *info)

This routine will register a destroy function for a viewable image. The function will be called when the viewable image is destroyed. Many destroy functions may be registered per vimage. The first function registered is the first function called upon destruction.

Parameters:

- vimage : The viewable image.
- func : The function that is called when the ViewableImage is destroyed. The prototype function is viewimg_PROTO_destroy_func.
- info : The arbitrary function information pointer.

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

- vimage : The viewable image.
- centre_x : The horizontal world co-ordinate of the centre of the ellipse.
- centre_y : The vertical world co-ordinate of the centre of the ellipse.
- radius_x : The horizontal radius.
- radius_y : The vertical radius.
- value : The complex value to fill the ellipse. This must be of type K_DCOMPLEX.

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:

- vimage : The viewable image.
- coords : The array of world co-ordinates of vertices of the polygon.
- num_vertices : The number of vertices in the polygon.
- value : The complex value to fill the polygon with. This must be of type K_DCOMPLEX.

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:

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

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:

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

Returns: Nothing.
Multithreading Level: Unsafe
Note:

- The canvas is not refreshed by this operation.

void viewimg_get_attributes (ViewableImage vimage, ...)

Get the attributes for a viewable image.

Parameters:

- vimage : The ViewableImage.
- ... : The list of parameter attribute-key attribute-value-ptr pairs must follow. This list must be terminated with the VIEWIMG_VATT_END. See viewimg_VIMAGE_ATTRIBUTES for the list of attributes.

Returns: Nothing.
Multithreading Level: Unsafe

void viewimg_set_attributes (ViewableImage vimage, ...)

Set the attributes for a viewable image.

Parameters:

- vimage : The ViewableImage.
- ... : The list of parameter attribute-key attribute-value pairs must follow. This list must be terminated with the VIEWIMG_VATT_END. See viewimg_VIMAGE_ATTRIBUTES for the list of attributes.

Returns: Nothing.
Multithreading Level: Unsafe

void viewimg_set_array_attributes (ViewableImage *vimages, unsigned int len, ...)

Set the attributes for an array of viewable images.

Parameters:

- vimages : The array of ViewableImage objects.
- len : The length of the array.
- ... : The list of parameter attribute-key attribute-value pairs must follow. This list must be terminated with the VIEWIMG_VATT_END. See viewimg_VIMAGE_ATTRIBUTES for the list of attributes.

Returns: Nothing.
Multithreading Level: Unsafe

#### EXPERIMENTAL FUNCTION: subject to change without notice

flag viewimg_partial_refresh (KWorldCanvas canvas, unsigned int num_areas, KPixCanvasRefreshArea *areas)

This routine will perform a partial refresh of a canvas. This call is similar to kwin_partial_refresh except that areas are not cleared prior to drawing if they lie within the image boundary.

Parameters:

- canvas : The world canvas.
- num_areas : The number of areas in the pixel canvas to refresh.
- areas : The list of areas to refresh. The values here are updated to ensure all points lie within the boundaries of the underlaying pixel canvas.

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

KWorldCanvas viewimg_get_worldcanvas (ViewableImage vimage)

Get the world canvas for a viewable image.

Parameters:

- vimage : The ViewableImage object.

Returns: The KWorldCanvas object.
Multithreading Level: Unsafe

#### EXPERIMENTAL FUNCTION: subject to change without notice

flag viewimg_statistics_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, double x_im, double y_im, int x_pix, int y_pix)

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

Parameters:

- viewimg : The active viewable image.
- x : The horizontal world co-ordinate of the event.
- y : The vertical world co-ordinate of the event. These values will have been transformed by the registered transform function (see canvas_register_transforms_func) for the associated world canvas.
- value : A pointer to the data value in the viewable image corresponding to the event co-ordinates.
- event_code : The arbitrary event code.
- e_info : The arbitrary event information.
- f_info : The arbitrary function information pointer.
- x_lin : The linear horizontal world co-ordinate (the co-ordinate prior to the transform function being called).
- y_lin : The linear vertical world co-ordinate (the co-ordinate prior to the transform function being called).
- value_type : The type of the data value. This may be K_DCOMPLEX or K_UB_RGB.
- x_im : The horizontal image pixel co-ordinate. 0.0 is the pixel centre.
- y_im : The vertical image pixel co-ordinate. 0.0 is the pixel centre.
- x_pix : The horizontal screen pixel co-ordinate.
- y_pix : The vertical screen pixel co-ordinate.

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

- All co-ordinates are clipped to pixel boundaries.

#### EXPERIMENTAL FUNCTION: subject to change without notice

flag viewimg_statistics_geom_func (KPixCanvasEditorContext context, KPixCanvas canvas, unsigned int object_type, unsigned int num_coords, CONST int *x, CONST int *y, unsigned int raw_event_code, void *raw_e_info, void **f_info)

Process a geometry editor event on a pixel canvas.

Parameters:

- context : The KPixCanvasEditorContext.
- canvas : The pixel canvas on which the event occurred.
- object_type : The type of the geometric object.
- num_coords : The number of co-ordinates in the geometric object.
- x : The array of horizontal co-ordinates for the geometric object.
- y : The array of vertical co-ordinates for the geometric object.
- raw_event_code : The raw arbitrary event code.
- raw_e_info : A pointer to the raw arbitrary event information.
- f_info : A pointer to an arbitrary function information pointer.

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

#### EXPERIMENTAL FUNCTION: subject to change without notice

flag viewimg_statistics_compute (ViewableImage vimage, double lx0, double ly0, double lx1,double ly1)

Compute and display statistics for a subimage.

Parameters:

- vimage : The active viewable image.
- lx0 : The first horizontal linear world co-ordinate.
- ly0 : The first vertical linear world co-ordinate.
- lx1 : The second horizontal linear world co-ordinate.
- ly1 : The second vertical linear world co-ordinate.

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

#### EXPERIMENTAL FUNCTION: subject to change without notice

void viewimg_track_compute (ViewableImage vimage, void *value, unsigned int value_type, double x, double y, double x_im, double y_im, char pix_string[STRING_LENGTH], char world_string[STRING_LENGTH], char extra_string[STRING_LENGTH])

Compute track strings.

Parameters:

- vimage : The active ViewableImage object.
- value : A pointer to the data value in the viewable image corresponding to the event co-ordinates.
- value_type : The type of the data value. This may be K_DCOMPLEX or K_UB_RGB.
- x : The horizontal world co-ordinate of the event.
- y : The vertical world co-ordinate of the event.
- x_im : The horizontal image pixel co-ordinate. 0.0 is the pixel centre.
- y_im : The vertical image pixel co-ordinate. 0.0 is the pixel centre.
- pix_string : The pixel co-ordinates and data value will be written here.
- world_string : The world co-ordinates and restriction information will be written here.
- extra_string : Extra information is written here. This may be NULL if world_string is also NULL.

Returns: Nothing.
Multithreading Level: Unsafe

#### EXPERIMENTAL FUNCTION: subject to change without notice

flag viewimg_values_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, double x_im, double y_im, int x_pix, int y_pix)

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

Parameters:

- viewimg : The active viewable image.
- x : The horizontal world co-ordinate of the event.
- y : The vertical world co-ordinate of the event. These values will have been transformed by the registered transform function (see canvas_register_transforms_func) for the associated world canvas.
- value : A pointer to the data value in the viewable image corresponding to the event co-ordinates.
- event_code : The arbitrary event code.
- e_info : The arbitrary event information.
- f_info : The arbitrary function information pointer.
- x_lin : The linear horizontal world co-ordinate (the co-ordinate prior to the transform function being called).
- y_lin : The linear vertical world co-ordinate (the co-ordinate prior to the transform function being called).
- value_type : The type of the data value. This may be K_DCOMPLEX or K_UB_RGB.
- x_im : The horizontal image pixel co-ordinate. 0.0 is the pixel centre.
- y_im : The vertical image pixel co-ordinate. 0.0 is the pixel centre.
- x_pix : The horizontal screen pixel co-ordinate.
- y_pix : The vertical screen pixel co-ordinate.

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

- All co-ordinates are clipped to pixel boundaries.

#### EXPERIMENTAL FUNCTION: subject to change without notice

flag viewimg_values_geom_func (KPixCanvasEditorContext context, KPixCanvas canvas, unsigned int object_type, unsigned int num_coords, CONST int *x, CONST int *y, unsigned int raw_event_code, void *raw_e_info, void **f_info)

Process a geometry editor event on a pixel canvas.

Parameters:

- context : The KPixCanvasEditorContext.
- canvas : The pixel canvas on which the event occurred.
- object_type : The type of the geometric object.
- num_coords : The number of co-ordinates in the geometric object.
- x : The array of horizontal co-ordinates for the geometric object.
- y : The array of vertical co-ordinates for the geometric object.
- raw_event_code : The raw arbitrary event code.
- raw_e_info : A pointer to the raw arbitrary event information.
- f_info : A pointer to an arbitrary function information pointer.

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

#### EXPERIMENTAL FUNCTION: subject to change without notice

flag viewimg_values_display (ViewableImage vimage, flag scaled, flag force, double lx0, double ly0, double lx1,double ly1)

Compute and display values for a subimage.

Parameters:

- vimage : The active viewable image.
- scaled : If TRUE, scaled values are displayed, else raw data are displayed.
- force : If TRUE, a large number of values will always be displayed. If FALSE and a large number of values is requested, the function fails.
- lx0 : The first horizontal linear world co-ordinate.
- ly0 : The first vertical linear world co-ordinate.
- lx1 : The second horizontal linear world co-ordinate.
- ly1 : The second vertical linear world co-ordinate.

Returns: TRUE on success, else FALSE (too many values).
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, double x_im, double y_im, int x_pix, int y_pix)

This routine is a position event consumer for a world canvas which has a number of ViewableImage objects associated with it. Most co-ordinate values are quantised to the nearest image pixel centre.

Parameters:

- viewimg : The active viewable image.
- x : The quantised horizontal world co-ordinate of the event.
- y : The quantised vertical world co-ordinate of the event.
- value : A pointer to the data value in the viewable image corresponding to the event co-ordinates.
- event_code : The arbitrary event code.
- e_info : The arbitrary event information.
- f_info : The arbitrary function information pointer.
- x_lin : The quantised linear horizontal world co-ordinate (the co-ordinate prior to the transform function being called).
- y_lin : The quantised linear vertical world co-ordinate (the co-ordinate prior to the transform function being called).
- value_type : The type of the data value. This may be K_DCOMPLEX or K_UB_RGB.
- x_im : The quantised horizontal image pixel co-ordinate. 0.0 is the pixel centre.
- y_im : The quantised vertical image pixel co-ordinate. 0.0 is the pixel centre.
- x_pix : The horizontal screen pixel co-ordinate.
- y_pix : The vertical screen pixel co-ordinate.

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

- All co-ordinates are clipped to pixel boundaries.

void viewimg_PROTO_destroy_func (void *info)

Process a destroy event on a ViewableImage.

Parameters:

- info : An arbitrary function information pointer.

Returns: Nothing.
Multithreading Level: Unsafe

## Tables

viewimg_CANVAS_ATTRIBUTES List of canvas attributes for viewable images

Name | Type | Meaning
VIEWIMG_ATT_END |  | End of varargs list
VIEWIMG_ATT_AUTO_X | flag | Enable automatic horizontal scaling
VIEWIMG_ATT_AUTO_Y | flag | Enable automatic vertical scaling
VIEWIMG_ATT_AUTO_V | flag | Enable automatic intensity scaling
VIEWIMG_ATT_INT_X | flag | Force integer horizontal zoom-in/zoom-out factor
VIEWIMG_ATT_INT_Y | flag | Force integer vertical zoom-in/zoom-out factor
VIEWIMG_ATT_MAINTAIN_ASPECT | flag | Maintain data image aspect ratio
VIEWIMG_ATT_ALLOW_TRUNCATION | flag | Allow shrunken images to be truncated
VIEWIMG_ATT_ENABLE_PANNING | flag | Enable panning mode
VIEWIMG_ATT_PAN_CENTRE_X | flag | Horizontal panning centre
VIEWIMG_ATT_PAN_CENTRE_Y | flag | Horizontal panning centre
VIEWIMG_ATT_PAN_CENTRE_Y | flag | Vertical panning centre
VIEWIMG_ATT_PAN_MAGNIFICATION | unsigned int | Panner magnification

viewimg_VIMAGE_ATTRIBUTES List of attributes for viewable images

Name | Get Type | Set Type | Meaning
VIEWIMG_VATT_END |  |  | End of varargs list
VIEWIMG_VATT_TRUECOLOUR | flag * |  | Image is TrueColour
VIEWIMG_VATT_ARRAY_DESC | array_desc ** |  | The array descriptor for the image
VIEWIMG_VATT_SLICE | char ** |  | Start of the image data
VIEWIMG_VATT_HDIM | unsigned int * |  | The horizontal dimension
VIEWIMG_VATT_VDIM | unsigned int * |  | The vertical dimension
VIEWIMG_VATT_PSEUDO_INDEX | unsigned int * |  | The PseudoColour element index
VIEWIMG_VATT_RED_INDEX | unsigned int * |  | The TrueColour red element index
VIEWIMG_VATT_GREEN_INDEX | unsigned int * |  | The TrueColour green element index
VIEWIMG_VATT_BLUE_INDEX | unsigned int * |  | The TrueColour blue element index
VIEWIMG_VATT_MULTI_ARRAY | multi_array ** |  | The multi_array descriptor
VIEWIMG_VATT_DATA_SCALE | double * | double | PsueodoColour data multiplier
VIEWIMG_VATT_DATA_OFFSET | double * | double | PsueodoColour data offset
VIEWIMG_VATT_VALUE_MIN | double * | double | PseudoColour minimum value override
VIEWIMG_VATT_VALUE_MAX | double * | double | PseudoColour maximum value override

Back to Karma Home Page