RodTracker.backend.logger

Class and methods used in RodTracked GUI for manipulation with particles coordinate data and logging the resulting actions.

Author: Adrian Niemann (adrian.niemann@ovgu.de)

Date: 2022-2024

class Action[source]

Bases: QListWidgetItem

Base class for all Actions that are loggable by an ActionLogger.

abstract __str__()[source]: Returns a string representation of the action.

property frame: int: Property holding the frame on which this Action was performed.

invert()[source]: Generates an inverted version of the Action (for redoing), None if the Action is not invertible.

property inverted: Returns a ‘plain’ inverted version of the action without any coupled actions.

property parent_id: str: The ID of the object that is responsible for (reverting) this action.

to_save()[source]: Gives information for saving this action, None, if it’s not savable.

abstract undo(rods: Iterable[RodNumberWidget] | None)[source]: Triggers events to revert this action.

class ActionLogger(parent_id, *args, **kwargs)[source]

Bases: QObject

Logs actions performed on its associated GUI object.

Keeps track of actions performed on/by a GUI object that is associated with it. It provides a list of the performed actions to a LoggerWidget for display in the GUI. It is also used to trigger reverting of these actions. Do NOT create instances of this class directly but let an instance of the LoggerWidget class do that, if the logged actions shall be displayed in the GUI.

Parameters:

*args – Positional arguments for the QObject superclass.
**kwargs – Keyword arguments for the QObject superclass.

Signals

undo_action
undone_action
added_action
notify_unsaved
request_saving
data_changed

Slots

undo_last()
actions_saved()
redo_last()

parent_id

ID of the GUI object from which actions are logged. It must be human readable as it is used for labelling the actions displayed in the GUI.

Type:: str

logged_actions

A list of all actions performed/logged with this instance (saved and unsaved).

Type:: List[Action]

unsaved_changes

A list of all actions performed/logged with this instance that are savable but currently unsaved.

Type:: List[Action]

repeatable_changes

An ordered list of all currently redoable/repeatable actions that were logged with this instance.

Type:: List[Action]

frame

Frame number that is currently relevant to the object this logger is associated with. Default is None.

Type:: int

actions_saved()[source]

All unsaved actions were saved.

Hint

Emits

notify_unsaved

add_action(last_action: Action) → None[source]

Registers the actions performed by its parent and propagates them for visual display in the GUI.

Parameters:: last_action (Action)

Hint

Emits

added_action
data_changed
notify_unsaved

added_action

Notifies that this object logged the Action from the payload.

Type:: pyqtSignal(Action)

data_changed

Notifies, if this object logged/undid/redid something that changed the displayed data.

Type:: pyqtSignal(Action)

discard_changes()[source]

Discards and reverts all unsaved changes made.

Hint

Emits

data_changed (potentially repeatedly)
notify_unsaved
undo_action (potentially repeatedly)
undone_action (potentially repeatedly)

notify_unsaved

Notifies, if this objects attribute unsaved_changes changes from empty to being filled with one or more items (True) or from filled to being empty (False). The parent_id is added to the payload.

Type:: pyqtSignal(bool, str)

redo_last(parent_id: str) → None[source]

De-registers the last undone action recorded and triggers its undo-(actually redo-)process.

Parameters:: parent_id (str)

Hint

Emits

added_action
data_changed
notify_unsaved
undo_action
unsaved_changes

register_undone(undone_action: Action)[source]

Lets the logger know that an action was undone without using its undo method(s).

Parameters:: undone_action (Action)

Hint

Emits

data_changed
notify_unsaved
undone_action

request_saving

Requests the saving of any unsaved changes.

True -> permanent saving

False -> temporary saving

Type:: pyqtSignal(bool)

undo_action

Requests the reverting of the Action that is given as the payload.

Type:: pyqtSignal(Action)

undo_last(parent_id: str) → None[source]

De-registers the last unsaved action recorded and triggers its undo process.

Parameters:: parent_id (str)

Hint

Emits

data_changed
notify_unsaved
undo_action

undone_action

Notifies that the Action in the payload has been reverted.

Type:: pyqtSignal(Action)

class ChangeRodPositionAction(old_rod: RodNumberWidget, new_position: List[int], *args, **kwargs)[source]

Bases: Action

Class to represent the change of a rod’s position as a loggable action.

Parameters:

old_rod (RodNumberWidget) – A copy of the rod whose position was changed, prior to the change.
new_postion (List[int]) – The newly set starting and ending points of the rod, i.e. [x1, y1, x2, y2].
*args (iterable) – Positional arguments for the QListWidgetItem superclass.
**kwargs (dict) – Keyword arguments for the QListWidgetItem superclass.

rod

A copy of the rod whose position was changed, prior to the change.

Type:: RodNumberWidget

new_pos

The newly set starting and ending points of the rod.

Type:: List[int]

action

Default is “Rod position updated”.

Type:: str

invert()[source]

Generates an inverted version of the ChangeRodPositionAction (for redoing).

Returns:: ChangeRodPositionAction

to_save()[source]

Generates a data representation of this action for saving.

Returns:: dict – Available fields: (“rod_id”, “cam_id”, “frame”, “color”, “position”)

