Thank you for your interest in improving TrueMapData. This document is the main entry point for local development, checks, and how we use GitHub.
- Bug reports and feature requests: use the templates under
.github/ISSUE_TEMPLATE/. - Pull requests: follow
.github/PULL_REQUEST_TEMPLATE.mdand link related issues when applicable. - Security: do not open public issues for vulnerabilities. See
SECURITY.md.
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:
pip install -r requirements-dev.txtpip install --upgrade pip
pip install -e ".[dev,docs]"Optional groups from 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.
For a reproducible environment (Python 3.12 image, dependencies, and suggested editor extensions), open the repository in a Dev Container using .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 for notes on .tmd files and common commands.
pytestOptions, logging, markers, and default addopts (including coverage reports) are defined in pytest.ini at the repository root.
Continuous integration runs Ruff (see .github/workflows/ruff.yml). Run it locally before pushing:
python -m ruff check .Optional: python -m ruff format . to apply the formatter locally (CI currently runs ruff check only; see .github/workflows/ruff.yml).
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.
If you use Git hooks, install them after cloning:
pre-commit installConfiguration lives in .pre-commit-config.yaml.
With docs dependencies installed:
mkdocs serveFor binding to all interfaces inside a container, use mkdocs serve -a 0.0.0.0:8000 and forward port 8000 if needed.
For AI-assisted editing, the repository root llms.txt lists canonical TrueMapData links; the published site expands that with AI assistants (llms.txt) (optional editor tooling, verification, and security notes).
Large proprietary captures are not committed as a rule. Whitelisted .tmd paths under examples/ and the wear-volume second-frame binary under tests/fixtures/ used by notebooks and tests/cli/test_example_tmds_smoke.py are tracked in git (see .gitignore negation rules for examples/). CI runs pytest on a clean checkout without a generator step.
Do not replace the canonical bytes of examples/gelsight/circle_0mm_100g_heightmap_linear_detrend.tmd, examples/v1/Dime.tmd, or examples/v2/Dime.tmd when refreshing fixtures. The GelSight circle_0mm file may be a full-resolution capture (large on disk); shrinking it for convenience requires an explicit project decision (for example Git LFS), not an automated rewrite.
To refresh the wear-volume smoke second frame only, regenerate tests/fixtures/gelsight_wear_volume_second_frame.tmd locally by loading examples/gelsight/circle_0mm_100g_heightmap_linear_detrend.tmd (read-only) and writing that fixture path with the same grid and metadata-derived x_length / y_length. Do not write under examples/gelsight/ except the frozen circle_0mm asset you maintain yourself.
To work with your own data, add files under examples/ locally; only the whitelisted fixture filenames are tracked—other examples/**/*.tmd paths stay ignored.
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.
Open a discussion or issue for design questions before large refactors so effort stays aligned with project goals.