openspeleo-lib 0.0.1__py3-none-any.whl

openspeleo_lib/__init__.py

@@ -0,0 +1,8 @@
+#!/usr/bin/env python
+
+import importlib.metadata
+
+__version__ = importlib.metadata.version("openspeleo_lib")
+
+# Initialize the logger
+from openspeleo_lib import logger  # noqa: F401

openspeleo_lib/commands/__init__.py

@@ -0,0 +1 @@
+#!/usr/bin/env python

openspeleo_lib/commands/convert.py

@@ -0,0 +1,69 @@
+import argparse
+import logging
+import pathlib
+
+from openspeleo_lib.interfaces import ArianeInterface
+
+logger = logging.getLogger(__name__)
+logger.setLevel(logging.INFO)
+
+
+def convert(args):
+    parser = argparse.ArgumentParser(
+        prog="convert", description="Convert a Survey File"
+    )
+    parser.add_argument(
+        "-i",
+        "--input_file",
+        type=pathlib.Path,
+        required=True,
+        help="Path to the TML file to be validated",
+    )
+
+    parser.add_argument(
+        "-o",
+        "--output_file",
+        type=pathlib.Path,
+        default=None,
+        required=True,
+        help="Path to save the converted file at.",
+    )
+
+    parser.add_argument(
+        "-w",
+        "--overwrite",
+        action="store_true",
+        help="Allow overwrite an already existing file.",
+        default=False,
+    )
+
+    parser.add_argument(
+        "-f",
+        "--format",
+        type=str,
+        choices=["json"],
+        required=True,
+        help="Conversion format used.",
+    )
+
+    parsed_args = parser.parse_args(args)
+
+    input_file: pathlib.Path = parsed_args.input_file
+    output_file: pathlib.Path = parsed_args.output_file
+
+    if not input_file.exists():
+        raise FileNotFoundError(f"File not found: `{input_file}`")
+
+    if output_file.exists() and not parsed_args.overwrite:
+        raise FileExistsError(
+            f"The file `{output_file}` already existing. "
+            "Please pass the flag `--overwrite` to ignore."
+        )
+
+    match input_file.suffix:
+        case ".tml":
+            survey = ArianeInterface.from_file(input_file)
+        case _:
+            raise ValueError(f"Unsupported file format: `{input_file.suffix}`")
+
+    survey.to_json(filepath=output_file)

openspeleo_lib/commands/main.py

@@ -0,0 +1,33 @@
+# #!/usr/bin/env python3
+
+import argparse
+from importlib.metadata import entry_points
+
+import openspeleo_lib
+
+
+def main():
+    registered_commands = entry_points(group="openspeleo_lib.actions")
+
+    parser = argparse.ArgumentParser(prog="openspeleo_lib")
+    parser.add_argument(
+        "-v",
+        "--version",
+        action="version",
+        version=f"%(prog)s version: {openspeleo_lib.__version__}",
+    )
+    parser.add_argument(
+        "command",
+        choices=registered_commands.names,
+    )
+    parser.add_argument(
+        "args",
+        help=argparse.SUPPRESS,
+        nargs=argparse.REMAINDER,
+    )
+
+    args = argparse.Namespace()
+    parser.parse_args(namespace=args)
+
+    main_fn = registered_commands[args.command].load()
+    return main_fn(args.args)

openspeleo_lib/commands/validate_tml.py

@@ -0,0 +1,32 @@
+import argparse
+import logging
+import pathlib
+
+from openspeleo_lib.interfaces import ArianeInterface
+
+logger = logging.getLogger(__name__)
+logger.setLevel(logging.INFO)
+
+
+def validate(args):
+    parser = argparse.ArgumentParser(
+        prog="validate_tml", description="Validate a TML file"
+    )
+    parser.add_argument(
+        "-i",
+        "--input_file",
+        type=pathlib.Path,
+        required=True,
+        help="Path to the TML file to be validated",
+    )
+
+    parsed_args = parser.parse_args(args)
+
+    input_file = parsed_args.input_file
+
+    if not input_file.exists():
+        raise FileNotFoundError(f"File not found: `{input_file}`")
+
+    _ = ArianeInterface.from_file(input_file)
+
+    logger.info("Filepath: `%(input_file)s` ... VALID", {"input_file": input_file})

openspeleo_lib/constants.py

