The "graph1d" Package

These routines are meant to provide a high level mechanism to graph a 1-dimensional array of values. NOTE: THIS PACKAGE IS WORK IN PROGRESS. THE INTERFACE MAY CHANGE IN THE NEXT RELEASE, POSSIBLY WITHOUT NOTICE.

Library: karmagraphics
Link With: -lkarmagraphics

Functions

graph1d_init	Initialise the package for a particular canvas.
graph1d_set_canvas_attributes	Set attributes for a canvas.
graph1d_test_if_zoomed_horizontally	Test if a canvas is zoomed horizontally.
graph1d_unzoom	Unzoom a canvas.
graph1d_refresh_if_needed	Refresh a canvas if needed.
graph1d_create	Create viewable graph.
graph1d_set_vgraph_attributes	Set attributes for a viewable graph.
graph1d_set_active	Set active state for a viewable graph controlled refresh.
graph1d_set_all_inactive	Clear active state all viewable graphs controlled refresh.
graph1d_destroy	Destroy a viewable graph.
graph1d_register_destroy_func	Register destroy callback.
graph1d_get_worldcanvas	Get the world canvas for a viewable graph.
graph1d_change_draw_order	Change the draw order for a viewable graph.
graph1d_get_last	Get last viewable graph for a world canvas.
graph1d_allocate_coords	Allocate co-ordinates for a viewable graph.
graph1d_set_size	Set the size of a viewable graph.
graph1d_get_size	Get the size of a viewable graph.
graph1d_save_ascii	Save the data in a viewable graph in ASCII format.
graph1d_orthogonal_create	Create an object for later viewing of orthogonal profiles.
graph1d_orthogonal_destroy	Destroy an orthogonal profile.
graph1d_orthogonal_register_destroy_func	Register destroy callback.
graph1d_orthogonal_invalidate	Invalidate an orthogonal profile.
graph1d_orthogonal_show_trace	Show a trace.
graph1d_orthogonal_show_traces	Show a weighted, summed trace.
graph1d_orthogonal_show_boxed_trace	Show a boxed trace.
graph1d_orthogonal_configure_canvas	Configure a canvas using an orthogonal profile object.
graph1d_orthogonal_save	Save orthogonal profile data to a file.
graph1d_orthogonal_track_compute	Compute track strings.

Functions

EXPERIMENTAL FUNCTION: subject to change without notice

void graph1d_init (KWorldCanvas canvas)

This routine will initialise the graph1d 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 viewable graphs.

Parameters:

canvas : The world canvas object.

Returns: Nothing.
Multithreading Level: Unsafe

EXPERIMENTAL FUNCTION: subject to change without notice

void graph1d_set_canvas_attributes (KWorldCanvas canvas, ...)

Set attributes for a 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 GRAPH1D_CANVAS_ATT_END. See graph1d_CANVAS_ATTRIBUTES for the list of attributes.

Returns: Nothing.
Multithreading Level: Unsafe

EXPERIMENTAL FUNCTION: subject to change without notice

flag graph1d_test_if_zoomed_horizontally (KWorldCanvas canvas)

Test if a canvas is zoomed horizontally.

Parameters:

canvas : The world canvas.

Returns: TRUE if the canvas is zoomed, else FALSE.
Multithreading Level: Unsafe

EXPERIMENTAL FUNCTION: subject to change without notice

void graph1d_unzoom (KWorldCanvas canvas, flag horizontal, flag vertical, flag auto_v)

Unzoom a canvas.

Parameters:

canvas : The world canvas.
horizontal : If TRUE, the canvas is unzoomed horizontally.
vertical : If TRUE, the canvas is unzoomed vertically.
auto_v : If TRUE, the canvas is auto-scaled vertically.

Returns: Nothing.
Multithreading Level: Unsafe

EXPERIMENTAL FUNCTION: subject to change without notice

void graph1d_refresh_if_needed (KWorldCanvas canvas)

Refresh a canvas if needed.

Parameters:

canvas : The world canvas to be refreshed.

Returns: Nothing.
Multithreading Level: Unsafe

EXPERIMENTAL FUNCTION: subject to change without notice

KViewableGraph graph1d_create (KWorldCanvas canvas, unsigned int num_points, double **x, double **y, uaddr key, ...)

This routine will create a viewable graph object from two arrays of values. At a later time, this viewable graph may be made visible. This routine will not cause the canvas to be refreshed.

Parameters:

canvas : The world canvas onto which the viewable graph may be drawn. Many viewable graphs may be associated with a single canvas.
num_points : The number of points in this viewable graph.
x : The pointer to the array of horizontal values is written here. The space is automatically dealloated when the graph is destroyed.
y : The pointer to the array of vertical values is written here. The space is automatically dealloated when the graph is destroyed.
key : The key to associate with this viewable graph.
... : The list of parameter attribute-key attribute-value-ptr pairs must follow. This list must be terminated with the GRAPH1D_VGRAPH_ATT_END. See graph1d_VGRAPH_ATTRIBUTES for the list of attributes.

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

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

EXPERIMENTAL FUNCTION: subject to change without notice

