rails49-r49 0.1.0__tar.gz

rails49_r49-0.1.0/.gitignore

@@ -0,0 +1,6 @@
+.pnpm-store/
+node_modules/
+dist/
+.venv/
+__pycache__/
+packages/r49/LICENSE

rails49_r49-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Bernhard Boser
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

rails49_r49-0.1.0/PKG-INFO

@@ -0,0 +1,82 @@
+Metadata-Version: 2.5
+Name: rails49-r49
+Version: 0.1.0
+Summary: Read .r49 layout archives
+Project-URL: Repository, https://github.com/rails49/r49
+Project-URL: Issues, https://github.com/rails49/r49/issues
+License-Expression: MIT
+Requires-Python: >=3.10
+Requires-Dist: pydantic>=2.11
+Description-Content-Type: text/markdown
+
+# rails49-r49
+
+Reads `.r49` railroad layout archives in Python: a zip holding a `manifest.json`
+plus the layout photographs it describes. The format is defined in
+[FORMAT.md](https://github.com/rails49/r49/blob/main/FORMAT.md); this package is a
+reader of it, and agrees with the TypeScript package
+[`@rails49/r49`](https://github.com/rails49/r49/tree/main/packages/r49) on every
+[conformance case](https://github.com/rails49/r49/tree/main/conformance).
+
+Read-only: it loads, validates and fits archives, and never writes one.
+
+## Interface
+
+See
+[`src/r49/__init__.py`](https://github.com/rails49/r49/blob/main/packages/r49-py/src/r49/__init__.py),
+the package's public surface.
+Anything not exported there is internal and may change without notice.
+
+The scale table and the vocabulary are read from the TypeScript package's
+[`data.json`](https://github.com/rails49/r49/blob/main/packages/r49/src/data.json),
+linked into the package as `src/r49/data.json`; no value of them is declared
+in code. The sdist holds a copy of the file in place of the link.
+
+## Example
+
+```python
+import r49
+
+archive = r49.load("layout.r49")          # a path, or the archive's bytes
+manifest = archive.manifest
+print(manifest.layout.name, manifest.layout.scale)
+
+result = r49.calibration_fit(manifest)
+print(result.dpt, result.residual)        # None where the fit cannot answer
+for left_out in result.left_out:
+    print(left_out.index, left_out.reason)
+
+jpeg = archive.image(manifest.images[0].filename)
+for mismatch in archive.image_mismatches():   # empty when the images match
+    print(mismatch.rule, mismatch.filename)
+
+r49.is_known_class("stock.loco.steam")    # True
+```
+
+A refusal is an `r49.R49Error` whose `rule` is the format rule id broken, such
+as `manifest/unknown-key`. The id is the contract; the message is not. An
+archive whose images and manifest disagree still loads; `image_mismatches()`
+lists each disagreement under `images/missing` or `images/orphan`.
+`r49.parse_manifest` reads a bare `manifest.json`, which is exempt from the zip
+and image rules.
+
+A car label's `class` is `class_` in Python; the manifest key stays `class`.
+
+## Build and test
+
+Managed with [uv](https://docs.astral.sh/uv/):
+
+```sh
+uv sync --locked
+uv run pytest            # the conformance cases and the reader's own tests
+uv run ruff check .
+uv run black --check .
+uv run pyright
+uv build                 # the sdist, then the wheel from it
+```
+
+Installed with `pip install rails49-r49`.
+
+## Licence
+
+[MIT](https://github.com/rails49/r49/blob/main/LICENSE-MIT).

rails49_r49-0.1.0/README.md

@@ -0,0 +1,71 @@
+# rails49-r49
+
+Reads `.r49` railroad layout archives in Python: a zip holding a `manifest.json`
+plus the layout photographs it describes. The format is defined in
+[FORMAT.md](https://github.com/rails49/r49/blob/main/FORMAT.md); this package is a
+reader of it, and agrees with the TypeScript package
+[`@rails49/r49`](https://github.com/rails49/r49/tree/main/packages/r49) on every
+[conformance case](https://github.com/rails49/r49/tree/main/conformance).
+
+Read-only: it loads, validates and fits archives, and never writes one.
+
+## Interface
+
+See
+[`src/r49/__init__.py`](https://github.com/rails49/r49/blob/main/packages/r49-py/src/r49/__init__.py),
+the package's public surface.
+Anything not exported there is internal and may change without notice.
+
+The scale table and the vocabulary are read from the TypeScript package's
+[`data.json`](https://github.com/rails49/r49/blob/main/packages/r49/src/data.json),
+linked into the package as `src/r49/data.json`; no value of them is declared
+in code. The sdist holds a copy of the file in place of the link.
+
+## Example
+
+```python
+import r49
+
+archive = r49.load("layout.r49")          # a path, or the archive's bytes
+manifest = archive.manifest
+print(manifest.layout.name, manifest.layout.scale)
+
+result = r49.calibration_fit(manifest)
+print(result.dpt, result.residual)        # None where the fit cannot answer
+for left_out in result.left_out:
+    print(left_out.index, left_out.reason)
+
+jpeg = archive.image(manifest.images[0].filename)
+for mismatch in archive.image_mismatches():   # empty when the images match
+    print(mismatch.rule, mismatch.filename)
+
+r49.is_known_class("stock.loco.steam")    # True
+```
+
+A refusal is an `r49.R49Error` whose `rule` is the format rule id broken, such
+as `manifest/unknown-key`. The id is the contract; the message is not. An
+archive whose images and manifest disagree still loads; `image_mismatches()`
+lists each disagreement under `images/missing` or `images/orphan`.
+`r49.parse_manifest` reads a bare `manifest.json`, which is exempt from the zip
+and image rules.
+
+A car label's `class` is `class_` in Python; the manifest key stays `class`.
+
+## Build and test
+
+Managed with [uv](https://docs.astral.sh/uv/):
+
+```sh
+uv sync --locked
+uv run pytest            # the conformance cases and the reader's own tests
+uv run ruff check .
+uv run black --check .
+uv run pyright
+uv build                 # the sdist, then the wheel from it
+```
+
+Installed with `pip install rails49-r49`.
+
+## Licence
+
+[MIT](https://github.com/rails49/r49/blob/main/LICENSE-MIT).

rails49_r49-0.1.0/pyproject.toml

@@ -0,0 +1,47 @@
+[project]
+name = "rails49-r49"
+version = "0.1.0"
+description = "Read .r49 layout archives"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.10"
+dependencies = ["pydantic>=2.11"]
+
+[project.urls]
+Repository = "https://github.com/rails49/r49"
+Issues = "https://github.com/rails49/r49/issues"
+
+[dependency-groups]
+dev = ["black>=25.1", "pyright>=1.1.400", "pytest>=8.3", "ruff>=0.11"]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/r49"]
+
+# The sdist holds a copy of ../r49/src/data.json in place of the link, and a
+# copy of the repository's LICENSE-MIT, which the wheel built from it lists as
+# its license file.
+[tool.hatch.build.targets.sdist]
+exclude = ["src/r49/data.json"]
+
+[tool.hatch.build.targets.sdist.force-include]
+"../r49/src/data.json" = "src/r49/data.json"
+"../../LICENSE-MIT" = "LICENSE"
+
+[tool.black]
+line-length = 100
+
+[tool.ruff]
+line-length = 100
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B"]
+
+[tool.pyright]
+include = ["src", "tests"]
+typeCheckingMode = "strict"
+venvPath = "."
+venv = ".venv"

rails49_r49-0.1.0/src/r49/__init__.py

@@ -0,0 +1,76 @@
+"""Read ``.r49`` layout archives.
+
+This module is the package's interface; anything not exported here is internal.
+FORMAT.md defines the format, and the conformance cases are how this reader
+shows it agrees with the TypeScript package, @rails49/r49.
+
+Read-only: nothing here writes an archive.
+"""
+
+from .archive import R49Archive, load
+from .calibration_fit import (
+    CalibrationFit,
+    CalibrationPair,
+    LeftOutPoint,
+    LeftOutReason,
+    calibration_fit,
+)
+from .errors import FORMAT_RULES, FormatRule, ImageMismatch, R49Error
+from .manifest import (
+    MANIFEST_VERSION,
+    VALID_SCALES,
+    Calibration,
+    Camera,
+    CarLabel,
+    Image,
+    Layout,
+    Manifest,
+    Point,
+    Provenance,
+    ReferencePoint,
+    Resolution,
+    Scale,
+    Sensor,
+    WorldPoint,
+    parse_manifest,
+)
+from .vocabulary import (
+    VocabularyNode,
+    is_known_class,
+    is_segment_prefix,
+    vocabulary_subtypes,
+)
+
+__all__ = [
+    "FORMAT_RULES",
+    "MANIFEST_VERSION",
+    "VALID_SCALES",
+    "Calibration",
+    "CalibrationFit",
+    "CalibrationPair",
+    "Camera",
+    "CarLabel",
+    "FormatRule",
+    "Image",
+    "ImageMismatch",
+    "Layout",
+    "LeftOutPoint",
+    "LeftOutReason",
+    "Manifest",
+    "Point",
+    "Provenance",
+    "R49Archive",
+    "R49Error",
+    "ReferencePoint",
+    "Resolution",
+    "Scale",
+    "Sensor",
+    "VocabularyNode",
+    "WorldPoint",
+    "calibration_fit",
+    "is_known_class",
+    "is_segment_prefix",
+    "load",
+    "parse_manifest",
+    "vocabulary_subtypes",
+]

rails49_r49-0.1.0/src/r49/archive.py

@@ -0,0 +1,84 @@
+"""Loading a ``.r49`` archive: a zip of ``manifest.json`` and the images it names."""
+
+from __future__ import annotations
+
+import io
+import os
+import zipfile
+import zlib
+from pathlib import Path
+
+from .errors import ImageMismatch, R49Error
+from .manifest import Manifest, parse_manifest
+
+MANIFEST_FILE = "manifest.json"
+
+
+class R49Archive:
+    """A loaded archive, read-only. Get one from :func:`load`."""
+
+    def __init__(self, manifest: Manifest, files: dict[str, bytes]) -> None:
+        self._manifest = manifest
+        self._files = files
+
+    @property
+    def manifest(self) -> Manifest:
+        """The validated manifest."""
+        return self._manifest
+
+    def entries(self) -> list[str]:
+        """Every file in the zip, ``manifest.json`` included, in zip order.
+        Directory entries are left out."""
+        return list(self._files)
+
+    def image(self, filename: str) -> bytes | None:
+        """The bytes of the file at ``filename``, or None when the zip has none."""
+        return self._files.get(filename)
+
+    def image_mismatches(self) -> list[ImageMismatch]:
+        """Every way the manifest and the zip disagree about which images this
+        archive holds: ``images/missing`` for each image entry whose file the
+        zip lacks, in manifest order, then ``images/orphan`` for each file
+        other than ``manifest.json`` that no image names, in zip order. Empty
+        for an archive that follows both rules.
+
+        Reported, not raised: :func:`load` accepts an archive with either."""
+        named = [image.filename for image in self._manifest.images]
+        missing = [
+            ImageMismatch("images/missing", name) for name in named if name not in self._files
+        ]
+        orphan = [
+            ImageMismatch("images/orphan", path)
+            for path in self._files
+            if path != MANIFEST_FILE and path not in named
+        ]
+        return missing + orphan
+
+
+def load(source: bytes | str | os.PathLike[str]) -> R49Archive:
+    """Load an archive from its bytes or from a path, applying every format rule
+    but the two image rules, which :meth:`R49Archive.image_mismatches` reports.
+
+    :raises R49Error: naming the format rule the archive breaks.
+    :raises OSError: if a path cannot be read; that is no verdict on an archive.
+    """
+    data = source if isinstance(source, bytes) else Path(source).read_bytes()
+    if not data:
+        raise R49Error("archive/empty", "Cannot load .r49 archive: data is empty")
+    files = _read_zip(data)
+
+    if MANIFEST_FILE not in files:
+        raise R49Error("archive/no-manifest", "manifest.json not found in archive")
+    return R49Archive(parse_manifest(files[MANIFEST_FILE]), files)
+
+
+def _read_zip(data: bytes) -> dict[str, bytes]:
+    """Every file in the zip by path. Read whole on load, so that a zip that
+    cannot be read is refused here rather than when an image is asked for."""
+    try:
+        with zipfile.ZipFile(io.BytesIO(data)) as zf:
+            return {info.filename: zf.read(info) for info in zf.infolist() if not info.is_dir()}
+    except (zipfile.BadZipFile, zlib.error, EOFError, NotImplementedError, RuntimeError) as err:
+        raise R49Error(
+            "archive/not-zip", f"Failed to load .r49 archive (size: {len(data)} bytes): {err}"
+        ) from None

rails49_r49-0.1.0/src/r49/calibration_fit.py

@@ -0,0 +1,135 @@
+"""The calibration fit, as FORMAT.md § The calibration fit defines it."""
+
+from __future__ import annotations
+
+import math
+from dataclasses import dataclass
+from typing import Literal
+
+from .data import SCALE_TO_RATIO, STANDARD_GAUGE
+from .manifest import Calibration, Manifest
+
+LeftOutReason = Literal["off-reference-plane", "above-camera", "no-partner"]
+"""Why a reference point is not in the fit, in FORMAT.md's order:
+
+* ``off-reference-plane``: there is no camera height and the point's ``z`` is
+  not the reference height.
+* ``above-camera``: the point's ``z`` is the camera height or more.
+* ``no-partner``: no other point still in the fit has the same ``z``.
+"""
+
+
+@dataclass(frozen=True)
+class LeftOutPoint:
+    """A reference point the fit does not use."""
+
+    index: int
+    """The point's index in ``calibration.points``."""
+    reason: LeftOutReason
+
+
+CalibrationPair = tuple[int, int]
+"""A pair the fit uses, by the indexes of its two points in
+``calibration.points``, the lower first."""
+
+
+@dataclass(frozen=True)
+class CalibrationFit:
+    """What a fit reports, together."""
+
+    dpt: float | None
+    """DPT, or None where it does not resolve: no pair with a nonzero separation,
+    or a camera height at or below the reference height."""
+    residual: float | None
+    """The RMS residual in image pixels, or None with fewer than two pairs."""
+    pairs: tuple[CalibrationPair, ...]
+    """The pairs used."""
+    left_out: tuple[LeftOutPoint, ...]
+    """The points left out, by index, each with the first reason that applies."""
+    camera_height_fits: bool | None
+    """None without a camera height; otherwise whether it is above every
+    reference point's ``z``. False is no format error, but the DPT should not
+    be trusted."""
+
+
+def calibration_fit(manifest: Manifest) -> CalibrationFit:
+    """Fit the layout's scale through its reference points.
+
+    ``d_mm²`` weighting trusts long baselines more; heights compare exactly,
+    because they are typed by hand.
+    """
+    calibration = manifest.layout.calibration
+    h = calibration.camera_height_mm
+    z_ref = calibration.reference_height_mm or 0.0
+
+    left_out, pairs = _select(calibration)
+    separations = [_separations(calibration, i, j) for i, j in pairs]
+
+    numerator = sum(d_px * d_mm for d_px, d_mm in separations)
+    denominator = sum(d_mm * d_mm for _, d_mm in separations)
+    scale = numerator / denominator if denominator != 0 else None
+
+    dpt: float | None = None
+    if scale is not None and (h is None or h > z_ref):
+        # Without a camera height the fit already sits on the reference plane;
+        # with one it is at layout zero, and this lifts it to the track.
+        at_reference = scale if h is None else scale * h / (h - z_ref)
+        dpt = at_reference * STANDARD_GAUGE / SCALE_TO_RATIO[manifest.layout.scale]
+
+    residual: float | None = None
+    if scale is not None and len(separations) >= 2:
+        residual = math.sqrt(
+            sum((d_px - scale * d_mm) ** 2 for d_px, d_mm in separations) / len(separations)
+        )
+
+    fits: bool | None = None
+    if h is not None:
+        fits = all(left.reason != "above-camera" for left in left_out)
+
+    return CalibrationFit(
+        dpt=dpt,
+        residual=residual,
+        pairs=tuple(pairs),
+        left_out=tuple(left_out),
+        camera_height_fits=fits,
+    )
+
+
+def _select(calibration: Calibration) -> tuple[list[LeftOutPoint], list[CalibrationPair]]:
+    """The points left out and the pairs: every unordered pair of the rest that
+    shares a ``z``."""
+    h = calibration.camera_height_mm
+    z_ref = calibration.reference_height_mm or 0.0
+    points = calibration.points
+
+    left_out: dict[int, LeftOutReason] = {}
+    for index, point in enumerate(points):
+        if h is None and point.world.z != z_ref:
+            left_out[index] = "off-reference-plane"
+        elif h is not None and point.world.z >= h:
+            left_out[index] = "above-camera"
+
+    kept = [index for index in range(len(points)) if index not in left_out]
+    pairs = [
+        (i, j)
+        for n, i in enumerate(kept)
+        for j in kept[n + 1 :]
+        if points[i].world.z == points[j].world.z
+    ]
+    paired = {index for pair in pairs for index in pair}
+    for index in kept:
+        if index not in paired:
+            left_out[index] = "no-partner"
+
+    return [LeftOutPoint(index, left_out[index]) for index in sorted(left_out)], pairs
+
+
+def _separations(calibration: Calibration, i: int, j: int) -> tuple[float, float]:
+    """A pair's pixel separation, scaled to layout zero when the camera height
+    is known, and its separation on the layout in mm."""
+    a, b = calibration.points[i], calibration.points[j]
+    h = calibration.camera_height_mm
+    d_px = math.hypot(a.px.x - b.px.x, a.px.y - b.px.y)
+    if h is not None:
+        d_px *= (h - a.world.z) / h
+    return d_px, math.hypot(a.world.x - b.world.x, a.world.y - b.world.y)

rails49_r49-0.1.0/src/r49/data.json

@@ -0,0 +1,12 @@
+{
+  "standard_gauge": 1435.0,
+  "scale_to_ratio": { "G": 25, "O": 48, "S": 64, "HO": 87, "T": 120, "N": 160, "Z": 220 },
+  "vocabulary": {
+    "stock": {
+      "loco": { "steam": {}, "diesel": {}, "electric": {} },
+      "passenger": {},
+      "freight": {}
+    }
+  },
+  "recommended_dpt": 20
+}

rails49_r49-0.1.0/src/r49/data.py

@@ -0,0 +1,25 @@
+"""The format's tables, read from ``data.json``.
+
+The file is the TypeScript package's own (``packages/r49/src/data.json``, linked
+here), so both readers compute with the same numbers. FORMAT.md § Scales and
+gauge and § The vocabulary state them in prose. No value is restated in code.
+"""
+
+from __future__ import annotations
+
+import json
+from importlib.resources import files
+from typing import Any, Final
+
+_DATA: Final[dict[str, Any]] = json.loads(
+    files(__package__).joinpath("data.json").read_text(encoding="utf-8")
+)
+
+STANDARD_GAUGE: Final[float] = _DATA["standard_gauge"]
+"""The prototype's standard gauge in mm."""
+
+SCALE_TO_RATIO: Final[dict[str, float]] = _DATA["scale_to_ratio"]
+"""Scale name to reduction ratio (HO is 1:87)."""
+
+VOCABULARY: Final[dict[str, Any]] = _DATA["vocabulary"]
+"""The vocabulary: what a label's ``class`` should match."""

rails49_r49-0.1.0/src/r49/errors.py

@@ -0,0 +1,52 @@
+"""The one error this package raises for an archive that breaks a format rule,
+and the image mismatches an archive reports instead of raising."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Final, Literal, get_args
+
+FormatRule = Literal[
+    "archive/empty",
+    "archive/not-zip",
+    "archive/no-manifest",
+    "manifest/not-json",
+    "manifest/version",
+    "manifest/unknown-key",
+    "manifest/duplicate-id",
+    "manifest/provenance",
+    "manifest/schema",
+    "images/missing",
+    "images/orphan",
+]
+"""A format rule id, as FORMAT.md § Format rules lists them."""
+
+FORMAT_RULES: Final[tuple[FormatRule, ...]] = get_args(FormatRule)
+"""Every format rule id, in FORMAT.md's order.
+
+The id is the contract; the wording of a message is not. A caller that needs to
+tell one refusal from another switches on :attr:`R49Error.rule`, never on the
+text.
+"""
+
+
+class R49Error(Exception):
+    """An archive or manifest broke a format rule. Anything else raised is a bug
+    or a misuse, not a verdict on the archive."""
+
+    rule: FormatRule
+    """The format rule the archive or manifest broke."""
+
+    def __init__(self, rule: FormatRule, message: str) -> None:
+        super().__init__(message)
+        self.rule = rule
+
+
+@dataclass(frozen=True)
+class ImageMismatch:
+    """One way the manifest and the zip disagree about which images an archive
+    holds. Reported by :meth:`R49Archive.image_mismatches`, never raised."""
+
+    rule: Literal["images/missing", "images/orphan"]
+    filename: str
+    """The manifest filename, or the zip entry, the disagreement is about."""