@@ -0,0 +1,15 @@
+# Length for the shot field `name` used by compass
+OSPL_SHOTNAME_MIN_LENGTH = 2
+OSPL_SHOTNAME_MAX_LENGTH = 20
+OSPL_SHOTNAME_DEFAULT_LENGTH = 6
+
+# Length for the section field `name`
+OSPL_SECTIONNAME_MIN_LENGTH = 2
+OSPL_SECTIONNAME_MAX_LENGTH = 50
+
+
+# Maximum retry attempts for any while loop
+OSPL_MAX_RETRY_ATTEMPTS = 100
+
+# Filenames
+ARIANE_DATA_FILENAME = "Data.xml"

openspeleo_lib/debug_utils.py

@@ -0,0 +1,12 @@
+from pathlib import Path
+
+import orjson
+
+
+def write_debugdata_to_disk(data: dict, filepath: Path) -> None:
+    with filepath.open(mode="w") as f:
+        f.write(
+            orjson.dumps(
+                data, None, option=(orjson.OPT_INDENT_2 | orjson.OPT_SORT_KEYS)
+            ).decode("utf-8")
+        )

openspeleo_lib/enums.py

@@ -0,0 +1,26 @@
+from enum import Enum
+
+
+class CustomEnum(Enum):
+    @classmethod
+    def reverse(cls, name):
+        return cls._value2member_map_[name]
+
+
+class ArianeProfileType(CustomEnum):
+    VERTICAL = "VERTICAL"
+    HORIZONTAL = "HORIZONTAL"
+    PERPENDICULAR = "PERPENDICULAR"
+    BISECTION = "BISECTION"
+
+
+class ArianeShotType(CustomEnum):
+    REAL = "REAL"
+    START = "START"
+    VIRTUAL = "VIRTUAL"
+    CLOSURE = "CLOSURE"
+
+
+class LengthUnits(CustomEnum):
+    FEET = "FT"
+    METERS = "M"

openspeleo_lib/errors.py

@@ -0,0 +1,6 @@
+class DuplicateValueError(ValueError):
+    pass
+
+
+class MaxRetriesError(RuntimeError):
+    pass

openspeleo_lib/generators.py

@@ -0,0 +1,91 @@
+import contextlib
+import random
+from collections import defaultdict
+from typing import Any
+from typing import NewType
+
+from openspeleo_lib.constants import OSPL_MAX_RETRY_ATTEMPTS
+from openspeleo_lib.constants import OSPL_SHOTNAME_DEFAULT_LENGTH
+from openspeleo_lib.constants import OSPL_SHOTNAME_MAX_LENGTH
+from openspeleo_lib.errors import DuplicateValueError
+from openspeleo_lib.errors import MaxRetriesError
+
+
+class UniqueValueGenerator:
+    _used_values = None
+    VOCAB = "ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789"
+
+    def __init__(self):
+        raise NotImplementedError("This class should not be instantiated.")
+
+    @classmethod
+    @contextlib.contextmanager
+    def activate_uniqueness(cls):
+        try:
+            cls._used_values = defaultdict(set)
+            yield
+        finally:
+            cls._used_values = None
+
+    @classmethod
+    def register(cls, vartype: type, value: Any) -> None:
+        """Register the generated value."""
+        if cls._used_values is None:  # uniqueness is not activated
+            return
+
+        value = vartype(value)
+
+        if value in cls._used_values[vartype]:
+            raise DuplicateValueError(
+                f"Value `{value}` for type `{vartype}` has already been registered."
+            )
+
+        cls._used_values[vartype].add(value)
+
+    @classmethod
+    def get(cls, vartype: type, **kwargs) -> Any:
+        """Get unique value for an object primary key."""
+        iter_idx = 0
+        while True:
+            iter_idx += 1
+            if iter_idx > OSPL_MAX_RETRY_ATTEMPTS:
+                raise MaxRetriesError(
+                    "Impossible to find an available value to use. "
+                    "Max retry attempts reached: "
+                    f"{OSPL_MAX_RETRY_ATTEMPTS}"
+                )
+            try:
+                if vartype is str or (
+                    isinstance(vartype, NewType) and vartype.__supertype__ is str
+                ):
+                    value = cls._generate_str(**kwargs)
+
+                elif vartype is int or (
+                    isinstance(vartype, NewType) and vartype.__supertype__ is int
+                ):
+                    value = cls._generate_int(
+                        known_values=(
+                            cls._used_values[vartype] if cls._used_values else []
+                        )
+                    )
+                else:
+                    raise TypeError(f"Unsupported type: `{vartype}`")
+
+                cls.register(vartype=vartype, value=value)
+                break
+            except DuplicateValueError:
+                continue
+
+        return value
+
+    @classmethod
+    def _generate_str(cls, str_len: int = OSPL_SHOTNAME_DEFAULT_LENGTH) -> str:
+        if str_len > OSPL_SHOTNAME_MAX_LENGTH:
+            raise ValueError(
+                f"Maximum length allowed: {OSPL_SHOTNAME_MAX_LENGTH}, received: {str_len}"  # noqa: E501
+            )
+        return "".join(random.choices(cls.VOCAB, k=str_len))
+
+    @classmethod
+    def _generate_int(cls, known_values: list[int] | set[int]) -> str:
+        return max(known_values, default=0) + 1