void graph1d_set_vgraph_attributes (KViewableGraph vgraph, ...)

Set attributes for a viewable graph.

Parameters:

vgraph : The viewable graph.
... : The list of parameter attribute-key attribute-value-ptr pairs must follow. This list must be terminated with the GRAPH1D_VGRAPH_ATT_END. See graph1d_VGRAPH_ATTRIBUTES for the list of attributes.

Returns: Nothing.
Multithreading Level: Unsafe

EXPERIMENTAL FUNCTION: subject to change without notice

flag graph1d_set_active (KViewableGraph vgraph, flag active,flag force_refresh, flag refresh_if_changed, flag exclusive, uaddr key)

This routine will make a viewable graph active or inactive.

Parameters:

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

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

EXPERIMENTAL FUNCTION: subject to change without notice

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

This routine will make all viewable graphs 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 viewable graph changed.
key : The key to use for inactivation of viewable graphs. If this is 0 then all viewable graphs will be made inactive.

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

EXPERIMENTAL FUNCTION: subject to change without notice

void graph1d_destroy (KViewableGraph vgraph)

Destroy a viewable graph.

Parameters:

vgraph : The viewable graph.

Returns: Nothing.
Multithreading Level: Unsafe

EXPERIMENTAL FUNCTION: subject to change without notice

KCallbackFunc graph1d_register_destroy_func (KViewableGraph vgraph, void (*func) (), void *info)

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

Parameters:

vgraph : The viewable graph.
func : The function that is called when the graph is destroyed. The prototype function is graph1d_PROTO_destroy_func.
info : The arbitrary function information pointer.

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

EXPERIMENTAL FUNCTION: subject to change without notice

KWorldCanvas graph1d_get_worldcanvas (KViewableGraph vgraph)

Get the world canvas for a viewable graph.

Parameters:

vgraph : The viewable graph.

Returns: The KWorldCanvas object.
Multithreading Level: Unsafe

EXPERIMENTAL FUNCTION: subject to change without notice

void graph1d_change_draw_order (KViewableGraph vgraph, KViewableGraph position, flag before)

Change the draw order for a viewable graph.

Parameters:

vgraph : The viewable graph to move in the draw order.
position : The viewable graph to use as a reference point.
before : If TRUE, vgraph will be moved just before position (or to the start of the list if position is NULL). If FALSE, vgraph will be moved just after position (or to the end of the list if position is NULL).

Returns: Nothing.
Multithreading Level: Unsafe

EXPERIMENTAL FUNCTION: subject to change without notice

KViewableGraph graph1d_get_last (KWorldCanvas canvas)

Get last viewable graph for a world canvas.

Parameters:

canvas : The world canvas.

Returns: The viewable graph if there is one, else NULL.
Multithreading Level: Unsafe

EXPERIMENTAL FUNCTION: subject to change without notice

flag graph1d_allocate_coords (KViewableGraph vgraph, unsigned int num_coords, double **x, double **y)

Allocate co-ordinates for a viewable graph.

Parameters:

vgraph : The viewable graph.
num_points : The number of co-ordinate pairs to allocate.
x : The pointer to the array of horizontal values is written here. The space is automatically dealloated when the graph is destroyed.
y : The pointer to the array of vertical values is written here. The space is automatically dealloated when the graph is destroyed.

Returns: TRUE on success, else FALSE, indicating an allocation error.
Multithreading Level: Unsafe

EXPERIMENTAL FUNCTION: subject to change without notice

void graph1d_set_size (KViewableGraph vgraph, unsigned int num_points)

Set the size of a viewable graph.

Parameters:

vgraph : The viewable graph.
num_points : The number of valid points in the graph.

Returns: Nothing.
Multithreading Level: Unsafe

EXPERIMENTAL FUNCTION: subject to change without notice

unsigned int graph1d_get_size (KViewableGraph vgraph, double **x, double **y)

Get the size of a viewable graph.

Parameters:

vgraph : The viewable graph.
num_points : The number of points in the graph is written here.
x : The pointer to the array of horizontal values is written here. This may be NULL.
y : The pointer to the array of vertical values is written here. This may be NULL.

Returns: Nothing.
Multithreading Level: Unsafe

EXPERIMENTAL FUNCTION: subject to change without notice

flag graph1d_save_ascii (KViewableGraph vgraph, Channel channel)

Save the data in a viewable graph in ASCII format.

Parameters:

vgraph : The viewable graph.
channel : The Channel object to write to.

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

EXPERIMENTAL FUNCTION: subject to change without notice

KOrthogonalProfile graph1d_orthogonal_create (KWorldCanvas canvas,iarray array, KViewableGraph *vgraph)

Create an object for later viewing of orthogonal profiles.

Parameters:

canvas : The world canvas object where profiles will be drawn.
array : The Intelligent Array which contains the data.
vgraph : The KViewableGraph that is created is written here. This may be NULL.

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

The KOrthogonalProfile will be automatically destroyed if the canvas or Intelligent Array are destroyed.

EXPERIMENTAL FUNCTION: subject to change without notice