undo(rods: List[RodNumberWidget] | None = None) → List[RodNumberWidget][source]

Triggers events to revert this action.

Parameters:: rods (List[RodNumberWidget]) – A list of RodNumberWidget in which should be the originally changed rod(s).
Returns:: List[RodNumberWidget]
Raises:: Exception –

class ChangedRodNumberAction(old_rod: RodNumberWidget, new_id: int, coupled_action: Action | None = None, *args, **kwargs)[source]

Bases: Action

Class to represent a change of the rod number as a loggable action.

Parameters:

rod (RodNumberWidget) – A copy of the rod whose number is changed.
new_id (int) – The new rod number of the changed rod.
coupled_action (Action, optional) – The instance of an Action that is performed at the same time with this and must be reverted as well, if this Action is reverted. For example when the numbers of two rods are exchanged. (Default is None)
*args (iterable) – Positional arguments for the QListWidgetItem superclass.
**kwargs (dict) – Keyword arguments for the QListWidgetItem superclass.

rod

A copy of the rod whose number is changed.

Type:: RodNumberWidget

new_id

The new rod number of the changed rod.

Type:: int

action

Description of what kind of action was performed. (Default is “Changed rod”)

Type:: str

coupled_action

The instance of an Action that is performed at the same time with this and must be reverted as well, if this Action is reverted.

Type:: Union[Action, None]

invert()[source]

Generates an inverted version of the ChangedRodNumberAction (for redoing).

Returns:: ChangedRodNumberAction

property inverted: Returns a ‘plain’ inverted version of the action without any coupled actions.

to_save()[source]

Generates a data representation of this action for saving.

Returns:: dict – Available fields: (“rod_id”, “cam_id”, “frame”, “color”, “position”)

undo(rods: List[RodNumberWidget]) → List[RodNumberWidget][source]

Triggers events to revert this action.

Parameters:: rods (List[RodNumberWidget]) – A list of RodNumberWidget in which should be the originally changed rod(s).
Returns:: List[RodNumberWidget]

class CreateRodAction(new_rod: RodNumberWidget, coupled_action: Action | ChangedRodNumberAction | None = None, *args, **kwargs)[source]

Bases: Action

Class to represent the creation of a new rod as a loggable action.

Parameters:

new_rod (RodNumberWidget) – A copy of the rod which was created.
*args (iterable) – Positional arguments for the QListWidgetItem superclass.
**kwargs (dict) – Keyword arguments for the QListWidgetItem superclass.

rod

A copy of the rod which was created.

Type:: RodNumberWidget

action

Default is “Created new rod”.

Type:: str

invert()[source]

Generates an inverted version of the CreateRodAction (for redoing).

Returns:: DeleteRodAction

property inverted: Returns a ‘plain’ inverted version of the action without any coupled actions.

to_save()[source]

Generates a data representation of this action for saving.

Returns:: dict – Available fields: (“rod_id”, “cam_id”, “frame”, “color”, “position”)

undo(rods: List[RodNumberWidget] | None = None) → List[RodNumberWidget][source]

Triggers events to revert this action.

Parameters:: rods (List[RodNumberWidget]) – A list of RodNumberWidget in which should be the created rod.
Returns:: List[RodNumberWidget]
Raises:: Exception –

class DeleteData(data: DataFrame, parent_id: str | None = None, *args, **kwargs)[source]

Bases: Action

invert()[source]: Generates an inverted version of the Action (for redoing), None if the Action is not invertible.

to_save()[source]: Gives information for saving this action, None, if it’s not savable.

undo(rods: Iterable[RodNumberWidget] | None = None)[source]: Do NOT use for this type of Action.

class DeleteRodAction(old_rod: RodNumberWidget, coupled_action: Action | ChangedRodNumberAction | None = None, *args, **kwargs)[source]

Bases: Action

Class to represent the deletion of a rod as a loggable action.

Parameters:

old_rod (RodNumberWidget) – A copy of the rod that is deleted.
coupled_action (Union[Action, ChangedRodNumberAction], optional) – The instance of an Action that is performed at the same time with this and must be reverted as well, if this Action is reverted. (Default is None)
*args (iterable) – Positional arguments for the QListWidgetItem superclass.
**kwargs (dict) – Keyword arguments for the QListWidgetItem superclass.

rod

A copy of the rod whose position was changed, prior to the change.

Type:: RodNumberWidget

action

Description of what kind of action was performed. (Default is “Deleted rod”)

Type:: str

coupled_action

The instance of an Action that is performed at the same time with this and must be reverted as well, if this Action is reverted.

Type:: Union[Action, ChangeRodNumberAction, None]

invert()[source]

Generates an inverted version of the DeleteRodAction (for redoing).

Returns:: ChangeRodPositionAction

property inverted: Returns a ‘plain’ inverted version of the action without any coupled actions.

to_save()[source]

Generates a data representation of this action for saving.

Returns:: dict – Available fields: (“rod_id”, “cam_id”, “frame”, “color”, “position”)

undo(rods: List[RodNumberWidget] | None = None)[source]

Triggers events to revert this action.

