temapy 1.0.0__py3-none-any.whl

temapy/examples/average_as_new_sequence.py

@@ -0,0 +1,30 @@
+"""
+Test script that adds an update action to calculate the average pos of
+every sample in two sequences.
+"""
+
+from temapy.gateway import TemaGateway
+from temapy.sequences import Status
+
+
+tema_gateway = TemaGateway()
+
+
+@tema_gateway.update_action(
+    input_sequences=("p1_pos", "p2_pos"), output_sequences=("avg_pos",)
+)
+def average_per_sample(seq_1, seq_2, seq_out):
+    """
+    calculates the average pos of every sample in two sequences.
+
+    :param seq_1: the first sequence
+    :param seq_2: the second sequence
+    :param seq_out: sequence to put result in
+    :return:
+    """
+    both_sequences = zip(seq_1.samples.items(), seq_2.samples.values())
+    for (time_1, sample_1), sample_2 in both_sequences:
+        if seq_1.samples[time_1].status.is_valid():
+            seq_out.samples[time_1].data[0] = (sample_1.data[0] + sample_2.data[0]) / 2
+            seq_out.samples[time_1].data[1] = (sample_1.data[1] + sample_2.data[1]) / 2
+            seq_out.samples[time_1].status = Status.CALCULATED

temapy/gateway.py

