plexus-python-pulse-common 1.1.75__py3-none-any.whl

plexus/pulse/common/__init__.py

@@ -0,0 +1,6 @@
+import importlib.metadata
+
+try:
+    __version__ = importlib.metadata.version("plexus-python-pulse-common")
+except importlib.metadata.PackageNotFoundError:
+    __version__ = "unknown"

plexus/pulse/common/carto/OSMFile.py

@@ -0,0 +1,259 @@
+from typing import Any, Self
+
+import lxml.etree
+
+from plexus.pulse.common.carto.OSMNode import OSMNode
+from plexus.pulse.common.carto.OSMTags import OSMTags
+from plexus.pulse.common.carto.OSMWay import OSMWay
+from plexus.pulse.common.utils.gisutils import Coord, Proj
+
+
+class OSMFile(object):
+    @classmethod
+    def load_file(cls, path: str, proj: Proj | None) -> Self:
+        """
+        Loads OSM from file given the path
+
+        :param path: path of OSM file
+        :param proj: cartographic projection
+
+        :return: an OSM file instance
+        """
+        root = lxml.etree.parse(path).getroot()
+
+        nodes = {}
+        ways = {}
+        for elem in root:
+            if elem.attrib.get("action") == "delete":
+                continue
+
+            if elem.tag == "node":
+                # Parse an OSM node
+                node_id = int(elem.attrib["id"])
+                tags = {}
+                for child in elem:
+                    if child.tag == "tag":
+                        k = child.attrib["k"]
+                        v = child.attrib["v"]
+                        tags[k] = v
+
+                tags = OSMTags.from_any_tags(tags)
+                coord = Coord.from_latlon(
+                    float(elem.attrib["lat"]),
+                    float(elem.attrib["lon"]),
+                    tags.getfloat("z", 0.0),
+                    proj,
+                )
+
+                nodes[node_id] = OSMNode(node_id, coord, tags)
+
+            elif elem.tag == "way":
+                # Parse an OSM way
+                way_id = int(elem.attrib["id"])
+
+                tags = {}
+                node_ids = []
+                for child in elem:
+                    if child.tag == "tag":
+                        k = child.attrib["k"]
+                        v = child.attrib["v"]
+                        tags[k] = v
+                    elif child.tag == "nd":
+                        node_id = int(child.attrib.get("ref"))
+                        node_ids.append(node_id)
+
+                tags = OSMTags.from_any_tags(tags)
+
+                ways[way_id] = OSMWay(way_id, node_ids, tags)
+
+        return OSMFile(nodes, ways)
+
+    @classmethod
+    def from_coords(cls, coords: list[Coord], way_tags: dict[str, Any] = None) -> Self:
+        """
+        Constructs a single-way OSM file from the given coords
+
+        :param coords: coords on a single way
+        :param way_tags: tags of the corresponding way
+
+        :return: OSM file contains one way
+        """
+        osm = OSMFile()
+        osm.add_way_from_coords(coords, way_tags or {})
+
+        return osm
+
+    @classmethod
+    def from_coords_list(cls, coords_list: list[list[Coord]], way_tags_list: list[dict[str, Any]] = None) -> Self:
+        """
+        Constructs a multi-way OSM file from the given coords
+
+        :param coords_list: coords of each way
+        :param way_tags_list: tags of each corresponding way
+
+        :return: OSM file contains multiple ways
+        """
+        osm = OSMFile()
+
+        if not way_tags_list or len(way_tags_list) != len(coords_list):
+            for coords in coords_list:
+                osm.add_way_from_coords(coords)
+        else:
+            for coords, way_tags in zip(coords_list, way_tags_list):
+                osm.add_way_from_coords(coords, way_tags or {})
+
+        return osm
+
+    def __init__(self, nodes: dict[int, OSMNode] = None, ways: dict[int, OSMWay] = None):
+        """
+        Represents an editable general purpose OSM file
+
+        :param nodes: nodes
+        :param ways: ways
+        """
+        self.nodes: dict[int, OSMNode] = {}
+        self.ways: dict[int, OSMWay] = {}
+
+        self.next_node_id = 1
+        self.next_way_id = 1
+
+        if nodes:
+            self.nodes = nodes
+            self.next_node_id = max(nodes.keys()) + 1
+        if ways:
+            self.ways = ways
+            self.next_way_id = max(ways.keys()) + 1
+
+    def add_node(self, node: OSMNode) -> OSMNode:
+        """
+        Adds the given node
+
+        :param node: the node to be added
+
+        :return: added node
+        """
+        self.nodes[node.node_id] = node
+        if node.node_id >= self.next_node_id:
+            self.next_node_id = node.node_id + 1
+        return node
+
+    def add_node_from_coord(self, coord: Coord, tags: dict[str, Any] = None) -> OSMNode:
+        """
+        Adds node given the coord and tags
+
+        :param coord: coord of the node
+        :param tags: tags of the node
+
+        :return: added node
+        """
+        return self.add_node(OSMNode(self.next_node_id, coord, OSMTags.from_any_tags(tags)))
+
+    def add_way(self, way: OSMWay) -> OSMWay:
+        """
+        Adds the given way
+
+        :param way: the way to be added
+
+        :return: added way
+        """
+        self.ways[way.way_id] = way
+        if way.way_id >= self.next_way_id:
+            self.next_way_id = way.way_id + 1
+        return way
+
+    def add_way_from_coords(self, coords: list[Coord], tags: dict[str, Any] = None) -> OSMWay:
+        """
+        Adds way given the coords of the nodes and tags
+
+        :param coords: coords of the nodes on the way
+        :param tags: tags of the way
+
+        :return: added way
+        """
+        return self.add_way_from_nodes(coords, tags)
+
+    def add_way_from_node_ids(self, node_ids: list[int], tags: dict[str, Any] = None) -> OSMWay:
+        """
+        Adds way given the ids of the nodes and tags
+
+        :param node_ids: ids of the nodes on the way
+        :param tags: tags of the way
+
+        :return: added way
+        """
+        return self.add_way_from_nodes(node_ids, tags)
+
+    def add_way_from_nodes(self, elements: list[OSMNode | Coord | int], tags: dict[str, Any] = None) -> OSMWay:
+        """
+        Adds way given list of the nodes, the coords, or the ids of the nodes and tags
+
+        :param elements: a list of the nodes, the coords, or the ids of the nodes on the way
+        :param tags: tags of the way
+
+        :return: added way
+        """
+        node_ids = []
+        for elem in elements:
+            if isinstance(elem, OSMNode):
+                node_ids.append(self.add_node_from_coord(elem.coord, elem.tags.tags).node_id)
+            elif isinstance(elem, Coord):
+                node_ids.append(self.add_node_from_coord(elem, {}).node_id)
+            else:
+                node_ids.append(elem)
+        return self.add_way(OSMWay(self.next_way_id, node_ids, OSMTags.from_any_tags(tags)))
+
+    def write(self, filename: str):
+        """
+        Writes this OSM file instance to the given file name
+
+        :param filename: file path to write into
+        """
+        root = lxml.etree.Element("osm")
+        root.attrib.update({
+            "version": "0.6",
+            "generator": "Plexus",
+        })
+
+        for _, node in self.nodes.items():
+            node_elem = lxml.etree.Element("node")
+            node_elem.attrib.update(
+                {
+                    "id": str(node.node_id),
+                    "lat": str(node.coord.lat),
+                    "lon": str(node.coord.lon),
+                    "version": "1",
+                }
+            )
+
+            for k, v in node.tags.items():
+                tag_elem = lxml.etree.Element("tag")
+                tag_elem.attrib.update({"k": str(k), "v": str(v)})
+                node_elem.append(tag_elem)
+
+            root.append(node_elem)
+
+        for _, way in self.ways.items():
+            way_elem = lxml.etree.Element("way")
+            way_elem.attrib.update(
+                {
+                    "id": str(way.way_id),
+                    "version": "1",
+                }
+            )
+
+            for k, v in way.tags.items():
+                tag_elem = lxml.etree.Element("tag")
+                tag_elem.attrib.update({"k": str(k), "v": str(v)})
+                way_elem.append(tag_elem)
+
+            for node_id in way.node_ids:
+                nd_elem = lxml.etree.Element("nd")
+                nd_elem.attrib.update({"ref": str(node_id)})
+                way_elem.append(nd_elem)
+
+            root.append(way_elem)
+
+        s = lxml.etree.tostring(root, pretty_print=True, encoding="unicode")
+
+        with open(filename, "w") as fh:
+            fh.write(s)

