Rewrite

.devcontainer/README.md

@@ -0,0 +1,16 @@
+# Dev Container notes
+
+This configuration uses **Python 3.12** on Debian Bookworm with runtime packages commonly needed for **OpenCV** (`libglib2.0-0`, `libgl1`). After the container is created, dependencies are installed from `requirements.txt`, the package is installed editable, `requirements-dev.txt` is applied, **Ruff** is installed for CI parity, and **pre-commit** hooks are installed.
+
+## Working with `.tmd` files
+
+The repository does not ship sample `.tmd` binaries. Mount or copy your own files into the workspace (or use synthetic terrain via `TMDTerrain` / the `terrain` CLI) when developing or running examples.
+
+## Useful commands
+
+- **Tests:** `pytest`
+- **Lint (matches CI):** `ruff check .`
+- **CLI:** `tmd-process --help` or `python tmd_cli.py --help`
+- **Docs:** `mkdocs serve -a 0.0.0.0:8000` (port **8000** is forwarded by default)
+
+Python **3.8–3.12** is validated in GitHub Actions; the container uses a single modern interpreter for day-to-day work.

.devcontainer/devcontainer.json

@@ -0,0 +1,17 @@
+{
+  "name": "TrueMapData",
+  "image": "mcr.microsoft.com/devcontainers/python:3.12-bookworm",
+  "forwardPorts": [8000],
+  "postCreateCommand": "bash -lc 'sudo apt-get update && sudo DEBIAN_FRONTEND=noninteractive apt-get install -y --no-install-recommends libglib2.0-0 libgl1 && python -m pip install --upgrade pip && python -m pip install -r requirements.txt && python -m pip install -e . && python -m pip install -r requirements-dev.txt && python -m pip install ruff && pre-commit install'",
+  "customizations": {
+    "vscode": {
+      "extensions": [
+        "ms-python.python",
+        "charliermarsh.ruff"
+      ],
+      "settings": {
+        "python.defaultInterpreterPath": "/usr/local/bin/python"
+      }
+    }
+  }
+}

.github/renovate.json

@@ -0,0 +1,15 @@
+{
+  "$schema": "https://docs.renovatebot.com/renovate-schema.json",
+  "extends": ["config:recommended"],
+  "labels": ["dependencies"],
+  "pip_requirements": {
+    "fileMatch": ["(^|/)requirements.*\\.txt$"]
+  },
+  "packageRules": [
+    {
+      "description": "Keep CI Actions PRs easy to review",
+      "matchManagers": ["github-actions"],
+      "groupName": "GitHub Actions"
+    }
+  ]
+}

.github/workflows/build.yml

@@ -27,3 +27,6 @@ jobs:
         python -m pip install build wheel
         if [ -f requirements.txt ]; then pip install -r requirements.txt; fi
         pip install -e .
+
+    - name: Build sdist and wheel
+      run: python -m build

.github/workflows/docs.yml

@@ -1,40 +1,52 @@
-# name: Documentation
-
-# on:
-#   push:
-#     branches: [ main, master ]
-
-# jobs:
-#   docs:
-#     runs-on: ubuntu-latest
-
-#     steps:
-#     - uses: actions/checkout@v3
-#       with:
-#         fetch-depth: 0  # Fetch all history for git-revision-date-localized plugin
-
-#     - name: Set up Python
-#       uses: actions/setup-python@v4
-#       with:
-#         python-version: '3.12'
-
-#     - name: Install dependencies
-#       run: |
-#         python -m pip install --upgrade pip
-#         pip install mkdocs==1.5.3 mkdocs-material==9.4.14
-#         pip install mkdocstrings mkdocstrings-python
-#         pip install pymdown-extensions
-#         pip install mkdocs-git-revision-date-localized-plugin
-#         pip install -e .
-
-#     - name: Build documentation
-#       run: |
-#         mkdocs build
-
-#     - name: Deploy to GitHub Pages
-#       if: success() && github.ref == 'refs/heads/main'
-#       uses: peaceiris/actions-gh-pages@v3
-#       with:
-#         github_token: ${{ secrets.DOCS }}
-#         publish_dir: ./site
-#         publish_branch: docs
+name: Documentation
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: pages
+  cancel-in-progress: false
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -r requirements-docs.txt
+          pip install -e .
+
+      - name: Build documentation
+        run: python -m mkdocs build --strict
+
+      - name: Upload Pages artifact
+        if: github.ref == 'refs/heads/main' && github.event_name == 'push'
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: site
+
+  deploy:
+    if: github.ref == 'refs/heads/main' && github.event_name == 'push'
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - id: deployment
+        uses: actions/deploy-pages@v4