@@ -0,0 +1,291 @@
+"""
+Module to set up a connection to a running Tema session.
+"""
+
+import argparse
+import threading
+
+from py4j.clientserver import ClientServer
+from py4j.java_gateway import DEFAULT_PORT
+from py4j.java_gateway import JavaGateway, CallbackServerParameters, GatewayParameters
+
+from temapy.sequences import Sequence
+
+
+class TemaGateway:
+    """
+    To make your script tema compatible, import and instantiate a
+    TemaGateway. Then add your wanted update actions (calculating
+    functions) using either the add_update_action function or the
+    update_action decorator.
+
+    Typical usage example:
+
+        # Establish connection
+        tema_gateway = TemaGateway()
+
+        # Register a calculation function
+        @tema_gateway.update_action(
+            input_sequences=("seq_1", "seq_2"),
+            output_sequences=("seq_3",)
+        )
+        def my_calculator(first_seq, second_seq, out_seq):
+            # your implementation
+    """
+
+    class Java:
+        """
+        This describes to Py4J that the TemaGateway implements the Java
+        interface "temapyCallbackInterface". This allows java to call the python
+        methods defined in the interface.
+
+        Setting the auto_connect argument to false means that the connection to
+        Tema will not be setup automatically and that the self.connect method
+        needs to be called to connect to Tema. this can be used to test the
+        script without running via Tema.
+        """
+
+        implements = ["se.imagesystems.python.temapyCallbackInterface"]
+
+    def __init__(self, auto_connect=True):
+        """
+        Creates a new TemaGateway that handles communication with Tema and
+        allows you to add update actions to modify Tema sequences.
+
+        :param auto_connect: if the gateway should attempt to automatically
+               connect to Tema or not.
+        """
+        self.update_actions = []
+        self.input_sequences = {}
+        self.output_sequences = {}
+        self.shutdown = threading.Event()
+        self.tema = None
+        self.connection_thread = None
+        self.port = None
+        self._parse_tema_port()
+        if auto_connect:
+            self.connect()
+
+    def connect(self):
+        """
+        Connects temapy to a running Tema application. Should only be called if
+        the script is started via Tema.
+
+        If a connection already exist this method does nothing.
+        (see request_shutdown(self))
+        :return:
+        """
+        if isinstance(self.tema, ClientServer):
+            return
+        self._setup_server()
+        self._notify_tema()
+
+    def _setup_server(self):
+        """
+        Creates a client server pair used for sending and receiving commands
+        to/from Tema.
+
+        The connection will remain active until the request_shutdown() method is
+        called.
+        :return:
+        """
+        # Start py4j Java Gateway with a callback server
+        self.tema = JavaGateway(
+            gateway_parameters=GatewayParameters(port=self.tema_port),
+            # Dynamically allocate a port for the callback server
+            callback_server_parameters=CallbackServerParameters(port=0),
+            python_server_entry_point=self,
+        )
+
+        # Gets the actually allocated port for the callback server
+        self.port = self.tema.get_callback_server().get_listening_port()
+
+    def _notify_tema(self):
+        """
+        Sends the port number of the Python server to Tema so that Tema can
+        communicate with python.
+
+        This also indicates to tema that the python process is ready to perform
+        calculations.
+        :return:
+        """
+        self.tema.entry_point.setPythonPort(self.port)
+
+    def add_update_action(self, action, *, input_sequences=(), output_sequences=()):
+        """
+        Adds an update action to be run when Tema calls for a recalculation.
+
+        The action should be a function or other callable that takes sequences
+        as input arguments matching the ones supplied in the input_sequences and
+        output_sequences arguments in the same order.
+
+        The action should refrain from changing the sequences specified as
+        input, as doing so would change the input for subsequent actions in the
+        same update. Additionally, changes to input sequences will not be sent
+        to Tema.
+
+        Changes made to any sequence specified as output will be copied back
+        into tema after all added update actions have run. If multiple actions
+        writes to the same output, they will operate on the same sequence and
+        might overwrite each other.
+
+        :param action: The action to be performed on the sequences.
+        :param input_sequences: The sequences to be used as input to the action
+        function.
+        :param output_sequences: The sequences to be used as output.
+        """
+
+        def do_action():
+            # Get the actual output and input sequences
+            in_sequences = []
+            for wanted_sequence_name in input_sequences:
+                try:
+                    in_sequences.append(self.input_sequences[wanted_sequence_name])
+                except KeyError as e:
+                    raise KeyError(
+                        f"No input sequence named {wanted_sequence_name}"
+                    ) from e
+            out_sequences = []
+            for wanted_sequence_name in output_sequences:
+                try:
+                    out_sequences.append(self.output_sequences[wanted_sequence_name])
+                except KeyError as e:
+                    raise KeyError(
+                        f"No output sequence named {wanted_sequence_name}"
+                    ) from e
+
+            # Run user action
+            action(*in_sequences, *out_sequences)
+
+        self.update_actions.append(do_action)
+
+    def update_action(self, *, input_sequences=(), output_sequences=()):
+        """
+        Decorator used to add an update action to the given sequences.
+
+        The action should be a function or other callable that takes sequences
+        as input arguments matching the ones supplied in the input_sequences and
+         output_sequences arguments in the same order.
+
+        The action should refrain from changing the sequences specified as
+        input, as doing so would change the input for subsequent actions in the
+        same update.
+
+        Changes made to any sequence specified as output will be copied back
+        into tema after all added update actions have run. If multiple actions
+        writes to the same output, they will operate on the same sequence and
+        might overwrite each other.
+
+        :param input_sequences: The sequences to be used as input to the action
+        function.
+        :param output_sequences: The sequences to be used as output.
+        """
+
+        def decorator(action):
+            self.add_update_action(
+                action,
+                input_sequences=input_sequences,
+                output_sequences=output_sequences,
+            )
+
+            def inner(*args, **kwargs):
+                action(*args, **kwargs)
+
+            return inner
+
+        return decorator
+
+    def update(self):
+        """
+        Performs all registered update actions.
+        """
+        self._read_sequences_from_tema()
+        for action in self.update_actions:
+            action()
+        self._write_sequences_to_tema()
+
+    def request_shutdown(self):
+        """
+        Requests that the python-java bridge be shutdown.
+        :return:
+        """
+
+        def wait_for_shutdown():
+            # Wait for shutdown request
+            self.shutdown.wait()
+            self.shutdown.clear()
+            self.tema.shutdown()
+
+        self.connection_thread = threading.Thread(target=wait_for_shutdown)
+        self.connection_thread.start()
+
+        self.shutdown.set()
+
+    def _read_sequences_from_tema(self):
+        """
+        Updates the sequences available to temapy with new input data from tema.
+
+        Runs every time tema calls for an update.
+        """
+        # FIXME: Future improvement to utilize the updated range to minimize
+        #  Java-Python data transfer
+        for (
+            tema_sequence_name,
+            tema_sequence,
+        ) in self.tema.entry_point.getInputSequences().items():
+            self.input_sequences[str(tema_sequence_name)] = Sequence.of_tema_sequence(
+                tema_sequence
+            )
+
+        for (
+            tema_sequence_name,
+            tema_sequence,
+        ) in self.tema.entry_point.getOutputSequences().items():
+            self.output_sequences[str(tema_sequence_name)] = Sequence.of_tema_sequence(
+                tema_sequence
+            )
+
+    def _write_sequences_to_tema(self):
+        """
+        Updates tema with the values of the sequences in temapy.
+        """
+        # FIXME: Future improvement to utilize the updated range to minimize
+        #  Java-Python data transfer
+        tema = self.tema.entry_point
+        for sequence_name, tema_sequence in tema.getOutputSequences().items():
+            if sequence_name not in self.output_sequences:
+                continue
+
+            tema_sequence_samples = tema_sequence.getSamples()
+
+            for timestamp, sample in self.output_sequences[
+                sequence_name
+            ].samples.items():
+                java_double_array = self.tema.new_array(
+                    self.tema.jvm.double, len(sample.data)
+                )
+
+                for i, data_point in enumerate(sample.data):
+                    java_double_array[i] = data_point
+
+                tema_sequence_samples[timestamp].setData(java_double_array)
+                tema_sequence_samples[timestamp].setStatus(sample.status.value)
+
+    def _parse_tema_port(self):
+        """
+        Parses the --tema_port program argument if it exists and sets the
+        self.tema_port member accordingly.
+
+        If the argument is not specified python will start its server on the
+        default port (see py4j.java_gateway.DEFAULT_PORT)
+        """
+        parser = argparse.ArgumentParser()
+        parser.add_argument(
+            "--tema_port", help="The port the java server is running on"
+        )
+        args = parser.parse_args()
+        if args.tema_port is None:
+            self.tema_port = DEFAULT_PORT
+            return
+
+        self.tema_port = int(args.tema_port)

