{"id":51139067,"url":"https://github.com/mikelmyers/argus-diff","last_synced_at":"2026-07-14T03:00:45.347Z","repository":{"id":363955327,"uuid":"1265708042","full_name":"mikelmyers/argus-diff","owner":"mikelmyers","description":"git diff for atoms — geometric diff, review, and CI for mechanical CAD (STEP/STL/3MF). Mass deltas, interference, rendered on the PR.","archived":false,"fork":false,"pushed_at":"2026-07-09T20:54:15.000Z","size":337,"stargazers_count":1,"open_issues_count":1,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-07-09T22:14:57.939Z","etag":null,"topics":["cad","cadquery","ci","diff","github-actions","hardware","mechanical-engineering","occt","step"],"latest_commit_sha":null,"homepage":"https://argusdiff.com","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mikelmyers.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-06-11T02:38:10.000Z","updated_at":"2026-07-09T20:54:20.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/mikelmyers/argus-diff","commit_stats":null,"previous_names":["mikelmyers/argus-diff"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/mikelmyers/argus-diff","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mikelmyers%2Fargus-diff","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mikelmyers%2Fargus-diff/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mikelmyers%2Fargus-diff/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mikelmyers%2Fargus-diff/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mikelmyers","download_url":"https://codeload.github.com/mikelmyers/argus-diff/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mikelmyers%2Fargus-diff/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35443979,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-07-14T02:00:06.603Z","response_time":114,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cad","cadquery","ci","diff","github-actions","hardware","mechanical-engineering","occt","step"],"created_at":"2026-06-25T21:00:18.174Z","updated_at":"2026-07-14T03:00:45.341Z","avatar_url":"https://github.com/mikelmyers.png","language":"Python","funding_links":[],"categories":["Extensions and Plugins"],"sub_categories":[],"readme":"# argus-diff\n\n[![ci](https://github.com/mikelmyers/argus-diff/actions/workflows/ci.yml/badge.svg)](https://github.com/mikelmyers/argus-diff/actions/workflows/ci.yml)\n\n**Site \u0026 waitlist:** [argusdiff.com](https://argusdiff.com) ·\n**Live demo:** [the Action commenting a geometric diff on a real PR](https://github.com/mikelmyers/argus-demo/pull/2)\n\n**git diff for atoms.** Geometric diff for mechanical CAD: point it at two\nrevisions of a CAD file — STEP, STL, 3MF, OBJ, PLY — and it tells you what\nactually changed — bodies added/removed/modified,\nmass and volume deltas, bounding box growth, solid-solid interference — as\nstructured JSON, a terminal summary, and a rendered before/after/overlay image.\nWith CI gate flags, so a mechanical change can fail a pull request the way a\nbroken test does.\n\n\u003e AI agents now produce engineering artifacts faster than humans can review\n\u003e them. Verification is the bottleneck. ECAD has diff/review tooling; mechanical\n\u003e CAD — the larger population — reviews screenshots in Slack. This fixes that.\n\n## Install\n\n```bash\npip install \"argus-diff[render]\"     # from PyPI\n# or the bleeding edge from GitHub:\npip install \"argus-diff[render] @ git+https://github.com/mikelmyers/argus-diff\"\n```\n\n## Use\n\n```bash\nargus diff old.step new.step\nargus diff old.step new.step --json diff.json --render diff.png --density 2.70\nargus diff old.step new.step --fail-on-interference --max-mass-delta-pct 2   # CI gate\n```\n\nExample: a sensor-mount bracket between two revisions — plate thickened,\nmounting holes opened up, boss enlarged and shifted, a gusset added (modeled\nslightly overlapping the boss — caught), a locating pin deleted:\n\n![bracket diff render](docs/img/bracket_diff.png)\n\n```\nargus-diff 0.1.0\n  before: bracket_rev_a.step  (4 bodies)\n  after:  bracket_rev_b.step  (4 bodies)\n\n  + 1 added   - 1 removed   ~ 2 modified   = 1 unchanged\n\n  volume: 35638.9 -\u003e 48318.3 mm^3 (+35.58%)\n  mass:   96.23 -\u003e 130.46 g @ 2.7 g/cm^3 (+34.23 g)\n  interferences (after): 1\n    ~ body_0 -\u003e body_0: vol +32.46%, com shift 1.000 mm\n        . 4x cylinder face: radius 2.500 -\u003e 3.000 mm, area 94.25 -\u003e 150.80 mm^2, moved 1.000 mm\n        . 2x plane face: area 468.00 -\u003e 624.00 mm^2, moved 1.000 mm\n    ~ body_1 -\u003e body_1: vol +52.38%, com shift 6.325 mm\n        . cylinder face: radius 10.000 -\u003e 12.000 mm, area 879.65 -\u003e 1055.58 mm^2, moved 6.325 mm\n    + body_2: 540.0 mm^3\n    - body_2: 100.5 mm^3\n    ! interference body_1 x body_2: 108.650 mm^3 overlap\n```\n\nYes — that's the four corner holes opening from ⌀5 to ⌀6 and the boss growing\nfrom ⌀20 to ⌀24, localized to the faces, by name. (Face output truncated here;\nrun it to see all lines.)\n\nExit codes: `0` ok, `1` a gate failed, `2` load/usage error — drop it straight\ninto CI.\n\n## In CI / on pull requests\n\n`argus ci` diffs every STEP file changed between two git refs and emits a\nPR-comment-ready markdown report plus per-file renders:\n\n```bash\nargus ci --base origin/main --render-dir renders/ --markdown report.md \\\n         --fail-on-interference --max-mass-delta-pct 2\n```\n\nOr use the GitHub Action — it comments the report on the PR and uploads the\nrenders as artifacts:\n\n```yaml\n# .github/workflows/cad-review.yml\non: pull_request\npermissions:\n  contents: read\n  pull-requests: write\njobs:\n  cad:\n    runs-on: ubuntu-latest\n    steps:\n      - uses: actions/checkout@v4\n      - uses: mikelmyers/argus-diff@main\n        with:\n          density: \"2.70\"\n          fail-on-interference: \"true\"\n          max-mass-delta-pct: \"2\"\n```\n\n## Read more\n\n[What changed in this 70 MB STEP file? Now you can actually know.](docs/posts/what-changed-in-this-70mb-step-file.md) — argus-diff\nrun on two real revisions from the Jubilee toolchanger's history.\n\n## How it works\n\n- STEP is loaded with the open-source OCCT kernel (via\n  [cadquery](https://github.com/CadQuery/cadquery)/OCP); assemblies are\n  flattened to solids.\n- Each body gets a geometric fingerprint: volume, surface area, center of\n  mass, bounding box, volume-normalized principal moments of inertia, face and\n  edge counts.\n- Bodies are globally matched between revisions by fingerprint distance;\n  matched-but-different = **modified**, unmatched = **added**/**removed**.\n- Interference = pairwise boolean-common volume between solids in the new\n  revision (bbox-prefiltered).\n- Renders are tessellated and drawn offscreen with pyvista — works headless\n  under `xvfb-run`.\n\nEvery number in this README is reproducible: `python examples/make_examples.py`\ngenerates the part pair, the command above generates the output.\n\n## Trust benchmark\n\nCompatibility is not accuracy. The versioned [trust benchmark](docs/benchmark/)\nscores the complete body correspondence and classification against human-reviewed\nground truth, with source provenance and evidence tier recorded per case. The\ncurrent calibration fixture prevents known regressions; it deliberately makes no\npublic accuracy claim until externally sourced, independently reviewed labeled\ncases are added.\n\n```bash\npython tools/score_benchmark.py\n```\n\nHave a real revision pair to test? See the [design-partner program](docs/DESIGN_PARTNERS.md)\nor open a **Benchmark case / design partner** issue. Do not attach proprietary\ngeometry to a public issue.\n\n## Scope (honest)\n\nAlpha. Today: STEP/STL/3MF/OBJ/PLY in, body-level diff out; change\nlocalization is analytic on B-rep (\"4x cylinder face: radius 2.500 -\u003e\n3.000 mm\") and region-based on meshes (\"changed region near (149, 124, 2)\nmm: max deviation 2.02 mm\", rigid translation removed first and stated).\n`--cache` makes repeat runs on unchanged files near-instant (measured\n480x on a 2x70 MB pair). Mesh files skip the interference check (no exact\nbooleans on meshes yet) and report it as skipped, not as zero; open\n(non-watertight) meshes report volume as unavailable rather than a\nmade-up number. Not yet: rotation-aware mesh alignment (ICP),\nfeature-tree awareness, drawing/PMI diff, proprietary formats (SolidWorks\net al.). Roadmap is driven by what users actually hit — file an issue.\n\n## License\n\nMIT.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmikelmyers%2Fargus-diff","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmikelmyers%2Fargus-diff","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmikelmyers%2Fargus-diff/lists"}