grm Reference

Basic functions

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.