plexus/pulse/common/carto/OSMNode.py

@@ -0,0 +1,25 @@
+from plexus.common.utils.strutils import repr_data
+
+from plexus.pulse.common.carto.OSMTags import OSMTags
+from plexus.pulse.common.utils.gisutils import Coord
+
+
+class OSMNode(object):
+    """
+    Represents node in OSM
+    """
+
+    def __init__(self, node_id: int, coord: Coord, tags: OSMTags):
+        """
+        Creates an instance from the given node id, coord, and tags
+
+        :param node_id: id
+        :param coord: node coordinate
+        :param tags: tags
+        """
+        self.node_id = node_id
+        self.coord = coord
+        self.tags = tags
+
+    def __str__(self):
+        return repr_data(self)

plexus/pulse/common/carto/OSMTags.py

@@ -0,0 +1,101 @@
+import datetime
+from typing import Any, Self
+
+from plexus.common.utils.strutils import repr_data, str_conv
+
+
+class OSMTags(object):
+    """
+    Represents tag in OSM
+    """
+
+    @classmethod
+    def from_any_tags(cls, any_tags: dict[str, Any] = None) -> Self:
+        """
+        Creates an instance from any-typed tags by automatically inferring data types
+
+        :param any_tags: tags with any-typed values
+
+        :return: OSM tag instance
+        """
+        if any_tags is None:
+            return OSMTags({})
+        return OSMTags({k: str_conv(v) for k, v in any_tags.items()})
+
+    def __init__(self, tags: dict[str, Any]):
+        """
+        Creates an instance from the given tags
+
+        :param tags: given tags
+        """
+        self.tags = tags
+
+    def __str__(self):
+        return repr_data(self)
+
+    def __iter__(self):
+        return self.tags.__iter__()
+
+    def __getitem__(self, k: str):
+        return self.tags.__getitem__(k)
+
+    def items(self):
+        return self.tags.items()
+
+    def set(self, key: str, value: Any) -> Any:
+        old_value = self.tags.get(key)
+        self.tags[key] = str_conv(value)
+        return old_value
+
+    def get(self, key: str, default: Any | None = None) -> Any | None:
+        return self.tags.get(key, default)
+
+    def getint(self, key: str, default: int | None = None) -> int | None:
+        value = self.tags.get(key, default)
+        if isinstance(value, int) and not isinstance(value, bool):
+            return value
+        if default is None:
+            return None
+        if isinstance(default, int) and not isinstance(default, bool):
+            return default
+        raise TypeError("type of either the value or the given default is incompatible, should be 'int'")
+
+    def getfloat(self, key: str, default: float | None = None) -> float | None:
+        value = self.tags.get(key, default)
+        if isinstance(value, float):
+            return value
+        if default is None:
+            return None
+        if isinstance(default, float):
+            return default
+        raise TypeError("type of either the value or the given default is incompatible, should be 'float'")
+
+    def getboolean(self, key: str, default: bool | None = None) -> bool | None:
+        value = self.tags.get(key, default)
+        if isinstance(value, bool):
+            return value
+        if default is None:
+            return None
+        if isinstance(default, bool):
+            return default
+        raise TypeError("type of either the value or the given default is incompatible, should be 'bool'")
+
+    def getdatetime(self, key: str, default: datetime.datetime | None = None) -> datetime.datetime | None:
+        value = self.tags.get(key, default)
+        if isinstance(value, datetime.datetime):
+            return value
+        if default is None:
+            return None
+        if isinstance(default, datetime.datetime):
+            return default
+        raise TypeError("type of either the value or the given default is incompatible, should be 'datetime.datetime'")
+
+    def getstring(self, key: str, default: str | None = None) -> str | None:
+        value = self.tags.get(key, default)
+        if isinstance(value, str):
+            return value
+        if default is None:
+            return None
+        if isinstance(default, str):
+            return default
+        raise TypeError("type of either the value or the given default is incompatible, should be 'str'")

