temapy 1.0.0__tar.gz → 1.2.0__tar.gz

{temapy-1.0.0 → temapy-1.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: temapy
-Version: 1.0.0
+Version: 1.2.0
 Summary: Python interface for scripting with TEMA
 Author-email: Image Systems <support@imagesystems.se>
 License-Expression: Apache-2.0
@@ -25,6 +25,11 @@ Python environment that you will use in TEMA.
 
     pip install temapy
 
+To upgrade an existing installation to a newer temapy (required when a TEMA
+release asks for a minimum version):
+
+    pip install --upgrade temapy
+
 ## Getting started: Create a TEMA compatible script
 
 To create a TEMA compatible script, first import the `TemaGateway` class from
@@ -147,8 +152,8 @@ it.
 
 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.
+sequence in TEMA. For each frame there is a sample that contains data from that
+frame of the image sequence.
 
 #### updated range
 
@@ -164,54 +169,107 @@ 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.
+The `samples` attribute is a dictionary that maps a frame number to a sample.
+As this is a standard Python dictionary, it supports all standard dict
+operations in Python. The concrete sample type depends on the sequence:
+`NumericSample` for numeric data, `OutlineSample` for outlines, and
+`LineSample` for 2D lines.
 
 ### Sample
 
-The `Sample` class contains data for a specific frame of the image sequence,
+`Sample` is the base class shared by all Temapy samples. Every sample has a
+`status`. Scripts normally work with one of the concrete subclasses below.
+
+### NumericSample
+
+The `NumericSample` class contains numeric 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).
+The data of each `NumericSample` is a list of numerical values, 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
+`NumericSample` contains two data components, the x position and the y position
+(`[x, y]`). A Length scalar uses a single component in `data[0]`.
+
+#### Outline samples
+
+An outline (chain code) input sequence contains `OutlineSample` objects instead
+of `NumericSample` objects. Each outline sample provides:
+
+- `points`: a list of `(x, y)` tuples describing the contour. Lens correction
+  and coordinate transformation have already been applied by TEMA.
+- `start`: the raw `(x, y)` starting point of the chain code.
+- `links`: the raw chain links as a string containing `U`, `D`, `L`, and `R`.
+- `status`: the sample status, used in the same way as for numeric samples.
+
+Outline sequences are currently input-only. Scripts can derive values from an
+outline and write those values to numeric output sequences. See
+`temapy.examples.outline_width` for an example.
+
+#### 2D line outputs
+
+A 2D line output uses a `LineSample`. Its `start` and `end` attributes are
+coordinate lists describing the line's two endpoints (currently `[x, y]`):
+
+```python
+line_sample.start = [x1, y1]
+line_sample.end = [x2, y2]
+line_sample.status = Status.CALCULATED
+```
+
+Choose **2D line** as the output physical type in TEMA. The line can be added
+to the Image Diagram as a distance overlay.
+
+Output sequences share a world feature named by the prefix before the first
+``_`` (for example ``point_position`` and ``point_speed`` both map to feature
+``point``). 2D line arrays and 2D distances use a line feature; other types use
+a point feature.
+
+To show the length in meters on a line overlay (and in Time Table / 2D Diagram),
+add a second output such as ``line_distance`` next to ``line`` with physical
+type **2D distance**, and write the offset components:
+
+```python
+line_distance.samples[frame].data[0] = end[0] - start[0]
+line_distance.samples[frame].data[1] = end[1] - start[1]
+line_distance.samples[frame].status = Status.CALCULATED
+```
+
+See `temapy.examples.two_points_to_line`.
 
 #### Status
 
-The `Status` of the `Sample` describe the nature of the `Sample` and if it
+The `Status` of a sample describes 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.
+`Status.is_valid()` method to 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
+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
+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
+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
+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
+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.
+Similar to `CALCULATED` but the data is interpolated from other samples.

{temapy-1.0.0 → temapy-1.2.0}/README.md

@@ -13,6 +13,11 @@ Python environment that you will use in TEMA.
 
     pip install temapy
 
+To upgrade an existing installation to a newer temapy (required when a TEMA
+release asks for a minimum version):
+
+    pip install --upgrade temapy
+
 ## Getting started: Create a TEMA compatible script
 
 To create a TEMA compatible script, first import the `TemaGateway` class from
