grm Reference

Basic functions

This module provides access to the various plotting-related functions.

grm.plot.clear() → int[source]

Clear all plots.

This function requires GR runtime version 0.47 or higher.

grm.plot.finalize() → None[source]

Finalize the grm framework and frees resources.

This function requires GR runtime version 0.47 or higher.

grm.plot.max_plotid() → int[source]

Index of the highest active plot.

This function requires GR runtime version 0.47 or higher.

grm.plot.merge(args_container: _ArgumentContainer) → int[source]

Store the args_container into the internal, possibly clearing the internal values.

Parameters:

args_container – The container with the data to merge

Raises:

TypeError – if the args_container is not a valid grm.args._ArgumentContainer

This function requires GR runtime version 0.47 or higher.

grm.plot.merge_extended(args_container: _ArgumentContainer, hold: bool, identificator: str) → int[source]

Merge the args_container into the internal, like merge_named, but hold specifies if the internal container should not be cleared.

Parameters:

  • args_container – The argument container with the data to merge

  • hold – When True, does not clear the internal data.

  • identificator – The identificator to pass to the MERGE_END event

Raises:

TypeError – if the arguments passed are not the expected type

This function requires GR runtime version 0.47 or higher.

grm.plot.merge_hold(args_container: _ArgumentContainer) → int[source]

Merge the container while preserving the internally stored values.

Parameters:

args_container – The argument container with the data to merge

Raises:

TypeError – if the args_container is not a valid grm.args._ArgumentContainer

This function requires GR runtime version 0.47 or higher.

grm.plot.merge_named(args_container: _ArgumentContainer, identificator: str) → int[source]

Merge the container, and the MERGE_END event is called with identificator set to the argument.

Parameters:

  • args_container – The argument container with the data to merge

  • identificator – The identificator to pass to the MERGE_END event

Raises:

TypeError – if the args_container is not a valid grm.args._ArgumentContainer, or the identificator is not a string

This function requires GR runtime version 0.47 or higher.

grm.plot.plot(args_container: _ArgumentContainer) → int[source]

Update the internal data container with the given data and draw the plot after it.

Parameters:

args_container – The container with the data to merge and plot

Raises:

TypeError – if the args_container is not a valid grm.args._ArgumentContainer

This function requires GR runtime version 0.47 or higher.

grm.plot.switch(plot_id: int) → int[source]

Switches the default plot id.

Parameters:

plot_id – The plot id to switch to.

Raises:

TypeError – if plot_id is not an unsigned int.

This function requires GR runtime version 0.47 or higher.

Argument Container

This module gives access to the ArgumentContainers exposed by GRM.

It is used to pass plotting data, settings and other data to GRM.

grm.args.new(params: Dict[str, ndarray | int | float | str | dict | _ArgumentContainer | List[int | float] | List[str] | List[dict | _ArgumentContainer] | Tuple[int | float, ...] | Tuple[str, ...] | Tuple[dict | _ArgumentContainer, ...]] | None = None) → _ArgumentContainer[source]

Initialise a new argument container with optional initialization data.

Parameters:

params – Each element in this dictionary is written into the container at initialization time.

This function requires GR runtime version 0.47 or higher.

class grm.args._ArgumentContainer(ptr: c_void_p, params: Dict[str, ndarray | int | float | str | dict | _ArgumentContainer | List[int | float] | List[str] | List[dict | _ArgumentContainer] | Tuple[int | float, ...] | Tuple[str, ...] | Tuple[dict | _ArgumentContainer, ...]] | None = None)[source]
clear() → None[source]

Clear the argument container and frees all resources held by bufs.

Raises:

ValueError – if the container was already deleted.

contains(name: str) → bool[source]

If the key name is contained in the argument, then return true.

Parameters:

name – the key to check for.

Raises:

ValueError – if the container was already deleted.

delete() → None[source]

De-Initialises a argument container (e.g. clear and destroy).

property ptr: c_void_p

Return the internal pointer of the argument container. Should not be modified or otherwise dealt with, primarily for use of internal classes.

Raises:

ValueError – if the container was already deleted.

push(name: str, values_to_insert: ndarray | int | float | str | dict | _ArgumentContainer | List[int | float] | List[str] | List[dict | _ArgumentContainer] | Tuple[int | float, ...] | Tuple[str, ...] | Tuple[dict | _ArgumentContainer, ...]) → bool[source]

Pushes the argument with name to the argument container args_ptr, which should have been created using args_new.

This function also silently overwrites entries with the same name.

You can always mix int values and float values, but they will then all be converted to floats.

One-dimensional numpy.ndarray with either Float64 or Int32 can also be passed.

Multi-dimensional numpy.ndarrays with either Float64 or Int32 can also be passed, they will be passed flattened, but name _dims is populated with the shape beforehand.