openspeleo_lib/interfaces/__init__.py

@@ -0,0 +1,3 @@
+from openspeleo_lib.interfaces.ariane.interface import ArianeInterface
+
+__all__ = ["ArianeInterface"]

openspeleo_lib/interfaces/ariane/decoding.py

@@ -0,0 +1,122 @@
+import contextlib
+import logging
+from pathlib import Path
+
+from openspeleo_core.legacy import deserialize_xmlfield_to_dict
+
+# from openspeleo_core.legacy import remove_none_values
+# from openspeleo_core.legacy import apply_key_mapping
+from openspeleo_core.mapping import apply_key_mapping
+
+from openspeleo_lib.debug_utils import write_debugdata_to_disk
+from openspeleo_lib.interfaces.ariane.name_map import ARIANE_INVERSE_MAPPING
+
+logger = logging.getLogger(__name__)
+DEBUG = False
+
+
+def ariane_decode(data: dict) -> dict:
+    # ===================== DICT FORMATTING TO OSPL ===================== #
+
+    # 1. Apply key mapping: From Ariane to OSPL
+    data = apply_key_mapping(data, mapping=ARIANE_INVERSE_MAPPING)
+
+    if DEBUG:
+        write_debugdata_to_disk(data, Path("data.import.step01-mapped.json"))
+
+    # 1.1 Formatting Top Lvl - ariane unit is lowercase - OSPL unit is uppercase
+    data["unit"] = data["unit"].upper()
+
+    # 2. Collapse `ariane_viewer_layers`:
+    # - BEFORE: data["ariane_viewer_layers"]["layer_list"]
+    # - AFTER:  data["ariane_viewer_layers"]
+    data["ariane_viewer_layers"] = data["ariane_viewer_layers"].pop("layer_list")
+
+    if DEBUG:
+        write_debugdata_to_disk(data, Path("data.import.step02-collapsed.json"))
+
+    # 3. Sort `shots` into `sections`
+    sections = {}
+    for shot in data.pop("data")["shots"]:
+        # 3.1 Collapse `radius_vectors`:
+        # - BEFORE: shot["shape"]["radius_collection"]["radius_vector"]
+        # - AFTER:  shot["shape"]["radius_vectors"]
+        with contextlib.suppress(KeyError):
+            shot["shape"]["radius_vectors"] = shot["shape"].pop("radius_collection")[
+                "radius_vector"
+            ]
+
+        # Formatting the color back to OSPL format
+        shot["color"] = shot.pop("color").replace("0x", "#")
+
+        # 3.2 Separate shots into sections
+        try:
+            if (section_name := shot.pop("section_name")) not in sections:
+                sections[section_name] = {
+                    "section_name": section_name,
+                    "date": shot.pop("date", None),
+                    "shots": [],
+                }
+                if ariane_explorer_field := shot.pop("explorers"):
+                    _data = deserialize_xmlfield_to_dict(ariane_explorer_field)
+
+                    if isinstance(_data, str):
+                        _data = {"explorers": _data}
+                    else:
+                        _data = apply_key_mapping(_data, mapping=ARIANE_INVERSE_MAPPING)
+
+                    sections[section_name].update(_data)
+
+            else:
+                for key in ["date", "explorers"]:
+                    with contextlib.suppress(KeyError):
+                        _value = shot.pop(key)
+
+                        if key == "explorers" and isinstance(_value, str):
+                            _data = deserialize_xmlfield_to_dict(_value)
+
+                            if isinstance(_data, dict):
+                                _data = apply_key_mapping(
+                                    _data,
+                                    mapping=ARIANE_INVERSE_MAPPING,
+                                )
+                            else:
+                                _data = {key: _value}
+                        else:
+                            _data = {key: _value}
+
+                        for sub_key, value in _data.items():
+                            if sections[section_name][sub_key] != value:
+                                logger.warning(
+                                    "Section `%(section)s` has different `%(key)s`: "
+                                    "`%(section_val)s` != `%(shot_val)s`",
+                                    {
+                                        "section": section_name,
+                                        "key": sub_key,
+                                        "section_val": sections[section_name][sub_key],
+                                        "shot_val": value,
+                                    },
+                                )
+
+            with contextlib.suppress(KeyError):
+                if not isinstance(
+                    (radius_vectors := shot["shape"]["radius_vectors"]),
+                    (tuple, list),
+                ):
+                    shot["shape"]["radius_vectors"] = [radius_vectors]
+
+            sections[section_name]["shots"].append(shot)
+
+        except KeyError as e:
+            logging.warning(
+                "Incomplete shot data: `%(shot)s` - Error: %(error)s",
+                {"shot": shot, "error": e},
+            )
+            continue  # if data is incomplete, skip this shot
+
+    data["sections"] = list(sections.values())
+
+    if DEBUG:
+        write_debugdata_to_disk(data, Path("data.import.step03-sections.json"))
+
+    return data