temapy/sequences.py

@@ -0,0 +1,140 @@
+"""
+Classes to represent TEMA sequence data in Python.
+
+Users should not need to create their own sequences or samples but
+simply edit those that are provided by Temapy.
+"""
+
+from enum import Enum
+
+
+class Sequence:
+    """
+    Represents a sequence as a dict mapping a frame-index to a Sample. Also
+    provides the updated_range, i.e. the range of indexes that have changed
+    since the last update, as a tuple.
+    """
+
+    def __init__(self, samples, updated_range):
+        self.samples = samples
+        self.updated_range = updated_range
+
+    @classmethod
+    def of_tema_sequence(cls, tema_sequence):
+        """
+        Factory method to create a new sequence with data copied from the given
+        sequence from Tema.
+
+        :param tema_sequence: The sequence to copy as returned from Tema
+        :return: A copy of the Tema sequence
+        """
+        # TODO: Future improvement to utilize the updated range to
+        #  minimize Java-Python data transfer
+        samples = {}
+        for timestamp, tema_sample in tema_sequence.getSamples().items():
+            samples[timestamp] = Sample.of_tema_sample(tema_sample)
+
+        updated_range = (
+            int(tema_sequence.getUpdatedRange().start()),
+            int(tema_sequence.getUpdatedRange().stop()),
+        )
+
+        return cls(samples, updated_range)
+
+
+class Sample:
+    """
+    Represents a sample as a list of data points and a status.
+
+    For 2D positional data the data components are [x, y], i.e. data[0] will
+    give the x component and data[1] the y component.
+    """
+
+    def __init__(self, data, status):
+        self.data = data
+        # TODO: status should be represented as an enum, will be done
+        #  when Java side is being implemented.
+        self.status = status
+
+    @classmethod
+    def of_tema_sample(cls, tema_sample):
+        """
+        Factory method to create a new sample with data copied from the given
+        sample from TEMA.
+
+        NOTE: This method is not intended to be used directly when writing
+        scripts.
+
+        :param tema_sample: The sample to copy as returned from Tema.
+        :return: A copy of the Tema sample
+        """
+        data = [float(data_point) for data_point in tema_sample.getData()]
+        status = Status(tema_sample.getStatusAsInt())
+        return cls(list(data), status)
+
+
+class Status(Enum):
+    """
+    Enum for statuses compatible with Tema.
+
+    In the normal case, any sample that is not valid (see Status.is_valid())
+    should not be used for calculation.
+
+    Any sample changed by a script should usually be given the Status CALCULATED.
+    """
+
+    NONE = 1
+    """
+    No status or unknown status.
+    """
+
+    FAILED = 2
+    """
+    Failed status. The data of the Sample failed in creation and that the data 
+    might not even be readable. Is invalid and cannot be used for calculations. 
+    """
+
+    SLEEPING = 3
+    """
+    Sleeping status. The data of the Sample is currently set to be ignored for 
+    calculation. The data may be meaningful but should be considered invalid 
+    and not be used for calculations.
+    """
+
+    PREDICTED = 4
+    """
+    Predicted status. Used by trackers for failed samples that are predicted 
+    until they are either found again or declared lost. The data of the Sample 
+    may be meaningful but should be considered invalid and not be used for 
+    calculations.
+    """
+
+    MANUAL = 5
+    """
+    Manual status. The data of the Sample has been set manually and is therefore
+    considered to be valid for calculations.
+    """
+
+    CALCULATED = 6
+    """
+    Calculated status. The data of the Sample has been successfully calculated 
+    and may be used for further calculations.
+    """
+
+    INTERPOLATED = 7
+    """
+    Interpolated status. Similar to CALCULATED but the data is interpolated from
+    other Samples.
+    """
+
+    def is_valid(self):
+        """
+        Checks if the status is noe that is considered valid
+        :return: True if the Status is valid
+        """
+        return self not in [
+            Status.NONE,
+            Status.FAILED,
+            Status.SLEEPING,
+            Status.PREDICTED,
+        ]