@@ -135,8 +140,8 @@ it.
 
 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.
+sequence in TEMA. For each frame there is a sample that contains data from that
+frame of the image sequence.
 
 #### updated range
 
@@ -152,54 +157,107 @@ 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.
+The `samples` attribute is a dictionary that maps a frame number to a sample.
+As this is a standard Python dictionary, it supports all standard dict
+operations in Python. The concrete sample type depends on the sequence:
+`NumericSample` for numeric data, `OutlineSample` for outlines, and
+`LineSample` for 2D lines.
 
 ### Sample
 
-The `Sample` class contains data for a specific frame of the image sequence,
+`Sample` is the base class shared by all Temapy samples. Every sample has a
+`status`. Scripts normally work with one of the concrete subclasses below.
+
+### NumericSample
+
+The `NumericSample` class contains numeric 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).
+The data of each `NumericSample` is a list of numerical values, 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
+`NumericSample` contains two data components, the x position and the y position
+(`[x, y]`). A Length scalar uses a single component in `data[0]`.
+
+#### Outline samples
+
+An outline (chain code) input sequence contains `OutlineSample` objects instead
+of `NumericSample` objects. Each outline sample provides:
+
+- `points`: a list of `(x, y)` tuples describing the contour. Lens correction
+  and coordinate transformation have already been applied by TEMA.
+- `start`: the raw `(x, y)` starting point of the chain code.
+- `links`: the raw chain links as a string containing `U`, `D`, `L`, and `R`.
+- `status`: the sample status, used in the same way as for numeric samples.
+
+Outline sequences are currently input-only. Scripts can derive values from an
+outline and write those values to numeric output sequences. See
+`temapy.examples.outline_width` for an example.
+
+#### 2D line outputs
+
+A 2D line output uses a `LineSample`. Its `start` and `end` attributes are
+coordinate lists describing the line's two endpoints (currently `[x, y]`):
+
+```python
+line_sample.start = [x1, y1]
+line_sample.end = [x2, y2]
+line_sample.status = Status.CALCULATED
+```
+
+Choose **2D line** as the output physical type in TEMA. The line can be added
+to the Image Diagram as a distance overlay.
+
+Output sequences share a world feature named by the prefix before the first
+``_`` (for example ``point_position`` and ``point_speed`` both map to feature
+``point``). 2D line arrays and 2D distances use a line feature; other types use
+a point feature.
+
+To show the length in meters on a line overlay (and in Time Table / 2D Diagram),
+add a second output such as ``line_distance`` next to ``line`` with physical
+type **2D distance**, and write the offset components:
+
+```python
+line_distance.samples[frame].data[0] = end[0] - start[0]
+line_distance.samples[frame].data[1] = end[1] - start[1]
+line_distance.samples[frame].status = Status.CALCULATED
+```
+
+See `temapy.examples.two_points_to_line`.
 
 #### Status
 
-The `Status` of the `Sample` describe the nature of the `Sample` and if it
+The `Status` of a sample describes 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.
+`Status.is_valid()` method to 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
+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
+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
+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
+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
+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.
+Similar to `CALCULATED` but the data is interpolated from other samples.

{temapy-1.0.0 → temapy-1.2.0}/pyproject.toml

@@ -7,7 +7,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "temapy"
-version = "1.0.0"
+version = "1.2.0"
 authors = [
     { name = "Image Systems", email = "support@imagesystems.se" }
 ]