openspeleo_lib/interfaces/ariane/encoding.py

@@ -0,0 +1,75 @@
+import contextlib
+import logging
+from pathlib import Path
+
+from openspeleo_core.legacy import serialize_dict_to_xmlfield
+
+# from openspeleo_core.legacy import apply_key_mapping
+from openspeleo_core.mapping import apply_key_mapping
+
+from openspeleo_lib.debug_utils import write_debugdata_to_disk
+from openspeleo_lib.interfaces.ariane.name_map import ARIANE_MAPPING
+
+logger = logging.getLogger(__name__)
+DEBUG = False
+
+
+def ariane_encode(data: dict) -> dict:
+    # ==================== FORMATING FROM OSPL TO TML =================== #
+
+    # 1. Formatting Unit - ariane unit is lowercase - OSPL unit is uppercase
+    data["unit"] = data["unit"].lower()
+
+    if DEBUG:
+        write_debugdata_to_disk(data, Path("data.export.step01.json"))
+
+    # 2. Flatten sections into shots
+    shots = []
+    for section in data.pop("sections"):
+        for shot in section.pop("shots"):
+            shot["section_name"] = section["section_name"]
+            shot["date"] = section["date"]
+
+            # ~~~~~~~~~~~~~~~~ Processing Explorers/Surveyors ~~~~~~~~~~~~~~~ #
+            _explo_data = {}
+            for key in ["explorers", "surveyors"]:
+                if (_value := section[key]) is not None:
+                    _explo_data[key] = _value
+
+            # In case only "explorer" data exists - Ariane doesn't store in format XML
+            if len(_explo_data) == 1:
+                with contextlib.suppress(KeyError):
+                    _explo_data = _explo_data["explorers"]
+
+            if isinstance(_explo_data, dict):
+                _explo_data = apply_key_mapping(_explo_data, mapping=ARIANE_MAPPING)
+
+            shot["explorers"] = serialize_dict_to_xmlfield(_explo_data)
+            # --------------------------------------------------------------- #
+
+            radius_vectors = shot["shape"].pop("radius_vectors")
+            shot["shape"]["radius_collection"] = {"radius_vector": radius_vectors}
+            shot["color"] = shot.pop("color").replace("#", "0x")
+
+            shots.append(shot)
+
+    data["data"] = {"shots": shots}
+
+    if DEBUG:
+        write_debugdata_to_disk(data, Path("data.export.step02.json"))
+
+    # 3. Restore ArianeViewerLayer => Layers[LayerList] = [Layer1, Layer2, ...]
+    data["ariane_viewer_layers"] = {"layer_list": data.pop("ariane_viewer_layers")}
+
+    if DEBUG:
+        write_debugdata_to_disk(data, Path("data.export.step03.json"))
+
+    # 4. Apply key mapping in reverse order
+    data = apply_key_mapping(data, mapping=ARIANE_MAPPING)
+
+    if DEBUG:
+        write_debugdata_to_disk(data, Path("data.export.mapped.json"))
+
+    # ------------------------------------------------------------------- #
+
+    return data

openspeleo_lib/interfaces/ariane/enums_cls.py

