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:

• EVENT_NEW_PLOT

• EVENT_UPDATE_PLOT

• EVENT_SIZE

• EVENT_MERGE_END

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.