@@ -46,6 +46,7 @@ env_list = [
     "lint",
     # FIXME: Disabled to not prevent merging. We should probably do type-checking in the future
     # "type",
+    "3.14",
     "3.13",
     "3.12",
     "3.11",
@@ -67,7 +68,7 @@ commands = [
 description = "run linters"
 deps = ["pylint"]
 commands = [
-    ["pylint", { replace = "posargs", default = ["src", "scripts"], extend = true }, "--disable=fixme,too-few-public-methods, too-many-instance-attributes", ],
+    ["pylint", { replace = "posargs", default = ["src"], extend = true }, "--disable=fixme,too-few-public-methods, too-many-instance-attributes", ],
 ]
 
 
@@ -75,5 +76,5 @@ commands = [
 description = "run type checks"
 deps = ["mypy"]
 commands = [
-    ["mypy", { replace = "posargs", default = ["src", "scripts"], extend = true }],
+    ["mypy", { replace = "posargs", default = ["src"], extend = true }],
 ]

temapy-1.2.0/src/temapy/examples/outline_width.py

@@ -0,0 +1,25 @@
+"""
+Calculates the axis-aligned width of an outline for every valid sample.
+"""
+
+from temapy.gateway import TemaGateway
+from temapy.sequences import Status
+
+
+tema_gateway = TemaGateway()
+
+
+@tema_gateway.update_action(
+    input_sequences=("outline",), output_sequences=("width",)
+)
+def calculate_outline_width(outline, width):
+    """
+    Writes the difference between the largest and smallest x coordinate.
+    """
+    for frame, sample in outline.samples.items():
+        if not sample.status.is_valid() or not sample.points:
+            continue
+
+        x_coordinates = [x for x, _ in sample.points]
+        width.samples[frame].data[0] = max(x_coordinates) - min(x_coordinates)
+        width.samples[frame].status = Status.CALCULATED

temapy-1.2.0/src/temapy/examples/two_points_to_line.py

@@ -0,0 +1,32 @@
+"""
+Builds a 2D line from two point sequences, plus a 2D distance sibling for the overlay.
+"""
+
+from temapy.gateway import TemaGateway
+from temapy.sequences import Status
+
+
+tema_gateway = TemaGateway()
+
+
+@tema_gateway.update_action(
+    input_sequences=("p1", "p2"), output_sequences=("line", "line_distance")
+)
+def make_line(p1, p2, line, line_distance):
+    """
+    Writes a two-point line and its 2D distance for every frame where both points are valid.
+
+    Name the distance output with the same prefix as the line (here ``line_distance`` next to
+    ``line``) and set its physical type to **2D distance** so both share the same line feature.
+    """
+    for frame, sample_p1 in p1.samples.items():
+        sample_p2 = p2.samples[frame]
+        if sample_p1.status.is_valid() and sample_p2.status.is_valid():
+            start = [sample_p1.data[0], sample_p1.data[1]]
+            end = [sample_p2.data[0], sample_p2.data[1]]
+            line.samples[frame].start = start
+            line.samples[frame].end = end
+            line.samples[frame].status = Status.CALCULATED
+            line_distance.samples[frame].data[0] = end[0] - start[0]
+            line_distance.samples[frame].data[1] = end[1] - start[1]
+            line_distance.samples[frame].status = Status.CALCULATED

{temapy-1.0.0 → temapy-1.2.0}/src/temapy/gateway.py

@@ -89,9 +89,10 @@ class TemaGateway:
         called.
         :return:
         """
-        # Start py4j Java Gateway with a callback server
+        # Start py4j Java Gateway with a callback server.
         self.tema = JavaGateway(
-            gateway_parameters=GatewayParameters(port=self.tema_port),
+            gateway_parameters=GatewayParameters(port=self.tema_port,
+                                                 auto_convert=True),
             # Dynamically allocate a port for the callback server
             callback_server_parameters=CallbackServerParameters(port=0),
             python_server_entry_point=self,
@@ -261,16 +262,10 @@ class TemaGateway:
             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)
+                sample.write_to_tema_sample(
+                    tema_sequence_samples[timestamp]
                 )
 
-                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

temapy-1.2.0/src/temapy/sequences.py

@@ -0,0 +1,282 @@
+"""
+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 abc import ABC, abstractmethod
+from array import array
+from enum import Enum
+import sys
+
+from py4j.protocol import Py4JError
+
+
+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
+        try:
+            sample_type = str(tema_sequence.getSampleType())
+        except Py4JError:
+            # Older TEMA versions only expose numeric samples.
+            sample_type = "NUMERIC"
+        sample_factory = _SAMPLE_FACTORIES.get(sample_type, NumericSample)
+        samples = {}
+        for timestamp, tema_sample in tema_sequence.getSamples().items():
+            samples[timestamp] = sample_factory.of_tema_sample(tema_sample)
+
+        updated_range = (
+            int(tema_sequence.getUpdatedRange().start()),
+            int(tema_sequence.getUpdatedRange().stop()),
+        )
+
+        return cls(samples, updated_range)
+
+
+class Sample(ABC):
+    """
+    Base class for all Temapy samples.
+
+    Concrete sample types share a ``status`` and type-specific data attributes.
+    """
+
+    def __init__(self, status):
+        self.status = status
+
+    @classmethod
+    @abstractmethod
+    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
+        """
+
+    @abstractmethod
+    def write_to_tema_sample(self, tema_sample):
+        """
+        Copies this sample to its corresponding TEMA sample.
+
+        NOTE: This method is used internally by the gateway.
+
+        :param tema_sample: The TEMA sample to write to.
+        """
+
+
+class NumericSample(Sample):
+    """
+    Represents a numeric sample as a list of data components 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. Scalars such as Length
+    use a single component in data[0].
+    """
+
+    def __init__(self, data, status):
+        super().__init__(status)
+        self.data = data
+
+    @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)
+
+    def write_to_tema_sample(self, tema_sample):
+        """
+        Copies this numeric sample to its corresponding TEMA sample.
+
+        NOTE: This method is used internally by the gateway.
+        """
+        # auto_convert turns this list into a Java List for setData
+        tema_sample.setData(list(self.data))
+        tema_sample.setStatus(self.status.value)
+
+
+class LineSample(Sample):
+    """
+    Represents a two-point line sample.
+
+    ``start`` and ``end`` are coordinate lists, currently ``[x, y]`` for 2D
+    lines in TEMA. A line always has exactly these two endpoints.
+    """
+
+    def __init__(self, start, end, status):
+        super().__init__(status)
+        self.start = start
+        self.end = end
+
+    @classmethod
+    def of_tema_sample(cls, tema_sample):
+        """
+        Factory method to copy a line sample returned from TEMA.
+
+        NOTE: This method is not intended to be used directly when writing
+        scripts.
+        """
+        start = [float(tema_sample.getStartX()), float(tema_sample.getStartY())]
+        end = [float(tema_sample.getEndX()), float(tema_sample.getEndY())]
+        status = Status(tema_sample.getStatusAsInt())
+        return cls(start, end, status)
+
+    def write_to_tema_sample(self, tema_sample):
+        """
+        Copies this line sample to its corresponding TEMA sample.
+
+        NOTE: This method is used internally by the gateway.
+        """
+        tema_sample.setStartX(self.start[0])
+        tema_sample.setStartY(self.start[1])
+        tema_sample.setEndX(self.end[0])
+        tema_sample.setEndY(self.end[1])
+        tema_sample.setStatus(self.status.value)
+
+
+class OutlineSample(Sample):
+    """
+    Represents an outline sample.
+
+    ``points`` contains the lens-corrected and coordinate-transformed contour
+    as ``(x, y)`` tuples. ``start`` and ``links`` contain the raw chain code.
+    """
+
+    def __init__(self, points, start, links, status):
+        super().__init__(status)
+        self.points = points
+        self.start = start
+        self.links = links
+
+    @classmethod
+    def of_tema_sample(cls, tema_sample):
+        """
+        Factory method to copy an outline sample returned from TEMA.
+
+        NOTE: This method is not intended to be used directly when writing
+        scripts.
+        """
+        values = array("d")
+        values.frombytes(tema_sample.getPoints())
+        if sys.byteorder == "little":
+            values.byteswap()
+
+        points = [(values[i], values[i+1]) for i in range(0, len(values), 2)]
+        start = (float(tema_sample.getStartX()), float(tema_sample.getStartY()))
+        links = str(tema_sample.getLinks())
+        status = Status(tema_sample.getStatusAsInt())
+        return cls(points, start, links, status)
+
+    def write_to_tema_sample(self, tema_sample):
+        """
+        Outline samples are not written back to TEMA.
+
+        NOTE: This method is used internally by the gateway.
+        """
+
+
+_SAMPLE_FACTORIES = {
+    "NUMERIC": NumericSample,
+    "CHAIN_CODE": OutlineSample,
+    "LINE": LineSample,
+}
+
+
+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 → temapy-1.2.0}/src/temapy.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: temapy
-Version: 1.0.0
+Version: 1.2.0
 Summary: Python interface for scripting with TEMA
 Author-email: Image Systems <support@imagesystems.se>
 License-Expression: Apache-2.0
@@ -25,6 +25,11 @@ Python environment that you will use in TEMA.
 
     pip install temapy
 
+To upgrade an existing installation to a newer temapy (required when a TEMA
+release asks for a minimum version):
+
+    pip install --upgrade temapy
+
 ## Getting started: Create a TEMA compatible script
 
 To create a TEMA compatible script, first import the `TemaGateway` class from
@@ -147,8 +152,8 @@ it.
 
 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.
+sequence in TEMA. For each frame there is a sample that contains data from that
+frame of the image sequence.
 
 #### updated range
 
@@ -164,54 +169,107 @@ 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.
+The `samples` attribute is a dictionary that maps a frame number to a sample.
+As this is a standard Python dictionary, it supports all standard dict
+operations in Python. The concrete sample type depends on the sequence:
+`NumericSample` for numeric data, `OutlineSample` for outlines, and
+`LineSample` for 2D lines.
 
 ### Sample
 
-The `Sample` class contains data for a specific frame of the image sequence,
+`Sample` is the base class shared by all Temapy samples. Every sample has a
+`status`. Scripts normally work with one of the concrete subclasses below.
+
+### NumericSample
+
+The `NumericSample` class contains numeric 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).
+The data of each `NumericSample` is a list of numerical values, 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
+`NumericSample` contains two data components, the x position and the y position
+(`[x, y]`). A Length scalar uses a single component in `data[0]`.
+
+#### Outline samples
+
+An outline (chain code) input sequence contains `OutlineSample` objects instead
+of `NumericSample` objects. Each outline sample provides:
+
+- `points`: a list of `(x, y)` tuples describing the contour. Lens correction
+  and coordinate transformation have already been applied by TEMA.
+- `start`: the raw `(x, y)` starting point of the chain code.
+- `links`: the raw chain links as a string containing `U`, `D`, `L`, and `R`.
+- `status`: the sample status, used in the same way as for numeric samples.
+
+Outline sequences are currently input-only. Scripts can derive values from an
+outline and write those values to numeric output sequences. See
+`temapy.examples.outline_width` for an example.
+
+#### 2D line outputs
+
+A 2D line output uses a `LineSample`. Its `start` and `end` attributes are
+coordinate lists describing the line's two endpoints (currently `[x, y]`):
+
+```python
+line_sample.start = [x1, y1]
+line_sample.end = [x2, y2]
+line_sample.status = Status.CALCULATED
+```
+
+Choose **2D line** as the output physical type in TEMA. The line can be added
+to the Image Diagram as a distance overlay.
+
+Output sequences share a world feature named by the prefix before the first
+``_`` (for example ``point_position`` and ``point_speed`` both map to feature
+``point``). 2D line arrays and 2D distances use a line feature; other types use
+a point feature.
+
+To show the length in meters on a line overlay (and in Time Table / 2D Diagram),
+add a second output such as ``line_distance`` next to ``line`` with physical
+type **2D distance**, and write the offset components:
+
+```python
+line_distance.samples[frame].data[0] = end[0] - start[0]
+line_distance.samples[frame].data[1] = end[1] - start[1]
+line_distance.samples[frame].status = Status.CALCULATED
+```
+
+See `temapy.examples.two_points_to_line`.
 
 #### Status
 
-The `Status` of the `Sample` describe the nature of the `Sample` and if it
+The `Status` of a sample describes 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.
+`Status.is_valid()` method to 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
+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
+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
+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
+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
+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.
+Similar to `CALCULATED` but the data is interpolated from other samples.

{temapy-1.0.0 → temapy-1.2.0}/src/temapy.egg-info/SOURCES.txt

@@ -9,4 +9,6 @@ src/temapy.egg-info/dependency_links.txt
 src/temapy.egg-info/requires.txt
 src/temapy.egg-info/top_level.txt
 src/temapy/examples/__init__.py
-src/temapy/examples/average_as_new_sequence.py
+src/temapy/examples/average_as_new_sequence.py
+src/temapy/examples/outline_width.py
+src/temapy/examples/two_points_to_line.py

temapy-1.0.0/src/temapy/sequences.py

@@ -1,140 +0,0 @@
-"""
-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,
-        ]