Parameters:: rods (List[RodNumberWidget]) – A list of RodNumberWidget in which should be the originally changed rod(s).
Returns:: List[RodNumberWidget]

class FileAction(path: Path, action: FileActions, file_num=None, cam_id=None, parent_id: str | None = None, *args, **kwargs)[source]

Bases: Action

Class to represent a loggable action that was performed on a file.

Parameters:

path (str) – Path to the file that this action describes.
action (FileActions)
file_num (int, optional) – Number of the image file that was loaded. It will be displayed to the user, if it was set. (Default is None)
cam_id (str, optional) – The objects ID on which behalf this action was done. This is necessary for displaying it to the user. (Default is None)
parent_id (str, optional) – The ID of the object that is responsible for (reverting) this action. (Default is None)
*args (iterable) – Positional arguments for the QListWidgetItem superclass.
**kwargs (dict) – Keyword arguments for the QListWidgetItem superclass.

action

Description of what kind of action was performed.

Type:: FileActions

file

Path to the file that this action describes.

Type:: str

file_num

Number of the image file that was loaded. It will be displayed to the user, if it was set.

Type:: Union[int, None]

cam_id

The objects ID on which behalf this action was done. This is necessary for displaying it to the user.

Type:: str

property parent_id: The ID of the object that is responsible for (reverting) this action.

undo(rods=None)[source]: Triggers events to revert this action.

class FileActions(value)[source]

Bases: Enum

Helper class holding all valid kinds of FileActions.

SAVE

String representing the base of a saving to file action.

Type:: str

LOAD_IMAGES

String representing the base of a loaded images action.

Type:: str

OPEN_IMAGE

Deprecated since version 0.1.0: Should not be used anymore, because it clutters the displayed log of performed actions.

Type:: str

MODIFY

Deprecated since version 0.1.0: Should not used be anymore, because all changes are made in RAM. Use SAVE instead.

Type:: str

LOAD_RODS

String representing the base of a loaded rod position data action.

Type:: str

exception NotInvertableError[source]

Bases: Exception

Raised when a not invertable action is attempted to be inverted.

class NumberChangeActions(value)[source]

Bases: Enum

Helper class holding valid kinds of rod number changes.

ALL

Indicates a switch of rod numbers in all cameras from the current frame to the last frame of the dataset.

Type:: int

ALL_ONE_CAM

Indicates a switch of rod numbers in the currently displayed camera from the current frame to the last frame of the dataset.

Type:: int

ONE_BOTH_CAMS

Indicates a switch of rod numbers in all cameras for the current frame only.

Type:: int

CURRENT

Indicates a switch of rod numbers in the current camera only and the current frame only.

Type:: int

class NumberExchange(mode: NumberChangeActions, previous_id: int, new_id: int, color: str, frame: int, cam_id: str | None = None)[source]

Bases: Action

invert()[source]

Generates an inverted version of this action(for redoing).

Returns:: NumberExchange

to_save()[source]: The operation is already ‘saved’ as it directly modifies the main dataframe.

undo(rods: List[RodNumberWidget])[source]: Triggers events to revert this action.

class PermanentRemoveAction(rod_quantity: int, *args, **kwargs)[source]

Bases: Action

Action to describe permanent deletion of a rod from a dataset.

Parameters:

rod_quantity (int) – Number of rods (rows) have been deleted.
*args (iterable) – Positional arguments for the QListWidgetItem superclass.
**kwargs (dict) – Keyword arguments for the QListWidgetItem superclass.

undo(rods: Iterable[RodNumberWidget] | None)[source]: Triggers events to revert this action.

class PruneLength(old_rods: RodNumberWidget | List[RodNumberWidget], new_positions: List[List[int]], adjustment: float, *args, **kwargs)[source]

Bases: Action

Class to represent the pruning of a rods length as a loggable action.

Parameters:

old_rod (RodNumberWidget) – A copy of the rod whose position was changed, prior to the change.
new_postion (List[int]) – The newly set starting and ending points of the rod, i.e. [x1, y1, x2, y2].
*args (iterable) – Positional arguments for the QListWidgetItem superclass.
**kwargs (dict) – Keyword arguments for the QListWidgetItem superclass.

rod

A copy of the rod whose position was changed, prior to the change.

Type:: RodNumberWidget

new_pos

The newly set starting and ending points of the rod.

Type:: [int]

action

Default is “Rod length pruned: “.

Type:: str

invert()[source]

Generates an inverted version of this action(for redoing).

Returns:: PruneLength

to_save()[source]

Generates a data representation of this action for saving.

Returns:: dict – Available fields: (“rod_id”, “cam_id”, “frame”, “color”, “position”)

undo(rods: List[RodNumberWidget] | None = None) → List[RodNumberWidget][source]

Triggers events to revert this action.

Parameters:: rods (List[RodNumberWidget]) – A list of RodNumberWidget in which should be the originally changed rod(s).
Returns:: List[RodNumberWidget]
Raises:: Exception –

qt_error_handler(mode: QtMsgType, context: QMessageLogContext, msg: str)[source]: Handler for logging uncaught Qt exceptions during the program flow.