@@ -0,0 +1,45 @@
+#!/usr/bin/env python
+
+from enum import IntEnum
+from pathlib import Path
+from typing import Self
+
+
+class BaseEnum(IntEnum):
+    @classmethod
+    def from_str(cls, value: str) -> Self:
+        try:
+            return cls[value.upper()]
+        except KeyError as e:
+            raise ValueError(f"Unknown value: {value.upper()}") from e
+
+
+class ArianeFileType(BaseEnum):
+    TML = 0
+    TMLU = 1
+
+    @classmethod
+    def from_path(cls, filepath: Path | str) -> Self:
+        filepath = Path(filepath)
+
+        try:
+            return cls.from_str(filepath.suffix[1:])
+
+        except ValueError as e:
+            raise TypeError(e) from e
+
+
+class UnitType(BaseEnum):
+    METRIC = 0
+    IMPERIAL = 1
+
+
+class ProfileType(BaseEnum):
+    VERTICAL = 0
+
+
+class ShotType(BaseEnum):
+    REAL = 1
+    VIRTUAL = 2
+    START = 3
+    CLOSURE = 4

openspeleo_lib/interfaces/ariane/interface.py

@@ -0,0 +1,106 @@
+import logging
+import zipfile
+from pathlib import Path
+
+from openspeleo_core import ariane_core
+
+from openspeleo_lib.constants import ARIANE_DATA_FILENAME
+from openspeleo_lib.debug_utils import write_debugdata_to_disk
+from openspeleo_lib.interfaces.ariane.decoding import ariane_decode
+from openspeleo_lib.interfaces.ariane.encoding import ariane_encode
+from openspeleo_lib.interfaces.ariane.enums_cls import ArianeFileType
+from openspeleo_lib.interfaces.base import BaseInterface
+from openspeleo_lib.models import Survey
+
+logger = logging.getLogger(__name__)
+DEBUG = False
+
+
+class ArianeInterface(BaseInterface):
+    @classmethod
+    def to_file(cls, survey: Survey, filepath: Path) -> None:
+        if (
+            filetype := ArianeFileType.from_path(filepath=filepath)
+        ) != ArianeFileType.TML:
+            raise TypeError(
+                f"Unsupported fileformat: `{filetype.name}`. "
+                f"Expected: `{ArianeFileType.TML.name}`"
+            )
+
+        data = survey.model_dump(mode="json")
+
+        # ------------------------------------------------------------------- #
+
+        if DEBUG:
+            write_debugdata_to_disk(data, Path("data.export.before.json"))
+
+        data = ariane_encode(data)
+
+        if DEBUG:
+            write_debugdata_to_disk(data, Path("data.export.after.json"))
+
+        # ------------------------------------------------------------------- #
+
+        # =========================== DICT TO XML =========================== #
+
+        # xml_str = dict_to_xml(data)
+        xml_str = ariane_core.dict_to_xml_str(data, root_name="CaveFile")
+
+        if DEBUG:
+            with Path("data.export.xml").open(mode="w") as f:
+                f.write(xml_str)
+
+        # ========================== WRITE TO DISK ========================== #
+
+        with zipfile.ZipFile(filepath, "w", compression=zipfile.ZIP_DEFLATED) as zf:
+            logging.debug(
+                "Exporting %(filetype)s File: `%(filepath)s`",
+                {"filetype": filetype.name, "filepath": filepath},
+            )
+            zf.writestr(ARIANE_DATA_FILENAME, xml_str)
+
+    @classmethod
+    def _from_file(cls, filepath: str | Path) -> Survey:
+        # ========================= INPUT VALIDATION ======================== #
+
+        if (
+            filetype := ArianeFileType.from_path(filepath=filepath)
+        ) != ArianeFileType.TML:
+            raise TypeError(
+                f"Unsupported fileformat: `{filetype.name}`. "
+                f"Expected: `{ArianeFileType.TML.name}`"
+            )
+
+        logging.debug(
+            "Loading %(filetype)s File: `%(filepath)s`",
+            {"filetype": filetype.name, "filepath": filepath},
+        )
+
+        # ------------------------------------------------------------------- #
+
+        # =========================== XML TO DICT =========================== #
+
+        match filetype:
+            case ArianeFileType.TML:
+                data = ariane_core.load_ariane_tml_file_to_dict(path=filepath)[
+                    "CaveFile"
+                ]
+
+            case _:
+                raise NotImplementedError(
+                    f"Not supported yet - Format: `{filetype.name}`"
+                )
+
+        # ------------------------------------------------------------------- #
+
+        if DEBUG:
+            write_debugdata_to_disk(data, Path("data.import.before.json"))
+
+        data = ariane_decode(data)
+
+        if DEBUG:
+            write_debugdata_to_disk(data, Path("data.import.after.json"))
+
+        # ------------------------------------------------------------------- #
+
+        return Survey.model_validate(data)