plexus/pulse/common/carto/OSMWay.py

@@ -0,0 +1,24 @@
+from plexus.common.utils.strutils import repr_data
+
+from plexus.pulse.common.carto.OSMTags import OSMTags
+
+
+class OSMWay(object):
+    """
+    Represents way in OSM
+    """
+
+    def __init__(self, way_id: int, node_ids: list[int], tags: OSMTags):
+        """
+        Creates an instance from the given way id, node ids, and tags
+
+        :param way_id: id
+        :param node_ids: nodes ids
+        :param tags: tags
+        """
+        self.way_id = way_id
+        self.node_ids = node_ids
+        self.tags = tags
+
+    def __str__(self):
+        return repr_data(self)

plexus/pulse/common/carto/__init__.py

@@ -0,0 +1,11 @@
+__all__ = [
+    "OSMFile",
+    "OSMNode",
+    "OSMTags",
+    "OSMWay",
+]
+
+from plexus.pulse.common.carto.OSMFile import OSMFile
+from plexus.pulse.common.carto.OSMNode import OSMNode
+from plexus.pulse.common.carto.OSMTags import OSMTags
+from plexus.pulse.common.carto.OSMWay import OSMWay

plexus/pulse/common/resources/tags/__init__.py

@@ -0,0 +1,35 @@
+from pathlib import Path
+
+import markdown_it as mdit
+import yaml
+from plexus.common.utils.funcutils import singleton
+from plexus.common.utils.jsonutils import JsonObject
+
+__all__ = [
+    "predefined_tagset_specs",
+]
+
+
+@singleton
+def predefined_tagset_specs() -> list[tuple[Path, JsonObject]]:
+    # Register simple constructors for !markdown tags yaml.load can parse them.
+    def markdown_constructor(loader: yaml.Loader, node: yaml.ScalarNode | yaml.MappingNode):
+        text = loader.construct_scalar(node)
+        tokens = mdit.MarkdownIt().parse(text)
+        for token in tokens:
+            if token.type.startswith("heading"):
+                raise ValueError("markdown content in tagset specifications cannot contain headings.")
+        return {
+            "type": "markdown",
+            "text": text,
+        }
+
+    yaml.SafeLoader.add_constructor("!markdown", markdown_constructor)
+
+    def load():
+        root = Path(__file__).parent
+        for path in root.glob("**/*.tagset.yaml"):
+            text = path.read_text(encoding="utf-8")
+            yield path, yaml.load(text, yaml.SafeLoader)
+
+    return list(load())