temapy-1.0.0.dist-info/METADATA

@@ -0,0 +1,217 @@
+Metadata-Version: 2.4
+Name: temapy
+Version: 1.0.0
+Summary: Python interface for scripting with TEMA
+Author-email: Image Systems <support@imagesystems.se>
+License-Expression: Apache-2.0
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Operating System :: Microsoft :: Windows
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: py4j
+
+# TemaPy
+
+This package is designed to be used with Image Systems TEMA Platform Python
+module to enable Python scripting functionality to TEMA.
+
+For detail instructions on how to enable your scripts in TEMA see the
+corresponding help pages in TEMA Connect.
+
+## install using pip:
+
+To develop and run scripts in TEMA you need this package installed in the
+Python environment that you will use in TEMA.
+
+    pip install temapy
+
+## Getting started: Create a TEMA compatible script
+
+To create a TEMA compatible script, first import the `TemaGateway` class from
+the `gateway` module and create a `TemaGateway`.
+
+```python
+from temapy.gateway import TemaGateway
+
+gateway = TemaGateway()
+```
+
+If the script is started using TEMA the `TemaGateway` will handle the connection
+and data transfer between TemaPy and TEMA automatically. The only thing left to
+do is to write your calculation function, referred to as an "update action", and
+register it using the Gateway.
+
+Here is an example update action that takes two input sequences, and for each
+sample calculates the average value and store it in a third output sequence.
+
+```python
+def average_per_sample(seq_1, seq_2, seq_out):
+    both_sequences = zip(seq_1.samples.items(), seq_2.samples.values())
+    for (time_1, sample_1), sample_2 in both_sequences:
+        if seq_1.samples[time_1].status.is_valid():
+            seq_out.samples[time_1].data[0] = (sample_1.data[0] + sample_2.data[0]) / 2
+            seq_out.samples[time_1].data[1] = (sample_1.data[1] + sample_2.data[1]) / 2
+            seq_out.samples[time_1].status = Status.CALCULATED
+```
+
+**Note:** The output sequence is supplied as an input to the function. This is
+because TemaPy is not allowed to create new sequences, only change data in the
+sequences supplied by TEMA.
+
+There are two ways of registering your function so that TEMA will run it when
+input sequences change, either by calling the `add_update_action` method in the
+`TemaGateway` or by using the `update_action` decorator, also from the
+`TemaGateway` class.
+
+```python
+# Using the add_update_action() function
+def average_per_sample(seq_1, seq_2, seq_out):
+    ...
+
+gateway.add_update_action(average_per_sample,
+                          input_sequences=("p1_pos", "p2_pos"),
+                          output_sequences=("avg_pos",))
+
+# Using the update_action decorator
+@gateway.update_action(input_sequences=("p1_pos", "p2_pos"), output_sequences=("avg_pos",))
+def average_per_sample(seq_1, seq_2, seq_out):
+    ...
+```
+
+In both cases the `input_sequences` and `output_sequences` parameter specify
+what TEMA sequences the update action will operate on. The strings in those
+parameters should correspond with the variable names given to the sequences in
+the Python Script Setup pane in TEMA. The sequences from TEMA will then
+automatically map to the input parameters in your update action in order, first
+input sequences and then output sequences. In this example this means that the
+sequence named "p1_pos" in TEMA is mapped to the `seq_1` parameter in the
+function, "p2_pos" is mapped to `seq_2` and "avg_pos" is mapped to `out_seq`.
+
+Now your script is ready to be used in TEMA, for more information about how to
+enable your script in TEMA, see the corresponding help pages in TEMA Connect.
+
+For more details on how to work with TemaPy, continue reading below.
+Additionally, more example scripts can be found in the `temapy.examples`
+package.
+
+## The gateway
+
+The `TemaGateway` handles the connection to TEMA and allows you to access and
+manipulate data sequences specified using the TEMA Python Scripting Setup. The
+connection is handled mostly automatically as soon as an instance of
+`TemaGateway` is created.
+
+### Update actions
+
+The update actions are your calculation functions that are run each time the
+input sequences specified in TEMA are updated. This means for example that each
+update action will run again for each tracked frame as long as the script is
+active.
+
+While it is not possible to run multiple Python scripts simultaneously in TEMA,
+it is possible to add multiple update actions to the same script. Whenever TEMA
+calls for the script to update, all update actions will be executed in the order
+they were added. Any changes made to sequences in an update action will be
+carried over to any following update actions which means that it is possible to
+chain actions together.
+
+The input and output sequences used by your update actions are copies of the
+data in TEMA.
+
+The input sequences are sequences that already exists in TEMA and are added from
+a list of available sequences in TEMA. While it is possible to change an input
+sequence in your update actions, this is not recommended, as data in input
+sequences will **not** be returned to TEMA and changing input sequences might
+cause the scripts sequences to diverge from the sequences supplied by TEMA.
+
+The output sequences are created by the TEMA Scripting Module for your TemaPy
+script to edit. The output sequences will be initialized with invalid
+placeholder values for each sample and it is up to your update actions to fill
+them with new values, see the sections about sequences and samples for
+instructions on how to work with sequences.
+
+It is important to note that the separation between output and input sequences
+does not necessarily reflect their use in your update functions. Instead it is
+the distinction between the sequences that already exists in TEMA (input) and
+those that are created by the scripting module (output).
+
+## TEMA data
+
+The data available from TEMA is in the form of sequences. In TemaPy these are
+represented by the classes found in the `temapy.sequences` module.
+
+The following sections describe how the data is structured and how to work with
+it.
+
+### Sequences
+
+The `Sequence` is the data structure that your update actions will operate on.
+A sequence represents a set of measurements for each frame in the original image
+sequence in TEMA. For each frame there is a `Sample` that contains numerical
+data from that frame of the image sequence.
+
+#### updated range
+
+Each sequence also has a `updated_range` which is a tuple of two integers. These
+integers represent the first (inclusive) and last (exclusive) frame of the
+sequence that has changed since the update actions were last run. This range can
+be used to avoid unnecessary recalculations and slowdown during tracking in TEMA
+with an active script. It is also good to adjust the `updated_range` of the
+output sequences to no wider than the range of values that have been changed.
+Otherwise, it will be assumed that all frames have been updated and the sequence
+will be copied to tema in its entirety which might cause significant slow-down
+during tracking.
+
+#### Samples
+
+The `samples` attribute is a dictionary that maps a frame number, to a `Sample`.
+The `Sample` contains the data of that specific frame of the image sequence used
+in TEMA. As this is a standard Python dictionary, it supports all standard dict
+operations in Python.
+
+### Sample
+
+The `Sample` class contains data for a specific frame of the image sequence,
+
+#### Data
+
+The data of each
+`Sample` is a tuple of numerical value, each value representing a
+certain component of the data. What components are available depends on the type
+of sequence. In a 2D position sequence, for example, each `Sample` contains two
+data components, the x position and the y position (x, y).
+
+#### Status
+
+The `Status` of the `Sample` describe the nature of the `Sample` and if it
+should be used for calculations. Usually it is enough to use the
+`Status.is_valid()` method do determine if the `Sample` should be used or not.
+For more fine grade control, each `Status` is described below.
+
+**NONE:** No or unknown `Status`.
+
+**FAILED:**
+The data of the `Sample` failed in creation and that the data might not even be
+readable, will cause undefined behaviour if used and might cause the script to
+fail. Is invalid and cannot be used for calculations.
+
+**SLEEPING:**
+The data of the `Sample` is currently set to be ignored for calculation. The
+data may be meaningful but should be considered invalid and not be used for
+calculations.
+
+**PREDICTED:**
+Used by trackers for failed Samples that are predicted until they are either
+found again or declared lost. The data of the `Sample` may be meaningful but
+should be considered invalid and not be used for calculations.
+
+**MANUAL:**
+The data of the `Sample` has been set manually and is therefore considered to be
+valid for calculations.
+
+**CALCULATED:**
+The data of the `Sample` has been successfully calculated and
+may be used for further calculations.
+
+**INTERPOLATED:**
+Similar to `CALCULATED` but the data is interpolated from other Samples.

temapy-1.0.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+temapy/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+temapy/gateway.py,sha256=NmwYyd6j2sBKUMlBfpaqqzewGTbNegcnDmT2GEpB-ak,10648
+temapy/sequences.py,sha256=baSkENB9TuieU5OXGmklI3ewhPNjOHi9bJSKtfkt1y4,4292
+temapy/examples/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+temapy/examples/average_as_new_sequence.py,sha256=CjmFEkeWnwLbQl8PMt1-0Lkewi-3iFG2XTliygghuLw,1034
+temapy-1.0.0.dist-info/METADATA,sha256=9SX0wzkaNWlO8RqkWSVXWeir5O7krIX-K0yfafgNu2s,9279
+temapy-1.0.0.dist-info/WHEEL,sha256=CmyFI0kx5cdEMTLiONQRbGQwjIoR1aIYB7eCAQ4KPJ0,91
+temapy-1.0.0.dist-info/top_level.txt,sha256=vGCOwZT-j1DnKtCnzs1ytwrK6I-fks-nss1_9NB6Juk,7
+temapy-1.0.0.dist-info/RECORD,,

temapy-1.0.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (78.1.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

temapy-1.0.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+temapy