The exception is if the name is absolute, relative or error where ndarrays with a shape of [2, N] are passed as nDD.

Parameters:

  • name – The key to insert.

  • values_to_insert – The data to insert.

Raises:

  • TypeError – if name or values (or the child elements of values) are of no correct type.

  • ValueError – if one of the _ArgumentContainer elements is already a child of another or the container is already deleted.

remove(name: str) → None[source]

Remove the given key name from the argument container, and frees the ressource held by it.

name in self should be false after that.

Parameters:

name – the key to remove

Raises:

ValueError – if the container was already deleted.

update(params: Dict[str, ndarray | int | float | str | dict | _ArgumentContainer | List[int | float] | List[str] | List[dict | _ArgumentContainer] | Tuple[int | float, ...] | Tuple[str, ...] | Tuple[dict | _ArgumentContainer, ...]]) → None[source]

Update the argument container with the given dictionary params, by calling self.push(k, v) on each item.

Parameters:

params – The data to set. On each element, self[k] = v is called, inserting the element.

Event system

This module provides functions to manage callbacks for the events which can happen in grm.

class grm.event.EVENT_MERGE_END[source]

This class is used to carry event data for the merge end event.

Instances of this class have the following members:

  • type (type: c_int): The event type (should be EventType.MERGE_END)

  • identificator (type: c_char_p): The optional identificator which was given using merge_named or merge_extended

class grm.event.EVENT_NEW_PLOT[source]

This class is used to carry event data for the new plot event.

Instances of this class have the following members:

  • type (type: c_int): The event type (should be EventType.NEW_PLOT)

  • plot_id (type: c_int): The plot id which has a new size

class grm.event.EVENT_SIZE[source]

This class is used to carry event data for the size event.

Instances of this class have the following members:

  • type (type: c_int): The event type (should be EventType.SIZE)

  • plot_id (type: c_int): The plot id which has a new size

  • width (type: c_int): The new width

  • height (type: c_int): The new height

class grm.event.EVENT_UPDATE_PLOT[source]

This class is used to carry event data for the update plot event.

Instances of this class have the following members:

  • type (type: c_int): The event type (should be EventType.UPDATE_PLOT)

  • plot_id (type: c_int): The plot id which has a new size

class grm.event.EventType(value)[source]

This class contains the event types which are passed to register/unregister.

grm.event.register(event_type: EventType, callback: Callable[[EVENT_NEW_PLOT], None] | Callable[[EVENT_SIZE], None] | Callable[[EVENT_UPDATE_PLOT], None] | Callable[[EVENT_MERGE_END], None]) → int[source]

Register a callback for the specified event type.

This eventually replaces an already set callback. Internally stores a reference to the callback. The callback receives a class specific to the event type, one of:

Parameters:

  • event_type – The EventType to register a callback for.

  • callback – The callback to be called if the event occurs.

Raises:

TypeError – if event_type is not an EventType.

This function requires GR runtime version 0.47 or higher.

grm.event.unregister(event_type: EventType) → int[source]

Deregister the callback for the given event type.

Parameters:

event_type – The EventType to deregister the callback from.

Raises:

TypeError – if event_type is not an EventType.

This function requires GR runtime version 0.47 or higher.

Interaction module

This module provides functions to combine gui and graphs.

grm.interaction.get_box(x1: int, y1: int, x2: int, y2: int, keep_aspect_ratio: bool) → Tuple[int, int, int, int][source]

Translate a x1, y1, x2, y2 in workstation coordinates into a box.

Raises:

  • TypeError – if the arguments have invalid types.

  • ValueError – if the c call failed.

This function requires GR runtime version 0.47 or higher.

grm.interaction.input(args_container: _ArgumentContainer) → int[source]

Perform specific actions based on user interaction with the gui.

All coordinates are integers and workstation coordinates It supports the following operation modes with the arguments needed:

reset_ranges:

  • x mouse cursor x

  • y mouse cursor y

  • key the pressed key, f.e. ‘r’ for the right button

zoom:

  • x start point x

  • y start point y

  • one of:

    • angle_delta: mouse wheel rotation angle in eights of a degree

    • factor: zoom factor

box zoom (Zooms the subplot to the selection made):

  • x1: fixed corner x

  • y1: fixed corner y

  • x2: other corner x

  • y2: other corner y

  • keep_aspect_ratio: if 1, the aspect ratio of the window is preserved

pan:

  • x: start point x

  • y: start point y

  • xshift: shift in x direction

  • yshift: shift in y direction

Parameters:

args_container – The container with one of the data sets described above set.

Raises:

TypeError – if args_container is not a valid grm.args._ArgumentContainer

This function requires GR runtime version 0.47 or higher.