.github/workflows/ruff.yml

@@ -1,8 +1,8 @@
-# name: Ruff
-# on: [ push, pull_request ]
-# jobs:
-#   ruff:
-#     runs-on: ubuntu-latest
-#     steps:
-#       - uses: actions/checkout@v4
-#       - uses: astral-sh/ruff-action@v3
+name: Ruff
+on: [ push, pull_request ]
+jobs:
+  ruff:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/ruff-action@v3

CONTRIBUTING.md

@@ -1 +1,94 @@
-contribution
+# Contributing to TrueMapData
+
+Thank you for your interest in improving TrueMapData. This document is the main entry point for local development, checks, and how we use GitHub.
+
+## Issues and pull requests
+
+- **Bug reports and feature requests:** use the templates under [`.github/ISSUE_TEMPLATE/`](.github/ISSUE_TEMPLATE/).
+- **Pull requests:** follow [`.github/PULL_REQUEST_TEMPLATE.md`](.github/PULL_REQUEST_TEMPLATE.md) and link related issues when applicable.
+- **Security:** do not open public issues for vulnerabilities. See [`SECURITY.md`](SECURITY.md).
+
+## Development environment
+
+### Option A: requirements files (matches README)
+
+```bash
+python -m venv .venv
+source .venv/bin/activate   # Windows: .venv\Scripts\activate
+pip install --upgrade pip
+pip install -r requirements.txt
+pip install -e .
+```
+
+For notebooks, docs tooling, and extra dev dependencies:
+
+```bash
+pip install -r requirements-dev.txt
+```
+
+### Option B: editable install with extras
+
+```bash
+pip install --upgrade pip
+pip install -e ".[dev,docs]"
+```
+
+Optional groups from [`pyproject.toml`](pyproject.toml) include `viz`, `mesh`, `advanced`, and `full` (Polyscope, glTF/Open3D-style workflows, etc.). Install what you need for your change; CI does not require every optional extra locally.
+
+### Dev Container
+
+For a reproducible environment (Python 3.12 image, dependencies, and suggested editor extensions), open the repository in a Dev Container using [`.devcontainer/devcontainer.json`](.devcontainer/devcontainer.json). Full **Python 3.8–3.12** compatibility is validated in GitHub Actions, not necessarily inside the container image.
+
+See [`.devcontainer/README.md`](.devcontainer/README.md) for notes on `.tmd` files and common commands.
+
+## Before you open a PR
+
+### Tests
+
+```bash
+pytest
+```
+
+Options and coverage defaults are defined under `[tool.pytest.ini_options]` in [`pyproject.toml`](pyproject.toml).
+
+### Linting
+
+Continuous integration runs **Ruff** (see [`.github/workflows/ruff.yml`](.github/workflows/ruff.yml)). Run it locally before pushing:
+
+```bash
+ruff check .
+```
+
+The `[project.optional-dependencies] dev` group in `pyproject.toml` still lists tools such as Black, isort, Flake8, and mypy for contributors who use them; **Ruff is the linter aligned with CI**.
+
+### Pre-commit
+
+If you use Git hooks, install them after cloning:
+
+```bash
+pre-commit install
+```
+
+Configuration lives in [`.pre-commit-config.yaml`](.pre-commit-config.yaml).
+
+### Documentation
+
+With docs dependencies installed:
+
+```bash
+mkdocs serve
+```
+
+For binding to all interfaces inside a container, use `mkdocs serve -a 0.0.0.0:8000` and forward port **8000** if needed.
+
+## Sample and proprietary `.tmd` data
+
+**Sample `.tmd` files are not committed** to this repository (size and licensing). Use your own captures, published attachments, or synthetic heightmaps (for example `TMDTerrain` / the `terrain` CLI) when developing or adding tests. Do not commit large binary fixtures without maintainer agreement.
+
+## Code style
+
+Match existing patterns in the `tmd` package: naming, imports, and typing conventions. When in doubt, run Ruff and the test suite and mirror surrounding modules.
+
+## Questions
+
+Open a [discussion or issue](https://github.com/ETSTribology/TrueMapData/issues) for design questions before large refactors so effort stays aligned with project goals.