void graph1d_orthogonal_destroy (KOrthogonalProfile profile)

Destroy an orthogonal profile.

Parameters:

profile : The orthogonal profile.

Returns: Nothing.
Multithreading Level: Unsafe

EXPERIMENTAL FUNCTION: subject to change without notice

KCallbackFunc graph1d_orthogonal_register_destroy_func (KOrthogonalProfile profile, void (*func) (), void *info)

This routine will register a destroy function for an orthogonal profile. Many destroy functions may be registered per profile. The first function registered is the first function called upon destruction.

Parameters:

profile : The orthogonal profile.
func : The function that is called when the profile is destroyed. The prototype function is graph1d_orthogonal_PROTO_destroy_func.
info : The arbitrary function information pointer.

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

EXPERIMENTAL FUNCTION: subject to change without notice

void graph1d_orthogonal_invalidate (KOrthogonalProfile profile)

Invalidate an orthogonal profile.

Parameters:

profile : The orthogonal profile.

Returns: Nothing.
Multithreading Level: Unsafe

EXPERIMENTAL FUNCTION: subject to change without notice

void graph1d_orthogonal_show_trace (KOrthogonalProfile profile, CONST unsigned int *dim_indices, flag correct_aberration, CONST uaddr *coord_indices, uaddr refpos)

Show a trace.

Parameters:

profile : The orthogonal profile.
dim_indices : The dimension indicies. The length of this array must be one less than the number of dimensions in the array.
correct_aberration : If TRUE, attempt to correct for chromatic aberration.
coord_indices : The co-ordinate indices of the trace. The length of this array must be one less than the number of dimensions in the array.
refpos : The reference position along the profile dimension.

Returns: Nothing.
Multithreading Level: Unsafe

EXPERIMENTAL FUNCTION: subject to change without notice

void graph1d_orthogonal_show_traces (KOrthogonalProfile profile, CONST unsigned int *dim_indices, flag correct_aberration, flag sum, float global_weight, unsigned int num_traces, CONST uaddr *coord_indices, uaddr refpos, CONST float *weights)

Show a weighted, summed trace.

Parameters:

profile : The orthogonal profile.
dim_indices : The dimension indicies. The length of this array must be one less than the number of dimensions in the array.
correct_aberration : If TRUE, attempt to correct for chromatic aberration.
sum : If TRUE, the data are summed rather than averaged.
global_weight : This weight value is applied to each trace as it is combined.
num_traces : The number of traces to combine.
coord_indices : The co-ordinate indices for the traces. This is grouped into num_traces contiguous blocks of co-ordinate traces. Each block must contain num_dim - 1 co-ordinate indices.
refpos : The reference position along the profile dimension.
weights : The weights to apply to each trace as it is combined. If this is NULL no weights are applied.

Returns: Nothing.
Multithreading Level: Unsafe

EXPERIMENTAL FUNCTION: subject to change without notice

void graph1d_orthogonal_show_boxed_trace (KOrthogonalProfile profile, CONST unsigned int *dim_indices, flag sum, CONST uaddr *start_indices, CONST uaddr *stop_indices, uaddr refpos)

Show a boxed trace.

Parameters:

profile : The orthogonal profile.
dim_indices : The dimension indicies. The length of this array must be one less than the number of dimensions in the array.
sum : If TRUE the traces are summed, else they are averaged.
start_indices : The starting co-ordinate indices of the box. The length of this array must be one less than the number of dimensions in the array.
stop_indices : The stopping co-ordinate indices of the box. The length of this array must be one less than the number of dimensions in the array.
refpos : The reference position along the profile dimension.

Returns: Nothing.
Multithreading Level: Unsafe
Note:

This function will attempt to correct for chromatic aberration.

EXPERIMENTAL FUNCTION: subject to change without notice

void graph1d_orthogonal_configure_canvas (KOrthogonalProfile profile)

Configure a canvas using an orthogonal profile object.

Parameters:

profile : The orthogonal profile.

Returns: Nothing.
Multithreading Level: Unsafe

EXPERIMENTAL FUNCTION: subject to change without notice

void graph1d_orthogonal_save (KWorldCanvas canvas, CONST char *filename)

Save orthogonal profile data to a file.

Parameters:

canvas : The world canvas.
filename : The filename to save to.

Returns: Nothing.
Multithreading Level: Unsafe
Note:

If there is no orthogonal profile data, the KViewableGraph that is drawn last (i.e. on top) is used instead.

EXPERIMENTAL FUNCTION: subject to change without notice

flag graph1d_orthogonal_track_compute (KWorldCanvas canvas, double x, double y, double x_lin, char x_string[STRING_LENGTH], char y_string[STRING_LENGTH])

Compute track strings.

Parameters:

canvas : The world canvas.
x : The horizontal world co-ordinate of the event.
y : The vertical world co-ordinate of the event.
x_lin : The horizontal linear co-ordinate of the event.
x_string : The X co-ordinate information will be written here.
y_string : The Y co-ordinate information will be written here.

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

Back to Karma Home Page

Contact: Richard Gooch
Web Development: Ariel Internet Services