plexus/pulse/common/resources/tags/unittest-1.0.0.tagset.yaml

@@ -0,0 +1,98 @@
+$namespace: "unittest"
+$version: "1.0.0"
+# language=markdown
+$desc: !markdown |
+  **Unit Test Tagset**
+  
+  A collection of tags designed for annotating and categorizing data in unit tests. This tagset includes categories
+  for camera views, radar views, LiDAR views, environmental conditions, and roadway characteristics. Each tag is
+  defined with a description that provides context for its use in unit testing scenarios, helping to ensure that
+  test cases are accurately annotated and can be easily understood by developers and testers.
+$def:
+  anchored_tags:
+    &anchored_tags
+    anchored:
+      # language=markdown
+      $desc: !markdown |
+        Anchored tags that describe specific perspectives or viewpoints from which data is captured. These tags are
+        typically associated with sensor data and provide critical context for understanding the scene and the
+        information being analyzed. For example, camera views may include front center, front left, front right, side
+        left, side right, rear left, and rear right perspectives, while radar and LiDAR views may include unified,
+        bumper center, bumper left, bumper right, and similar perspectives.
+      $schema:
+        type: object
+        properties:
+          dummy_property:
+            description: "This is a dummy property that serves as a placeholder for the actual properties that would be defined under the anchored tags."
+            type: string
+        additionalProperties: true
+    another_anchored:
+      # language=markdown
+      $desc: !markdown |
+        Another set of anchored tags that describe specific perspectives or viewpoints from which data is captured.
+        These tags may be used in different contexts or for different types of sensors, but they serve a similar
+        purpose in providing critical context for understanding the scene and the information being analyzed.
+$tags:
+  level_1_tag:
+    $desc: "This is a level 1 tag that provides a high-level categorization for the data."
+    $schema:
+      type: object
+      properties:
+        dummy_property:
+          description: "This is a dummy property that serves as a placeholder for the actual properties that would be defined under this level 1 tag."
+          type: string
+      additionalProperties: true
+    level_2_tag:
+      $desc: "This is a level 2 tag that provides a more specific categorization for the data."
+      level_3_tag: { $desc: "level 3 tag description", <<: *anchored_tags }
+      another_level_3_tag: { $desc: "another level 3 tag description" }
+    another_level_2_tag:
+      $desc: "This is another level 2 tag that provides a different specific categorization for the data."
+      $schema:
+        type: object
+        properties:
+          dummy_property:
+            description: "This is a dummy property that serves as a placeholder for the actual properties that would be defined under this level 2 tag."
+            type: object
+            properties:
+              dummy_sub_property:
+                description: "This is a dummy sub-property that serves as a placeholder for the actual sub-properties that would be defined under this dummy property."
+                type: string
+            additionalProperties: false
+        required: [ dummy_property ]
+        additionalProperties: true
+      <<: *anchored_tags
+  another_level_1_tag:
+    # language=markdown
+    $desc: !markdown |
+      This is another level 1 tag that provides a different high-level categorization for the data. It may be used
+      to group data based on different criteria or characteristics, such as environmental conditions, roadway
+      characteristics, or other relevant factors that are important for unit testing scenarios.
+    $schema:
+      type: object
+      properties:
+        dummy_elements:
+          description: "This is a dummy array property that serves as a placeholder for the actual array properties that would be defined under this level 1 tag."
+          type: array
+          items:
+            type: integer
+            minimum: 0
+          minItems: 1
+          maxItems: 3
+      required: [ dummy_elements ]
+      additionalProperties: true
+    level_2_tag:
+      # language=markdown
+      $desc: !markdown |
+        This is a level 2 tag that provides a more specific categorization for the data under the second level 1 tag.
+        It may be used to further refine the categorization based on specific criteria or characteristics relevant to
+        the second level 1 tag, such as different types of environmental conditions or roadway characteristics.
+      level_3_tag:
+        # language=markdown
+        $desc: !markdown |
+          This is a level 3 tag that provides an even more specific categorization for the data under the level 2 tag
+          of the second level 1 tag. It may be used to further refine the categorization based on very specific
+          criteria or characteristics relevant to the level 2 tag, such as specific weather conditions, road types,
+          or other detailed factors that are important for unit testing scenarios.
+        level_4_tag:
+          $desc: "This is a level 4 tag that provides an even more specific categorization for the data under the level 3 tag. Actually, you can have as many levels as you want, but for the sake of this example, we will stop at level 4."