Publish evaluated Forma3D Tiny 3 ABO continuation

LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

NOTICE

@@ -0,0 +1,13 @@
+Forma3D-Tiny v0.2.0, derived from Image3D Student v0.1.0
+Copyright 2026 Lucasgitguy-co.
+
+Original project source, documentation and procedural demonstration artifacts are released under Apache License 2.0.
+
+The optional Idol integration and Gaussian attribute conventions were developed with reference to
+speridlabs/idol-sdk, revision 4702a7f00850e34b6e83a2170cc123c3e9570744 (Apache-2.0).
+Its architecture is imported as an optional dependency; pretrained teacher weights are not redistributed.
+Adaptations in this project: staged loading, query-chunk attention, explicit real-valued RoPE selection,
+independent student training, coordinate-preserving Gaussian IO, and diagnostic rendering.
+Upstream attribution is retained in licenses/Idol-APACHE-2.0.txt and THIRD_PARTY.md.
+
+ABO continuation data: Amazon.com, Amazon Berkeley Objects contributors; converted to GLB by CodePawl. CC BY 4.0. Training preprocessing decompresses geometry, normalizes objects, samples surface colors and renders Gaussian proxies. See ATTRIBUTIONS.json and licenses/LICENSE-ABO-CC-BY-4.0.txt. No endorsement implied.

README.md

@@ -0,0 +1,67 @@
+---
+license: apache-2.0
+pipeline_tag: image-to-3d
+base_model: Lucasgitguy-co/forma3d-tiny-2
+base_model_relation: finetune
+model_name: Forma3D Tiny 3
+datasets:
+- codepawl/abo-glb
+tags:
+- pytorch
+- gaussian-splatting
+- mesh-proxy-supervision
+- research-prototype
+---
+# Forma3D Tiny 3
+
+Continued from [Lucasgitguy-co/forma3d-tiny-2](https://huggingface.co/Lucasgitguy-co/forma3d-tiny-2) at `1648582b07a0f7f9d482a8c0f4cf89e6ecd86972`.
+Same 306,321-parameter architecture, 16 cubed grid, width 64, maximum 4,096 Gaussian slots.
+Fresh AdamW optimizer at the start of continuation. Completed 6000 steps;
+selected step 6000 by validation loss only.
+
+## Data and scope
+
+512 ABO objects, 2048 orthographic Gaussian-proxy images on black.
+Data revision: `c7c8293fed3b7ab122ef5d7896521a187e0962d7`. Targets are isotropic mesh surface samples, compressed to
+one Gaussian per occupied grid cell. Texture surface colors are sampled; full PBR rendering
+and differentiable rendering are not used. No natural-photo training is claimed.
+MeshAnythingV2, Idol Diffusers, SHARP, Pixal3D, Idol Turbo and Qwen3.5-4B-3D-Coder
+were **not run, merged, or distilled** in this Mac-only recipe.
+
+Objects, shared Amazon item IDs and exact mesh/image/target hashes are grouped before splitting.
+Split groups: {"train": 348, "validation": 87, "test": 77}. Test data is excluded from training and checkpoint selection.
+Near duplicates can remain; overlap with ancestor training datasets is not fully known.
+
+## Evaluation
+
+Both checkpoints were evaluated on the identical held-out ABO proxy views.
+
+| Metric | Starting v2 | Selected v3 |
+|---|---:|---:|
+| Mean test loss | 0.690551 | 0.544487 |
+| Mean view occupancy IoU, threshold 0.5 | 0.286866 | 0.339860 |
+
+These measurements do not establish natural-photo reconstruction, photorealism, mesh quality,
+novel-view rendering quality or improvement on v2's original domains. No confidence intervals
+or broad generalization claim. See evaluation.json, preparation.json and split manifests.
+
+## Use
+
+With Python 3.11, install this repository using `pip install .`, then:
+
+```bash
+image3d generate --checkpoint model.pt --image centered-object-on-black.png --out object.ply --device mps
+image3d preview --ply object.ply --out preview.png
+```
+
+Output is Gaussian PLY, not a textured GLB mesh. Inputs should match centered objects on black.
+The model has no text prompt conditioning. Reproduction launcher and locked dependencies are in recipe/.
+
+## Attribution
+
+Publisher source and weights: Apache 2.0. Retain inherited NOTICE, THIRD_PARTY.md and ATTRIBUTIONS.json.
+ABO models, images and listing text: Amazon.com and the Amazon Berkeley Objects contributors,
+CC BY 4.0; converted to GLB by CodePawl. The recipe further decompresses geometry,
+normalizes coordinates, samples colored surfaces and renders proxy images.
+See [ABO dataset](https://huggingface.co/datasets/codepawl/abo-glb),
+ATTRIBUTIONS.json and licenses/LICENSE-ABO-CC-BY-4.0.txt. Raw assets are not bundled.

SHA256SUMS

@@ -0,0 +1,34 @@
+952b78774f6d41182b685271d6ed64abbca9b0c5ff4081e8e55ab92ce256e737  ATTRIBUTIONS.json
+cfc7749b96f63bd31c3c42b5c471bf756814053e847c10f3eb003417bc523d30  LICENSE
+d84c0de5fa230ed94d4a2c84c791ffe4a13a2f73ac2657b19bcf0b55f11726a7  NOTICE
+0ae2c6c30c34fd70281e576023e040052c7546adad85c530c91e179299c2dc16  README.md
+ef7c689f184a7921b02887eeb8d859e8cca77da6d2082999bb19bf29beda61f1  THIRD_PARTY.md
+54439a905e24b39dfc4d2c28a4b45b97e584a3cf40c612700e71aba4b51d9409  completed.json
+25d53c6500d9e45aca8a2ce1fe54030e05a0822c554ab24cfcbfeaa631ee9c91  config.json
+e6aca692ff4fe1a6066c67152253435bebb86bcd33983efa73d9b45b0709da23  environment.txt
+5bab5e4f1938a873a5f2eb8405fe4d94e0b532bc566250189c5b1e764ed3eebf  evaluation.json
+cfc7749b96f63bd31c3c42b5c471bf756814053e847c10f3eb003417bc523d30  licenses/Idol-APACHE-2.0.txt
+419896aea50c15d6e40c5b4baf4bd346f78223b9a354c7357ad00262afdc08ec  licenses/LICENSE-ABO-CC-BY-4.0.txt
+c9175419fd345f1b2831201495cf27d9929b92dee52288c798ece243b13f6db1  metrics.jsonl
+ec7c37e8ff293877149822150a5e08e8dde3e37fe0e6cfc1dc71e05adecd7790  model.pt
+14d89f03bdae1c5cb416b121248d024a49c30d5545bd560b6b390c52afa049c2  preparation.json
+e8f66f2a90fbe6c42cc098357cc862d8ea00eaf3a4f38fa22eb59b168eab2ee9  pyproject.toml
+da5bb78d178599428987111fc83e27678fd3589e59c4756653f612114e139a29  recipe/decode.mjs
+72730d8990cffc36b3f77ced370306978d01ddeb9b417c891613c0e95cb475ac  recipe/package-lock.json
+4d87fdff2312cb3afc1ecd98c39e152c6b44e792b4ea717c8f94204ab8d857a7  recipe/package.json
+33ef603b3550a78eb982138540bcdbbca596d3b3f697368593a6d5ca3ff4b436  recipe/pipeline.py
+890fa9075ec44ab44d42db01a893df1fd1ab8b6c989324041f4ee3537a2d5720  recipe/requirements.txt
+b9e8acb85f25b4e35ab555e81d09a3679e5daa4edafdc5f28a80c4442da83db3  recipe/run.command
+2d0c28622dfb8d3a51f1cc631bbb62ed48c135c83aee2b9edf72aed161b9a3e3  settings.json
+c8f927c42ba2ccecd960536de8c7c7431c8fe674401e1fbe7d7613d18cab860d  splits/test.jsonl
+65af1c16cefde7e9cd411af055ccdee36c183382db18a4fd9a9d4ea82fb248ee  splits/train.jsonl
+65ca208e5b7d59d398056c997751b12a18ce05c9361e37f4160f3b1420cbe52a  splits/validation.jsonl
+c09ce8cb78cd68ae32b618ba49f97508b6ce14bc89e88c5b80cc3e2487bd919c  src/image3d_student/__init__.py
+b4be53a864458a84009e91277ff64767dffc6139ca3afcc50526747743722c02  src/image3d_student/cli.py
+d34f9fa50d574764e5e2c1c31c1ca477f2bc4a1887e103c5c47b754f1f1d8c72  src/image3d_student/data.py
+e01d1b42929c993d92cad1bde8944b14c6a8e325fc279d8fd3e9c7287523ad69  src/image3d_student/demo.py
+7335dcc99fcd9cea5c217841376f0ca8c0ca179809b4df34e344bf929d11da51  src/image3d_student/engine.py
+a18005f75a66846446b2574b4f1b085ebde5321e835c4e5b4507e15e812ee5ef  src/image3d_student/model.py
+41961fae62d2819c1e3f455e74539a66b8c4f57bedd9fb9379497b3a5764c692  src/image3d_student/splats.py
+2e2439bc0a48c52e32a8e273f879ed7328fdb82632a996ed3e239e0391ca3a59  src/image3d_student/teacher_idol.py
+ebe640c6078f02ef84fb9992bd3f7585a326b523e9f480526c2057d5a2892074  training.json

THIRD_PARTY.md

@@ -0,0 +1,13 @@
+# Third-party scope
+
+This training kit extends Lucasgitguy-co/image3d-student, Apache-2.0. The original
+checkpoint is downloaded separately. No new trained weights are bundled in the kit.
+
+Optional Idol SDK integration is inherited from the original project, pinned to
+`4702a7f00850e34b6e83a2170cc123c3e9570744`; its Apache notice is retained in
+`licenses/Idol-APACHE-2.0.txt`. The Mac recipe does not install or run Idol, Hi3D,
+InstantMesh, Hunyuan, or gated encoders. Their weights are not redistributed.
+
+Dependencies retain their respective licenses. Third-party dataset terms are
+documented in DATASETS.md; per-asset attribution is generated during preparation
+and copied into any published release. Code licensing does not relicense datasets.

completed.json

@@ -0,0 +1,5 @@
+{
+  "completed_steps": 6000,
+  "selected_step": 6000,
+  "best_validation_loss": 0.5845230878598389
+}

config.json

@@ -0,0 +1,4 @@
+{
+  "grid": 16,
+  "width": 64
+}

environment.txt

@@ -0,0 +1,28 @@
+Jinja2==3.1.6
+MarkupSafe==3.0.4
+PyYAML==6.0.3
+anyio==4.16.0
+click==8.5.1
+filelock==4.2.9
+fsspec==2026.9.0
+h11==0.16.0
+hf-xet==1.8.0
+httpcore2==2.16.0
+httpx2==2.16.0
+huggingface_hub==2.4.0
+idna==3.20
+mpmath==1.3.0
+networkx==3.6.1
+numpy==2.4.6
+packaging==26.3
+pillow==13.0.0
+plyfile==1.1.5
+pyarrow==26.0.0
+scipy==1.17.1
+setuptools==84.2.1
+sympy==1.14.0
+torch==2.15.0
+tqdm==4.70.1
+trimesh==5.2.0
+truststore==0.10.5
+typing_extensions==4.16.0

evaluation.json

@@ -0,0 +1,41 @@
+{
+  "base_v2": {
+    "sha256": "c051b3f93d874f7c638588c9d0381754d3f954b1cd271121a033b2478d36bb1a",
+    "metrics": {
+      "occupancy": 0.5241638378953779,
+      "position": 0.0944967952302911,
+      "colour": 0.03564881652105273,
+      "scale": 0.0022415842836557938,
+      "rotation": 1.5440619935813406e-05,
+      "opacity": 0.00036697591761591643,
+      "geometry": 0.0,
+      "loss": 0.6905509463765405,
+      "occupancy_iou": 0.2868661397414935
+    }
+  },
+  "candidate_v3": {
+    "sha256": "ec7c37e8ff293877149822150a5e08e8dde3e37fe0e6cfc1dc71e05adecd7790",
+    "metrics": {
+      "occupancy": 0.38844528866859224,
+      "position": 0.09291809090933242,
+      "colour": 0.03145392079041612,
+      "scale": 0.0012586073008405238,
+      "rotation": 2.456774355854217e-06,
+      "opacity": 8.929977638831883e-05,
+      "geometry": 0.0,
+      "loss": 0.5444866280954379,
+      "occupancy_iou": 0.33986033104940666
+    }
+  },
+  "gates": {
+    "training_complete": true,
+    "validation_loss_improved": true,
+    "test_loss_improved_at_least_half_percent": true,
+    "test_occupancy_iou_not_worse": true,
+    "weights_changed": true
+  },
+  "passed": true,
+  "test_manifest_sha256": "c8f927c42ba2ccecd960536de8c7c7431c8fe674401e1fbe7d7613d18cab860d",
+  "measurement": "mean per-view proxy loss and occupancy IoU, threshold 0.5, batch size 1",
+  "limitation": "Not evidence of natural-photo, mesh, texture or photorealistic rendering quality."
+}

licenses/Idol-APACHE-2.0.txt

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

licenses/LICENSE-ABO-CC-BY-4.0.txt

@@ -0,0 +1,317 @@
+Creative Commons Attribution 4.0 International Public License
+
+By exercising the Licensed Rights (defined below), You accept and agree
+to be bound by the terms and conditions of this Creative Commons
+Attribution 4.0 International Public License ("Public License"). To the
+extent this Public License may be interpreted as a contract, You are
+granted the Licensed Rights in consideration of Your acceptance of
+these terms and conditions, and the Licensor grants You such rights in
+consideration of benefits the Licensor receives from making the
+Licensed Material available under these terms and conditions.
+
+
+Section 1 -- Definitions.
+
+  a. Adapted Material means material subject to Copyright and Similar
+     Rights that is derived from or based upon the Licensed Material
+     and in which the Licensed Material is translated, altered,
+     arranged, transformed, or otherwise modified in a manner requiring
+     permission under the Copyright and Similar Rights held by the
+     Licensor. For purposes of this Public License, where the Licensed
+     Material is a musical work, performance, or sound recording,
+     Adapted Material is always produced where the Licensed Material is
+     synched in timed relation with a moving image.
+
+  b. Adapter's License means the license You apply to Your Copyright
+     and Similar Rights in Your contributions to Adapted Material in
+     accordance with the terms and conditions of this Public License.
+
+  c. Copyright and Similar Rights means copyright and/or similar rights
+     closely related to copyright including, without limitation,
+     performance, broadcast, sound recording, and Sui Generis Database
+     Rights, without regard to how the rights are labeled or
+     categorized. For purposes of this Public License, the rights
+     specified in Section 2(b)(1)-(2) are not Copyright and Similar
+     Rights.
+
+  d. Effective Technological Measures means those measures that, in the
+     absence of proper authority, may not be circumvented under laws
+     fulfilling obligations under Article 11 of the WIPO Copyright
+     Treaty adopted on December 20, 1996, and/or similar international
+     agreements.
+
+  e. Exceptions and Limitations means fair use, fair dealing, and/or
+     any other exception or limitation to Copyright and Similar Rights
+     that applies to Your use of the Licensed Material.
+
+  f. Licensed Material means the artistic or literary work, database,
+     or other material to which the Licensor applied this Public
+     License.
+
+  g. Licensed Rights means the rights granted to You subject to the
+     terms and conditions of this Public License, which are limited to
+     all Copyright and Similar Rights that apply to Your use of the
+     Licensed Material and that the Licensor has authority to license.
+
+  h. Licensor means the individual(s) or entity(ies) granting rights
+     under this Public License.
+
+  i. Share means to provide material to the public by any means or
+     process that requires permission under the Licensed Rights, such
+     as reproduction, public display, public performance, distribution,
+     dissemination, communication, or importation, and to make material
+     available to the public including in ways that members of the
+     public may access the material from a place and at a time
+     individually chosen by them.
+
+  j. Sui Generis Database Rights means rights other than copyright
+     resulting from Directive 96/9/EC of the European Parliament and of
+     the Council of 11 March 1996 on the legal protection of databases,
+     as amended and/or succeeded, as well as other essentially
+     equivalent rights anywhere in the world.
+
+  k. You means the individual or entity exercising the Licensed Rights
+     under this Public License. Your has a corresponding meaning.
+
+
+Section 2 -- Scope.
+
+  a. License grant.
+
+       1. Subject to the terms and conditions of this Public License,
+          the Licensor hereby grants You a worldwide, royalty-free,
+          non-sublicensable, non-exclusive, irrevocable license to
+          exercise the Licensed Rights in the Licensed Material to:
+
+            a. reproduce and Share the Licensed Material, in whole or
+               in part; and
+
+            b. produce, reproduce, and Share Adapted Material.
+
+       2. Exceptions and Limitations. For the avoidance of doubt, where
+          Exceptions and Limitations apply to Your use, this Public
+          License does not apply, and You do not need to comply with
+          its terms and conditions.
+
+       3. Term. The term of this Public License is specified in Section
+          6(a).
+
+       4. Media and formats; technical modifications allowed. The
+          Licensor authorizes You to exercise the Licensed Rights in
+          all media and formats whether now known or hereafter created,
+          and to make technical modifications necessary to do so. The
+          Licensor waives and/or agrees not to assert any right or
+          authority to forbid You from making technical modifications
+          necessary to exercise the Licensed Rights, including
+          technical modifications necessary to circumvent Effective
+          Technological Measures. For purposes of this Public License,
+          simply making modifications authorized by this Section 2(a)
+          (4) never produces Adapted Material.
+
+       5. Downstream recipients.
+
+            a. Offer from the Licensor -- Licensed Material. Every
+               recipient of the Licensed Material automatically
+               receives an offer from the Licensor to exercise the
+               Licensed Rights under the terms and conditions of this
+               Public License.
+
+            b. No downstream restrictions. You may not offer or impose
+               any additional or different terms or conditions on, or
+               apply any Effective Technological Measures to, the
+               Licensed Material if doing so restricts exercise of the
+               Licensed Rights by any recipient of the Licensed
+               Material.
+
+       6. No endorsement. Nothing in this Public License constitutes or
+          may be construed as permission to assert or imply that You
+          are, or that Your use of the Licensed Material is, connected
+          with, or sponsored, endorsed, or granted official status by,
+          the Licensor or others designated to receive attribution as
+          provided in Section 3(a)(1)(A)(i).
+
+  b. Other rights.
+
+       1. Moral rights, such as the right of integrity, are not
+          licensed under this Public License, nor are publicity,
+          privacy, and/or other similar personality rights; however, to
+          the extent possible, the Licensor waives and/or agrees not to
+          assert any such rights held by the Licensor to the limited
+          extent necessary to allow You to exercise the Licensed
+          Rights, but not otherwise.
+
+       2. Patent and trademark rights are not licensed under this
+          Public License.
+
+       3. To the extent possible, the Licensor waives any right to
+          collect royalties from You for the exercise of the Licensed
+          Rights, whether directly or through a collecting society
+          under any voluntary or waivable statutory or compulsory
+          licensing scheme. In all other cases the Licensor expressly
+          reserves any right to collect such royalties.
+
+
+Section 3 -- License Conditions.
+
+Your exercise of the Licensed Rights is expressly made subject to the
+following conditions.
+
+  a. Attribution.
+
+       1. If You Share the Licensed Material (including in modified
+          form), You must:
+
+            a. retain the following if it is supplied by the Licensor
+               with the Licensed Material:
+
+                 i. identification of the creator(s) of the Licensed
+                    Material and any others designated to receive
+                    attribution, in any reasonable manner requested by
+                    the Licensor (including by pseudonym if
+                    designated);
+
+                ii. a copyright notice;
+
+               iii. a notice that refers to this Public License;
+
+                iv. a notice that refers to the disclaimer of
+                    warranties;
+
+                 v. a URI or hyperlink to the Licensed Material to the
+                    extent reasonably practicable;
+
+            b. indicate if You modified the Licensed Material and
+               retain an indication of any previous modifications; and
+
+            c. indicate the Licensed Material is licensed under this
+               Public License, and include the text of, or the URI or
+               hyperlink to, this Public License.
+
+       2. You may satisfy the conditions in Section 3(a)(1) in any
+          reasonable manner based on the medium, means, and context in
+          which You Share the Licensed Material. For example, it may be
+          reasonable to satisfy the conditions by providing a URI or
+          hyperlink to a resource that includes the required
+          information.
+
+       3. If requested by the Licensor, You must remove any of the
+          information required by Section 3(a)(1)(A) to the extent
+          reasonably practicable.
+
+       4. If You Share Adapted Material You produce, the Adapter's
+          License You apply must not prevent recipients of the Adapted
+          Material from complying with this Public License.
+
+
+Section 4 -- Sui Generis Database Rights.
+
+Where the Licensed Rights include Sui Generis Database Rights that
+apply to Your use of the Licensed Material:
+
+  a. for the avoidance of doubt, Section 2(a)(1) grants You the right
+     to extract, reuse, reproduce, and Share all or a substantial
+     portion of the contents of the database;
+
+  b. if You include all or a substantial portion of the database
+     contents in a database in which You have Sui Generis Database
+     Rights, then the database in which You have Sui Generis Database
+     Rights (but not its individual contents) is Adapted Material; and
+
+  c. You must comply with the conditions in Section 3(a) if You Share
+     all or a substantial portion of the contents of the database.
+
+For the avoidance of doubt, this Section 4 supplements and does not
+replace Your obligations under this Public License where the Licensed
+Rights include other Copyright and Similar Rights.
+
+
+Section 5 -- Disclaimer of Warranties and Limitation of Liability.
+
+  a. UNLESS OTHERWISE SEPARATELY UNDERTAKEN BY THE LICENSOR, TO THE
+     EXTENT POSSIBLE, THE LICENSOR OFFERS THE LICENSED MATERIAL AS-IS
+     AND AS-AVAILABLE, AND MAKES NO REPRESENTATIONS OR WARRANTIES OF
+     ANY KIND CONCERNING THE LICENSED MATERIAL, WHETHER EXPRESS,
+     IMPLIED, STATUTORY, OR OTHER. THIS INCLUDES, WITHOUT LIMITATION,
+     WARRANTIES OF TITLE, MERCHANTABILITY, FITNESS FOR A PARTICULAR
+     PURPOSE, NON-INFRINGEMENT, ABSENCE OF LATENT OR OTHER DEFECTS,
+     ACCURACY, OR THE PRESENCE OR ABSENCE OF ERRORS, WHETHER OR NOT
+     KNOWN OR DISCOVERABLE. WHERE DISCLAIMERS OF WARRANTIES ARE NOT
+     ALLOWED IN FULL OR IN PART, THIS DISCLAIMER MAY NOT APPLY TO YOU.
+
+  b. TO THE EXTENT POSSIBLE, IN NO EVENT WILL THE LICENSOR BE LIABLE
+     TO YOU ON ANY LEGAL THEORY (INCLUDING, WITHOUT LIMITATION,
+     NEGLIGENCE) OR OTHERWISE FOR ANY DIRECT, SPECIAL, INDIRECT,
+     INCIDENTAL, CONSEQUENTIAL, PUNITIVE, EXEMPLARY, OR OTHER LOSSES,
+     COSTS, EXPENSES, OR DAMAGES ARISING OUT OF THIS PUBLIC LICENSE OR
+     USE OF THE LICENSED MATERIAL, EVEN IF THE LICENSOR HAS BEEN
+     ADVISED OF THE POSSIBILITY OF SUCH LOSSES, COSTS, EXPENSES, OR
+     DAMAGES. WHERE A LIMITATION OF LIABILITY IS NOT ALLOWED IN FULL OR
+     IN PART, THIS LIMITATION MAY NOT APPLY TO YOU.
+
+  c. The disclaimer of warranties and limitation of liability provided
+     above shall be interpreted in a manner that, to the extent
+     possible, most closely approximates an absolute disclaimer and
+     waiver of all liability.
+
+
+Section 6 -- Term and Termination.
+
+  a. This Public License applies for the term of the Copyright and
+     Similar Rights licensed here. However, if You fail to comply with
+     this Public License, then Your rights under this Public License
+     terminate automatically.
+
+  b. Where Your right to use the Licensed Material has terminated under
+     Section 6(a), it reinstates:
+
+       1. automatically as of the date the violation is cured, provided
+          it is cured within 30 days of Your discovery of the
+          violation; or
+
+       2. upon express reinstatement by the Licensor.
+
+     For the avoidance of doubt, this Section 6(b) does not affect any
+     right the Licensor may have to seek remedies for Your violations
+     of this Public License.
+
+  c. For the avoidance of doubt, the Licensor may also offer the
+     Licensed Material under separate terms or conditions or stop
+     distributing the Licensed Material at any time; however, doing so
+     will not terminate this Public License.
+
+  d. Sections 1, 5, 6, 7, and 8 survive termination of this Public
+     License.
+
+
+Section 7 -- Other Terms and Conditions.
+
+  a. The Licensor shall not be bound by any additional or different
+     terms or conditions communicated by You unless expressly agreed.
+
+  b. Any arrangements, understandings, or agreements regarding the
+     Licensed Material not stated herein are separate from and
+     independent of the terms and conditions of this Public License.
+
+
+Section 8 -- Interpretation.
+
+  a. For the avoidance of doubt, this Public License does not, and
+     shall not be interpreted to, reduce, limit, restrict, or impose
+     conditions on any use of the Licensed Material that could lawfully
+     be made without permission under this Public License.
+
+  b. To the extent possible, if any provision of this Public License is
+     deemed unenforceable, it shall be automatically reformed to the
+     minimum extent necessary to make it enforceable. If the provision
+     cannot be reformed, it shall be severed from this Public License
+     without affecting the enforceability of the remaining terms and
+     conditions.
+
+  c. No term or condition of this Public License will be waived and no
+     failure to comply consented to unless expressly agreed to by the
+     Licensor.
+
+  d. Nothing in this Public License constitutes or may be interpreted
+     as a limitation upon, or waiver of, any privileges and immunities
+     that apply to the Licensor or You, including from the legal
+     processes of any jurisdiction or authority.

metrics.jsonl

@@ -0,0 +1,24 @@
+{"step": 250, "validation": {"occupancy": 0.46106726838939494, "position": 0.09389111219808974, "colour": 0.04310893663230296, "scale": 0.0017047523277184133, "rotation": 7.976808186366066e-06, "opacity": 0.0001671786365754631, "geometry": 0.0, "loss": 0.6415147080846216, "occupancy_iou": 0.28041237205181313}, "best_step": 250}
+{"step": 500, "validation": {"occupancy": 0.45162729049722355, "position": 0.09384130607305587, "colour": 0.04260444884213897, "scale": 0.001661866389471909, "rotation": 7.302595148517532e-06, "opacity": 0.00015287357286561227, "geometry": 0.0, "loss": 0.6309972834484331, "occupancy_iou": 0.2809994066583699}, "best_step": 500}
+{"step": 750, "validation": {"occupancy": 0.4463731253455425, "position": 0.09366091319370544, "colour": 0.04174524028390785, "scale": 0.0015576746118731327, "rotation": 6.378893373750188e-06, "opacity": 0.00014788560389499106, "geometry": 0.0, "loss": 0.623828811121398, "occupancy_iou": 0.28580000422809315}, "best_step": 750}
+{"step": 1000, "validation": {"occupancy": 0.44312713128225556, "position": 0.09379177611192753, "colour": 0.04165307760182447, "scale": 0.0015555841554874212, "rotation": 5.9876457319153386e-06, "opacity": 0.00015077445404988366, "geometry": 0.0, "loss": 0.6205319956630125, "occupancy_iou": 0.2945208903830284}, "best_step": 1000}
+{"step": 1250, "validation": {"occupancy": 0.44061438426717947, "position": 0.09367082068889306, "colour": 0.04216459069863342, "scale": 0.0014779921650355306, "rotation": 5.084008926746981e-06, "opacity": 0.00011434342663647087, "geometry": 0.0, "loss": 0.6188770349340877, "occupancy_iou": 0.2978490527569391}, "best_step": 1250}
+{"step": 1500, "validation": {"occupancy": 0.4407315632735176, "position": 0.09352761307923958, "colour": 0.04121334745345273, "scale": 0.001461793350182265, "rotation": 5.134973895207005e-06, "opacity": 0.00013860988812520263, "geometry": 0.0, "loss": 0.6169711736769512, "occupancy_iou": 0.30566408061261835}, "best_step": 1500}
+{"step": 1750, "validation": {"occupancy": 0.4404393983469612, "position": 0.09349199953949315, "colour": 0.04051890540187282, "scale": 0.0014701240166457071, "rotation": 4.675330279103517e-06, "opacity": 0.0001237910014685764, "geometry": 0.0, "loss": 0.6152404779675363, "occupancy_iou": 0.2812621619595193}, "best_step": 1750}
+{"step": 2000, "validation": {"occupancy": 0.4346818130506181, "position": 0.09341091703323798, "colour": 0.040201177800073554, "scale": 0.001307281967079877, "rotation": 4.513101891955652e-06, "opacity": 0.00011089177358361217, "geometry": 0.0, "loss": 0.6087371564802082, "occupancy_iou": 0.3118145927444272}, "best_step": 2000}
+{"step": 2250, "validation": {"occupancy": 0.43869901795325605, "position": 0.09344819003994438, "colour": 0.03963602398473357, "scale": 0.0013264096483364754, "rotation": 4.0235361918947135e-06, "opacity": 0.00012048149227112667, "geometry": 0.0, "loss": 0.6116727790955839, "occupancy_iou": 0.327563153215866}, "best_step": 2000}
+{"step": 2500, "validation": {"occupancy": 0.43227739353803385, "position": 0.0933333754154115, "colour": 0.04032809674817113, "scale": 0.0014659382510196347, "rotation": 3.973887600551834e-06, "opacity": 0.00011141035008285113, "geometry": 0.0, "loss": 0.6065253679608477, "occupancy_iou": 0.317919851869516}, "best_step": 2500}
+{"step": 2750, "validation": {"occupancy": 0.4353166666181608, "position": 0.09328038397448501, "colour": 0.040686976895854945, "scale": 0.0012758097041166794, "rotation": 3.63702629057905e-06, "opacity": 0.0001189368781472266, "geometry": 0.0, "loss": 0.6102178843542078, "occupancy_iou": 0.3161811849487753}, "best_step": 2500}
+{"step": 3000, "validation": {"occupancy": 0.4327074812147124, "position": 0.09331944621243012, "colour": 0.039487305421605653, "scale": 0.0012567756840880242, "rotation": 3.5919594875489063e-06, "opacity": 0.00010452814740869792, "geometry": 0.0, "loss": 0.6052321044878027, "occupancy_iou": 0.32888385336632014}, "best_step": 3000}
+{"step": 3250, "validation": {"occupancy": 0.4364492620031039, "position": 0.09324339584543787, "colour": 0.04059594625760346, "scale": 0.0014138426100627798, "rotation": 3.2943687288110042e-06, "opacity": 9.927087626499412e-05, "geometry": 0.0, "loss": 0.6111255342076565, "occupancy_iou": 0.3483805300389556}, "best_step": 3000}
+{"step": 3500, "validation": {"occupancy": 0.42581871918391906, "position": 0.09325098914319072, "colour": 0.03928116287306171, "scale": 0.0011773849444413002, "rotation": 3.056185458513812e-06, "opacity": 9.935026393535757e-05, "geometry": 0.0, "loss": 0.5978494251425239, "occupancy_iou": 0.30775405541490547}, "best_step": 3500}
+{"step": 3750, "validation": {"occupancy": 0.432027333469569, "position": 0.09319557866145825, "colour": 0.040138308227131804, "scale": 0.0011525598650526565, "rotation": 3.166901425911733e-06, "opacity": 9.929725881935239e-05, "geometry": 0.0, "loss": 0.6057144006093343, "occupancy_iou": 0.3355185413711715}, "best_step": 3500}
+{"step": 4000, "validation": {"occupancy": 0.42550981757712775, "position": 0.09316891669456301, "colour": 0.04052523164856033, "scale": 0.0012177044145887364, "rotation": 2.9242365325929356e-06, "opacity": 0.00010036813353445754, "geometry": 0.0, "loss": 0.5999516276107437, "occupancy_iou": 0.3211282266667862}, "best_step": 3500}
+{"step": 4250, "validation": {"occupancy": 0.43654163040477656, "position": 0.09321942790571985, "colour": 0.03907850670414822, "scale": 0.0011486642537023015, "rotation": 2.998764346520848e-06, "opacity": 0.00011165465859537745, "geometry": 0.0, "loss": 0.6081448930433426, "occupancy_iou": 0.35518712877970315}, "best_step": 3500}
+{"step": 4500, "validation": {"occupancy": 0.42716445825223265, "position": 0.09306304662049501, "colour": 0.03876508917791994, "scale": 0.001119821725045893, "rotation": 2.8751217178591753e-06, "opacity": 9.490183666541229e-05, "geometry": 0.0, "loss": 0.5979648541616297, "occupancy_iou": 0.33583940336502144}, "best_step": 3500}
+{"step": 4750, "validation": {"occupancy": 0.4252900903637724, "position": 0.09302231579505164, "colour": 0.03992765121651685, "scale": 0.001186143789385531, "rotation": 2.6761208888841394e-06, "opacity": 9.641269463733399e-05, "geometry": 0.0, "loss": 0.5983830038244011, "occupancy_iou": 0.32429440710265406}, "best_step": 3500}
+{"step": 5000, "validation": {"occupancy": 0.4202662355469904, "position": 0.09291419757251766, "colour": 0.03968908278396669, "scale": 0.0011747911177380224, "rotation": 2.4885126973019615e-06, "opacity": 9.251441614933669e-05, "geometry": 0.0, "loss": 0.5927688404061329, "occupancy_iou": 0.32473888893708075}, "best_step": 5000}
+{"step": 5250, "validation": {"occupancy": 0.41929296279946965, "position": 0.09285500444386197, "colour": 0.03871898723538061, "scale": 0.001147763923529118, "rotation": 2.570338795158545e-06, "opacity": 8.911200696316862e-05, "geometry": 0.0, "loss": 0.5897900897195969, "occupancy_iou": 0.3356060852328765}, "best_step": 5250}
+{"step": 5500, "validation": {"occupancy": 0.42326834313999645, "position": 0.09288628300887415, "colour": 0.039693311325156654, "scale": 0.0011034196943690967, "rotation": 2.521009106911167e-06, "opacity": 9.737238293126566e-05, "geometry": 0.0, "loss": 0.5957492148910446, "occupancy_iou": 0.34857936678775425}, "best_step": 5250}
+{"step": 5750, "validation": {"occupancy": 0.4186605631491576, "position": 0.09286394899432686, "colour": 0.039635561564341774, "scale": 0.001126612422368275, "rotation": 2.4452578455453876e-06, "opacity": 9.208203308760899e-05, "geometry": 0.0, "loss": 0.591000622288249, "occupancy_iou": 0.3344719207941972}, "best_step": 5250}
+{"step": 6000, "validation": {"occupancy": 0.4138930352597401, "position": 0.09282098901083415, "colour": 0.038808255775693815, "scale": 0.0010773984927934296, "rotation": 2.286030634838985e-06, "opacity": 8.458352363703299e-05, "geometry": 0.0, "loss": 0.5845230878598389, "occupancy_iou": 0.3310552115669881}, "best_step": 6000}

model.pt

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:ec7c37e8ff293877149822150a5e08e8dde3e37fe0e6cfc1dc71e05adecd7790
+size 1725673

preparation.json

@@ -0,0 +1,23 @@
+{
+  "dataset": "codepawl/abo-glb",
+  "revision": "c7c8293fed3b7ab122ef5d7896521a187e0962d7",
+  "objects": 512,
+  "views": 2048,
+  "groups": {
+    "train": 348,
+    "validation": 87,
+    "test": 77
+  },
+  "split_views": {
+    "train": 1392,
+    "validation": 348,
+    "test": 308
+  },
+  "manifest_sha256": {
+    "train": "65af1c16cefde7e9cd411af055ccdee36c183382db18a4fd9a9d4ea82fb248ee",
+    "validation": "65ca208e5b7d59d398056c997751b12a18ce05c9361e37f4160f3b1420cbe52a",
+    "test": "c8f927c42ba2ccecd960536de8c7c7431c8fe674401e1fbe7d7613d18cab860d"
+  },
+  "grouping": "object IDs, shared Amazon item IDs, exact mesh/image/target hashes",
+  "limitations": "Near duplicates can remain. Cross-dataset overlap with ancestor training is not fully known; only recorded exact source hashes were excluded."
+}

pyproject.toml

@@ -0,0 +1,28 @@
+[build-system]
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "forma3d-tiny-3"
+version = "0.4.0"
+license = "Apache-2.0"
+license-files = ["LICENSE", "NOTICE", "THIRD_PARTY.md", "licenses/*.txt"]
+readme = "README.md"
+authors = [{name = "Lucasgitguy-co"}]
+description = "Experimental local image-to-Gaussian student with cached teacher supervision"
+requires-python = ">=3.11,<3.14"
+dependencies = ["torch>=2.5", "numpy>=1.26", "pillow>=10", "plyfile>=1", "trimesh>=4", "scipy>=1.11"]
+
+[project.optional-dependencies]
+test = ["pytest>=8"]
+data = ["huggingface_hub>=0.34", "pyarrow>=17"]
+teacher = ["idol @ git+https://github.com/speridlabs/idol-sdk.git@4702a7f00850e34b6e83a2170cc123c3e9570744"]
+
+[project.scripts]
+image3d = "image3d_student.cli:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

recipe/decode.mjs

@@ -0,0 +1,13 @@
+import { NodeIO } from '@gltf-transform/core';
+import { ALL_EXTENSIONS } from '@gltf-transform/extensions';
+import { dequantize } from '@gltf-transform/functions';
+import { MeshoptDecoder } from 'meshoptimizer';
+await MeshoptDecoder.ready;
+const io = new NodeIO().registerExtensions(ALL_EXTENSIONS)
+  .registerDependencies({ 'meshopt.decoder': MeshoptDecoder });
+const doc = await io.read(process.argv[2]);
+await doc.transform(dequantize());
+for (const ext of doc.getRoot().listExtensionsUsed()) {
+  if (ext.extensionName === 'EXT_meshopt_compression') ext.dispose();
+}
+await io.write(process.argv[3], doc);

recipe/package-lock.json

@@ -0,0 +1,784 @@
+{
+  "name": "forma3d-tiny-3-mac",
+  "lockfileVersion": 3,
+  "requires": true,
+  "packages": {
+    "": {
+      "dependencies": {
+        "@gltf-transform/core": "4.5.1",
+        "@gltf-transform/extensions": "4.5.1",
+        "@gltf-transform/functions": "4.5.1",
+        "meshoptimizer": "1.3.0"
+      }
+    },
+    "node_modules/@emnapi/runtime": {
+      "version": "1.11.3",
+      "resolved": "https://registry.npmjs.org/@emnapi/runtime/-/runtime-1.11.3.tgz",
+      "integrity": "sha512-Xz4Tpyki7XyrpbUK1jR1AhdAdaXyhhY4lZ3neLodmhpuWfy2PAQN5B46sAiU4liOXGLkHypn/qU+jvfWSCYYLA==",
+      "license": "MIT",
+      "optional": true,
+      "dependencies": {
+        "tslib": "^2.4.0"
+      }
+    },
+    "node_modules/@gltf-transform/core": {
+      "version": "4.5.1",
+      "resolved": "https://registry.npmjs.org/@gltf-transform/core/-/core-4.5.1.tgz",
+      "integrity": "sha512-OWgBYssKHKoXMIrMb2N20jXqWRnMP9HdtcTFQBEAJtz4P+OOxx5fozl5eAeK7nktIs5uDE/lu4NbkE5VCZaR9g==",
+      "license": "MIT",
+      "dependencies": {
+        "property-graph": "^4.1.0"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/donmccurdy"
+      }
+    },
+    "node_modules/@gltf-transform/extensions": {
+      "version": "4.5.1",
+      "resolved": "https://registry.npmjs.org/@gltf-transform/extensions/-/extensions-4.5.1.tgz",
+      "integrity": "sha512-3jTe+GWRy4fj1TU790LPsO+rpO/4byUWPTpNkjy6M6h8RvrUivRf12Mptc0770K4ZczibpJDNHXZFkFsFMRDLA==",
+      "license": "MIT",
+      "dependencies": {
+        "@gltf-transform/core": "^4.5.1",
+        "ktx-parse": "^1.1.0"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/donmccurdy"
+      }
+    },
+    "node_modules/@gltf-transform/functions": {
+      "version": "4.5.1",
+      "resolved": "https://registry.npmjs.org/@gltf-transform/functions/-/functions-4.5.1.tgz",
+      "integrity": "sha512-rfm4nQY2DJ+ip1e15xp7YfQwhRno3kPLcGw4EZiRk1dVwMV3cdFMcF08glYcO/+oLyYkUEs3xXMJYXa0cPgcTg==",
+      "license": "MIT",
+      "dependencies": {
+        "@gltf-transform/core": "^4.5.1",
+        "@gltf-transform/extensions": "^4.5.1",
+        "ktx-parse": "^1.1.0",
+        "ndarray": "^1.0.19",
+        "ndarray-lanczos": "^0.3.0",
+        "ndarray-pixels": "^5.2.0"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/donmccurdy"
+      }
+    },
+    "node_modules/@img/colour": {
+      "version": "1.1.0",
+      "resolved": "https://registry.npmjs.org/@img/colour/-/colour-1.1.0.tgz",
+      "integrity": "sha512-Td76q7j57o/tLVdgS746cYARfSyxk8iEfRxewL9h4OMzYhbW4TAcppl0mT4eyqXddh6L/jwoM75mo7ixa/pCeQ==",
+      "license": "MIT",
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@img/sharp-darwin-arm64": {
+      "version": "0.35.5",
+      "resolved": "https://registry.npmjs.org/@img/sharp-darwin-arm64/-/sharp-darwin-arm64-0.35.5.tgz",
+      "integrity": "sha512-QRUlFQ0WxvdWyqqG/WtI3iupfD5rBzmCHXSdPsY91sAtVtTo7Q4cb6zOccZ3gqEqkr0f1As1ehLqmEpDsRf+lg==",
+      "cpu": [
+        "arm64"
+      ],
+      "license": "Apache-2.0",
+      "optional": true,
+      "os": [
+        "darwin"
+      ],
+      "engines": {
+        "node": ">=20.9.0"
+      },
+      "funding": {
+        "url": "https://opencollective.com/libvips"
+      },
+      "optionalDependencies": {
+        "@img/sharp-libvips-darwin-arm64": "1.3.4"
+      }
+    },
+    "node_modules/@img/sharp-darwin-x64": {
+      "version": "0.35.5",
+      "resolved": "https://registry.npmjs.org/@img/sharp-darwin-x64/-/sharp-darwin-x64-0.35.5.tgz",
+      "integrity": "sha512-+BR255RhDlpygUpOc/Jdt1nT6DQ3XG/ERo5wbcdOf5Q320dKtPCKPLR1LJs9VGXRaMa8l1uUa0tkCNOXiAxZUw==",
+      "cpu": [
+        "x64"
+      ],
+      "license": "Apache-2.0",
+      "optional": true,
+      "os": [
+        "darwin"
+      ],
+      "engines": {
+        "node": ">=20.9.0"
+      },
+      "funding": {
+        "url": "https://opencollective.com/libvips"
+      },
+      "optionalDependencies": {
+        "@img/sharp-libvips-darwin-x64": "1.3.4"
+      }
+    },
+    "node_modules/@img/sharp-freebsd-wasm32": {
+      "version": "0.35.5",
+      "resolved": "https://registry.npmjs.org/@img/sharp-freebsd-wasm32/-/sharp-freebsd-wasm32-0.35.5.tgz",
+      "integrity": "sha512-Y/z91nEZ4uIBX5X3nfTovjU9lHNKFYbL2lpHCLVNmXQK03VIZvXBBt0KxbPGp2SdGSF+2mQU4e+hQaWOt86iAw==",
+      "license": "Apache-2.0",
+      "optional": true,
+      "os": [
+        "freebsd"
+      ],
+      "dependencies": {
+        "@img/sharp-wasm32": "0.35.5"
+      },
+      "engines": {
+        "node": ">=20.9.0"
+      },
+      "funding": {
+        "url": "https://opencollective.com/libvips"
+      }
+    },
+    "node_modules/@img/sharp-libvips-darwin-arm64": {
+      "version": "1.3.4",
+      "resolved": "https://registry.npmjs.org/@img/sharp-libvips-darwin-arm64/-/sharp-libvips-darwin-arm64-1.3.4.tgz",
+      "integrity": "sha512-5R89nBYiRdUlSWJxPhO+GVtaXzXSxKnRu/xqMn3KTA3L9EB9Oy/P+Nn2f2vlhPuUdy/Zusb2DarbyTpGCfEDuw==",
+      "cpu": [
+        "arm64"
+      ],
+      "license": "LGPL-3.0-or-later",
+      "optional": true,
+      "os": [
+        "darwin"
+      ],
+      "funding": {
+        "url": "https://opencollective.com/libvips"
+      }
+    },
+    "node_modules/@img/sharp-libvips-darwin-x64": {
+      "version": "1.3.4",
+      "resolved": "https://registry.npmjs.org/@img/sharp-libvips-darwin-x64/-/sharp-libvips-darwin-x64-1.3.4.tgz",
+      "integrity": "sha512-iR2OKH80yi0U+dUplyh3/xdpFvps6YkCwsXenIJxqxR1v9o+xtKTGbS9H7cps+2Vxjc8B1j96p75NmTGjIhtpQ==",
+      "cpu": [
+        "x64"
+      ],
+      "license": "LGPL-3.0-or-later",
+      "optional": true,
+      "os": [
+        "darwin"
+      ],
+      "funding": {
+        "url": "https://opencollective.com/libvips"
+      }
+    },
+    "node_modules/@img/sharp-libvips-linux-arm": {
+      "version": "1.3.4",
+      "resolved": "https://registry.npmjs.org/@img/sharp-libvips-linux-arm/-/sharp-libvips-linux-arm-1.3.4.tgz",
+      "integrity": "sha512-LmRtTsOHuvM2+wlO2Db37dx5MiZhB0FvSunciw48YjdOkZz9KAiRbm8ujeMOA1INqmei5NapFxYEK1D1ZSidmw==",
+      "cpu": [
+        "arm"
+      ],
+      "libc": [
+        "glibc"
+      ],
+      "license": "LGPL-3.0-or-later",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "funding": {
+        "url": "https://opencollective.com/libvips"
+      }
+    },
+    "node_modules/@img/sharp-libvips-linux-arm64": {
+      "version": "1.3.4",
+      "resolved": "https://registry.npmjs.org/@img/sharp-libvips-linux-arm64/-/sharp-libvips-linux-arm64-1.3.4.tgz",
+      "integrity": "sha512-Y3dgX/6lE2QhQb+Gxy0WZxfg9MEm/JBjamZpS2IklP7xIQoKN4hzAm7KcMVGtaVDt3neE9OKBC7vAfonA/Lr1A==",
+      "cpu": [
+        "arm64"
+      ],
+      "libc": [
+        "glibc"
+      ],
+      "license": "LGPL-3.0-or-later",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "funding": {
+        "url": "https://opencollective.com/libvips"
+      }
+    },
+    "node_modules/@img/sharp-libvips-linux-ppc64": {
+      "version": "1.3.4",
+      "resolved": "https://registry.npmjs.org/@img/sharp-libvips-linux-ppc64/-/sharp-libvips-linux-ppc64-1.3.4.tgz",
+      "integrity": "sha512-Le6boB8Tai0Nis+gIxIpKx68UDVVIqdR8Tin5Yf1z2LJJQLDJvCDRqRu+jC2qCoD+eIomonmOwB4smBRxfVpYQ==",
+      "cpu": [
+        "ppc64"
+      ],
+      "libc": [
+        "glibc"
+      ],
+      "license": "LGPL-3.0-or-later",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "funding": {
+        "url": "https://opencollective.com/libvips"
+      }
+    },
+    "node_modules/@img/sharp-libvips-linux-riscv64": {
+      "version": "1.3.4",
+      "resolved": "https://registry.npmjs.org/@img/sharp-libvips-linux-riscv64/-/sharp-libvips-linux-riscv64-1.3.4.tgz",
+      "integrity": "sha512-aHkkIEHPRdQEegJN20MLmGtxYD9R2wQr3Cwpddnu5+YKMt6Uzax7S9h5gpZTo8wyrGuZSlfQ63OevL5mTyOC7Q==",
+      "cpu": [
+        "riscv64"
+      ],
+      "libc": [
+        "glibc"
+      ],
+      "license": "LGPL-3.0-or-later",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "funding": {
+        "url": "https://opencollective.com/libvips"
+      }
+    },
+    "node_modules/@img/sharp-libvips-linux-s390x": {
+      "version": "1.3.4",
+      "resolved": "https://registry.npmjs.org/@img/sharp-libvips-linux-s390x/-/sharp-libvips-linux-s390x-1.3.4.tgz",
+      "integrity": "sha512-ra/mB6MikESDUO7Yg+Mi95bFBb9GsObURuhnOv3OqknjGe9sZrG8tCe9q0xSIGrtLgvgw0gKnFWcK4blSgQOuQ==",
+      "cpu": [
+        "s390x"
+      ],
+      "libc": [
+        "glibc"
+      ],
+      "license": "LGPL-3.0-or-later",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "funding": {
+        "url": "https://opencollective.com/libvips"
+      }
+    },
+    "node_modules/@img/sharp-libvips-linux-x64": {
+      "version": "1.3.4",
+      "resolved": "https://registry.npmjs.org/@img/sharp-libvips-linux-x64/-/sharp-libvips-linux-x64-1.3.4.tgz",
+      "integrity": "sha512-GJ//SSXbnwSDes02umB3nDJLFcQzw8a18V8fyhqr6tV515tOEMdImjjxj1AoafMRz56F3PHgftnj1QEKSU1zkw==",
+      "cpu": [
+        "x64"
+      ],
+      "libc": [
+        "glibc"
+      ],
+      "license": "LGPL-3.0-or-later",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "funding": {
+        "url": "https://opencollective.com/libvips"
+      }
+    },
+    "node_modules/@img/sharp-libvips-linuxmusl-arm64": {
+      "version": "1.3.4",
+      "resolved": "https://registry.npmjs.org/@img/sharp-libvips-linuxmusl-arm64/-/sharp-libvips-linuxmusl-arm64-1.3.4.tgz",
+      "integrity": "sha512-hvulFwtjUcagsis6BBxHwGFwWoNZjgYmULGVrZcyfNbjA8hKILbRxGg15/7w5HDyXHXUos/j6baAWqnCyQ2DWA==",
+      "cpu": [
+        "arm64"
+      ],
+      "libc": [
+        "musl"
+      ],
+      "license": "LGPL-3.0-or-later",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "funding": {
+        "url": "https://opencollective.com/libvips"
+      }
+    },
+    "node_modules/@img/sharp-libvips-linuxmusl-x64": {
+      "version": "1.3.4",
+      "resolved": "https://registry.npmjs.org/@img/sharp-libvips-linuxmusl-x64/-/sharp-libvips-linuxmusl-x64-1.3.4.tgz",
+      "integrity": "sha512-6zXKeE/p39I1AmA3cJG35eyBGNqNddLnUXjhwBnsGjFPWqf5VKkDBEqaEkPDoTEtkxwi2vv8Tcr2mDyP4So7Fg==",
+      "cpu": [
+        "x64"
+      ],
+      "libc": [
+        "musl"
+      ],
+      "license": "LGPL-3.0-or-later",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "funding": {
+        "url": "https://opencollective.com/libvips"
+      }
+    },
+    "node_modules/@img/sharp-linux-arm": {
+      "version": "0.35.5",
+      "resolved": "https://registry.npmjs.org/@img/sharp-linux-arm/-/sharp-linux-arm-0.35.5.tgz",
+      "integrity": "sha512-LEaXK2WdXVK5ykcw0buWyPMsmLLL2vpHLD6yrNSW+JGEL3BZPA4tpKN6iaMc4AxTTAoaX/sU1rOL51lcIz48ZQ==",
+      "cpu": [
+        "arm"
+      ],
+      "libc": [
+        "glibc"
+      ],
+      "license": "Apache-2.0",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">=20.9.0"
+      },
+      "funding": {
+        "url": "https://opencollective.com/libvips"
+      },
+      "optionalDependencies": {
+        "@img/sharp-libvips-linux-arm": "1.3.4"
+      }
+    },
+    "node_modules/@img/sharp-linux-arm64": {
+      "version": "0.35.5",
+      "resolved": "https://registry.npmjs.org/@img/sharp-linux-arm64/-/sharp-linux-arm64-0.35.5.tgz",
+      "integrity": "sha512-LYVx5JTsOM2CBzmxreh+nl64/3H6Xb09iSLknqH47z2T2DFFxDeFLP5y4dJwe6H7uGQlHPyEEtIqyo3DYsRwdQ==",
+      "cpu": [
+        "arm64"
+      ],
+      "libc": [
+        "glibc"
+      ],
+      "license": "Apache-2.0",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">=20.9.0"
+      },
+      "funding": {
+        "url": "https://opencollective.com/libvips"
+      },
+      "optionalDependencies": {
+        "@img/sharp-libvips-linux-arm64": "1.3.4"
+      }
+    },
+    "node_modules/@img/sharp-linux-ppc64": {
+      "version": "0.35.5",
+      "resolved": "https://registry.npmjs.org/@img/sharp-linux-ppc64/-/sharp-linux-ppc64-0.35.5.tgz",
+      "integrity": "sha512-QVxAAq8evVRI9ia2vqgwrmWucn5Dfv+JdWzj75pD8omHLPSP7f8p20O8jxzjCcuCEQEOtYOZUmX1hkiZ0kdevA==",
+      "cpu": [
+        "ppc64"
+      ],
+      "libc": [
+        "glibc"
+      ],
+      "license": "Apache-2.0",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">=20.9.0"
+      },
+      "funding": {
+        "url": "https://opencollective.com/libvips"
+      },
+      "optionalDependencies": {
+        "@img/sharp-libvips-linux-ppc64": "1.3.4"
+      }
+    },
+    "node_modules/@img/sharp-linux-riscv64": {
+      "version": "0.35.5",
+      "resolved": "https://registry.npmjs.org/@img/sharp-linux-riscv64/-/sharp-linux-riscv64-0.35.5.tgz",
+      "integrity": "sha512-LtdreXguaavKODPIfzJ4kffx7UNt1omwtK0rch4EBbbSTXPnxWmYSayXdLJw0fJzQ97kHt1gL/yh4tvU+nCyRQ==",
+      "cpu": [
+        "riscv64"
+      ],
+      "libc": [
+        "glibc"
+      ],
+      "license": "Apache-2.0",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">=20.9.0"
+      },
+      "funding": {
+        "url": "https://opencollective.com/libvips"
+      },
+      "optionalDependencies": {
+        "@img/sharp-libvips-linux-riscv64": "1.3.4"
+      }
+    },
+    "node_modules/@img/sharp-linux-s390x": {
+      "version": "0.35.5",
+      "resolved": "https://registry.npmjs.org/@img/sharp-linux-s390x/-/sharp-linux-s390x-0.35.5.tgz",
+      "integrity": "sha512-UZasTOFiYzotTsGOCu42BfUzP6Tu6Do/947iRm1RsLKvlllxwGcn4RN27LibGWceix4Y+Pmw3jsnTcCQIgWjqA==",
+      "cpu": [
+        "s390x"
+      ],
+      "libc": [
+        "glibc"
+      ],
+      "license": "Apache-2.0",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">=20.9.0"
+      },
+      "funding": {
+        "url": "https://opencollective.com/libvips"
+      },
+      "optionalDependencies": {
+        "@img/sharp-libvips-linux-s390x": "1.3.4"
+      }
+    },
+    "node_modules/@img/sharp-linux-x64": {
+      "version": "0.35.5",
+      "resolved": "https://registry.npmjs.org/@img/sharp-linux-x64/-/sharp-linux-x64-0.35.5.tgz",
+      "integrity": "sha512-SxFtLTeJInhAA9Q836kux2vZNeOBQEx658qvbboZScr0wIARym3IcGmW7KpVD5sbVg0Ojy+udFQdayYIZyoNog==",
+      "cpu": [
+        "x64"
+      ],
+      "libc": [
+        "glibc"
+      ],
+      "license": "Apache-2.0",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">=20.9.0"
+      },
+      "funding": {
+        "url": "https://opencollective.com/libvips"
+      },
+      "optionalDependencies": {
+        "@img/sharp-libvips-linux-x64": "1.3.4"
+      }
+    },
+    "node_modules/@img/sharp-linuxmusl-arm64": {
+      "version": "0.35.5",
+      "resolved": "https://registry.npmjs.org/@img/sharp-linuxmusl-arm64/-/sharp-linuxmusl-arm64-0.35.5.tgz",
+      "integrity": "sha512-9HbMclmI1zlNkFRs3z9/eBtDjfD0sGlrX1z6b1qwmiFY5ElDLh4BC0LPBdVp7z1DXFiKlIcznf+ZlsuZzLxQqg==",
+      "cpu": [
+        "arm64"
+      ],
+      "libc": [
+        "musl"
+      ],
+      "license": "Apache-2.0",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">=20.9.0"
+      },
+      "funding": {
+        "url": "https://opencollective.com/libvips"
+      },
+      "optionalDependencies": {
+        "@img/sharp-libvips-linuxmusl-arm64": "1.3.4"
+      }
+    },
+    "node_modules/@img/sharp-linuxmusl-x64": {
+      "version": "0.35.5",
+      "resolved": "https://registry.npmjs.org/@img/sharp-linuxmusl-x64/-/sharp-linuxmusl-x64-0.35.5.tgz",
+      "integrity": "sha512-4KOphqB035HrVdqLZfCgMzzERrQkkzOwRhl4OAkRO1YCldbaFjySXMaK534Mo0V+LndnlJk+sbUyLeU0ULyD1A==",
+      "cpu": [
+        "x64"
+      ],
+      "libc": [
+        "musl"
+      ],
+      "license": "Apache-2.0",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">=20.9.0"
+      },
+      "funding": {
+        "url": "https://opencollective.com/libvips"
+      },
+      "optionalDependencies": {
+        "@img/sharp-libvips-linuxmusl-x64": "1.3.4"
+      }
+    },
+    "node_modules/@img/sharp-wasm32": {
+      "version": "0.35.5",
+      "resolved": "https://registry.npmjs.org/@img/sharp-wasm32/-/sharp-wasm32-0.35.5.tgz",
+      "integrity": "sha512-Ptsga1su4tQx+LLF1ECS9U6nz5kmrXKo6XVbtR48Ke3ZRxxgaWBu7IDtEe1quo8hiupwm6WFqxVlXaSf7IINGQ==",
+      "license": "Apache-2.0 AND LGPL-3.0-or-later AND MIT",
+      "optional": true,
+      "dependencies": {
+        "@emnapi/runtime": "^1.11.3"
+      },
+      "engines": {
+        "node": ">=20.9.0"
+      },
+      "funding": {
+        "url": "https://opencollective.com/libvips"
+      }
+    },
+    "node_modules/@img/sharp-webcontainers-wasm32": {
+      "version": "0.35.5",
+      "resolved": "https://registry.npmjs.org/@img/sharp-webcontainers-wasm32/-/sharp-webcontainers-wasm32-0.35.5.tgz",
+      "integrity": "sha512-hfhF/FmoQyTUkA0bIKFOtw536BQSeBMe6BF6QyWlrPxT754+TFLaZ7sKKTfvvM0yJgKgaYTwnFCIZ/GuDw5SUA==",
+      "cpu": [
+        "wasm32"
+      ],
+      "license": "Apache-2.0",
+      "optional": true,
+      "dependencies": {
+        "@img/sharp-wasm32": "0.35.5"
+      },
+      "engines": {
+        "node": ">=20.9.0"
+      },
+      "funding": {
+        "url": "https://opencollective.com/libvips"
+      }
+    },
+    "node_modules/@img/sharp-win32-arm64": {
+      "version": "0.35.5",
+      "resolved": "https://registry.npmjs.org/@img/sharp-win32-arm64/-/sharp-win32-arm64-0.35.5.tgz",
+      "integrity": "sha512-X4t7g+7ZA5DKblCBEXGjUqqemj4vczING/5viFwAL8h4N3qYeyjwdCvRLHi4EdOUI+2Z7UFlp1VM+p/AuEtm6Q==",
+      "cpu": [
+        "arm64"
+      ],
+      "license": "Apache-2.0 AND LGPL-3.0-or-later",
+      "optional": true,
+      "os": [
+        "win32"
+      ],
+      "engines": {
+        "node": ">=20.9.0"
+      },
+      "funding": {
+        "url": "https://opencollective.com/libvips"
+      }
+    },
+    "node_modules/@img/sharp-win32-ia32": {
+      "version": "0.35.5",
+      "resolved": "https://registry.npmjs.org/@img/sharp-win32-ia32/-/sharp-win32-ia32-0.35.5.tgz",
+      "integrity": "sha512-5Zm82LoBc43nhwNybZlG7Y1KO//Zhsn306fQl29ZOuStHLGTo3BWL83q3cznX0poxSAMuYL1On/BHBxkBeKr6A==",
+      "cpu": [
+        "ia32"
+      ],
+      "license": "Apache-2.0 AND LGPL-3.0-or-later",
+      "optional": true,
+      "os": [
+        "win32"
+      ],
+      "engines": {
+        "node": "^20.9.0"
+      },
+      "funding": {
+        "url": "https://opencollective.com/libvips"
+      }
+    },
+    "node_modules/@img/sharp-win32-x64": {
+      "version": "0.35.5",
+      "resolved": "https://registry.npmjs.org/@img/sharp-win32-x64/-/sharp-win32-x64-0.35.5.tgz",
+      "integrity": "sha512-x76eH0vEiHlcMQu8Y8IenntaACtddpT6W0wmXtWrnKcnKI7ME5DdgqhAD6SEWOEl1v2zDvkZDhFA9KnURwpfqg==",
+      "cpu": [
+        "x64"
+      ],
+      "license": "Apache-2.0 AND LGPL-3.0-or-later",
+      "optional": true,
+      "os": [
+        "win32"
+      ],
+      "engines": {
+        "node": ">=20.9.0"
+      },
+      "funding": {
+        "url": "https://opencollective.com/libvips"
+      }
+    },
+    "node_modules/@types/ndarray": {
+      "version": "1.1.0",
+      "resolved": "https://registry.npmjs.org/@types/ndarray/-/ndarray-1.1.0.tgz",
+      "integrity": "sha512-go+C6vHBUuO9jH6Tj6qEZ63JEGoMSxFdmd+6QAtthGD6xumBfIz3RbNDDs2aoRVLf9naH8lk5jnWy2UHHKgYQQ==",
+      "license": "MIT"
+    },
+    "node_modules/cwise-compiler": {
+      "version": "1.1.3",
+      "resolved": "https://registry.npmjs.org/cwise-compiler/-/cwise-compiler-1.1.3.tgz",
+      "integrity": "sha512-WXlK/m+Di8DMMcCjcWr4i+XzcQra9eCdXIJrgh4TUgh0pIS/yJduLxS9JgefsHJ/YVLdgPtXm9r62W92MvanEQ==",
+      "license": "MIT",
+      "dependencies": {
+        "uniq": "^1.0.0"
+      }
+    },
+    "node_modules/detect-libc": {
+      "version": "2.1.2",
+      "resolved": "https://registry.npmjs.org/detect-libc/-/detect-libc-2.1.2.tgz",
+      "integrity": "sha512-Btj2BOOO83o3WyH59e8MgXsxEQVcarkUOpEYrubB0urwnN10yQ364rsiByU11nZlqWYZm05i/of7io4mzihBtQ==",
+      "license": "Apache-2.0",
+      "engines": {
+        "node": ">=8"
+      }
+    },
+    "node_modules/iota-array": {
+      "version": "1.0.0",
+      "resolved": "https://registry.npmjs.org/iota-array/-/iota-array-1.0.0.tgz",
+      "integrity": "sha512-pZ2xT+LOHckCatGQ3DcG/a+QuEqvoxqkiL7tvE8nn3uuu+f6i1TtpB5/FtWFbxUuVr5PZCx8KskuGatbJDXOWA==",
+      "license": "MIT"
+    },
+    "node_modules/is-buffer": {
+      "version": "1.1.6",
+      "resolved": "https://registry.npmjs.org/is-buffer/-/is-buffer-1.1.6.tgz",
+      "integrity": "sha512-NcdALwpXkTm5Zvvbk7owOUSvVvBKDgKP5/ewfXEznmQFfs4ZRmanOeKBTjRVjka3QFoN6XJ+9F3USqfHqTaU5w==",
+      "license": "MIT"
+    },
+    "node_modules/ktx-parse": {
+      "version": "1.1.0",
+      "resolved": "https://registry.npmjs.org/ktx-parse/-/ktx-parse-1.1.0.tgz",
+      "integrity": "sha512-mKp3y+FaYgR7mXWAbyyzpa/r1zDWeaunH+INJO4fou3hb45XuNSwar+7llrRyvpMWafxSIi99RNFJ05MHedaJQ==",
+      "license": "MIT"
+    },
+    "node_modules/meshoptimizer": {
+      "version": "1.3.0",
+      "resolved": "https://registry.npmjs.org/meshoptimizer/-/meshoptimizer-1.3.0.tgz",
+      "integrity": "sha512-2oZqMAcEEiCtXWUjIGtZ71oPx1B0ZxYGTqIKsXB1wzWFhleNsCFxQuUJzgCV706bRcwPWtMGf1odmQvAcqKkIw==",
+      "license": "MIT"
+    },
+    "node_modules/ndarray": {
+      "version": "1.1.1",
+      "resolved": "https://registry.npmjs.org/ndarray/-/ndarray-1.1.1.tgz",
+      "integrity": "sha512-AsE8w/M2MS+0pD3nP5qbRRtJFeJJJaJ+qXZaZr0XjVGXhy6LIj2TERTlkpdK2AI3WufoOP+pwPk3q2ilAJcZ9g==",
+      "license": "MIT",
+      "dependencies": {
+        "iota-array": "^1.0.0",
+        "is-buffer": "^1.0.2"
+      }
+    },
+    "node_modules/ndarray-lanczos": {
+      "version": "0.3.0",
+      "resolved": "https://registry.npmjs.org/ndarray-lanczos/-/ndarray-lanczos-0.3.0.tgz",
+      "integrity": "sha512-5kBmmG3Zvyj77qxIAC4QFLKuYdDIBJwCG+DukT6jQHNa1Ft74/hPH1z5mbQXeHBt8yvGPBGVrr3wEOdJPYYZYg==",
+      "license": "MIT",
+      "dependencies": {
+        "@types/ndarray": "^1.0.11",
+        "ndarray": "^1.0.19"
+      }
+    },
+    "node_modules/ndarray-ops": {
+      "version": "1.2.2",
+      "resolved": "https://registry.npmjs.org/ndarray-ops/-/ndarray-ops-1.2.2.tgz",
+      "integrity": "sha512-BppWAFRjMYF7N/r6Ie51q6D4fs0iiGmeXIACKY66fLpnwIui3Wc3CXiD/30mgLbDjPpSLrsqcp3Z62+IcHZsDw==",
+      "license": "MIT",
+      "dependencies": {
+        "cwise-compiler": "^1.0.0"
+      }
+    },
+    "node_modules/ndarray-pixels": {
+      "version": "5.2.0",
+      "resolved": "https://registry.npmjs.org/ndarray-pixels/-/ndarray-pixels-5.2.0.tgz",
+      "integrity": "sha512-lTh4tFKziAatVTa9crIsidUyn+lqujVOQpzfdBWvdFu2wo9Uo6z261lVX7SgMyP89xGmj3TMTPbbxl9YDnV4SA==",
+      "license": "MIT",
+      "dependencies": {
+        "@types/ndarray": "^1.0.14",
+        "ndarray": "^1.0.19",
+        "ndarray-ops": "^1.2.2",
+        "sharp": "^0.35.0"
+      }
+    },
+    "node_modules/property-graph": {
+      "version": "4.1.0",
+      "resolved": "https://registry.npmjs.org/property-graph/-/property-graph-4.1.0.tgz",
+      "integrity": "sha512-AvPcP7XECNWy4LGmFQ77k7un4lSKM4eS29PTvW4ck95uYeLxXPWJM7hLuBqK91FaHqCcgJvIUCuNJjjxKE7VKQ==",
+      "license": "MIT"
+    },
+    "node_modules/semver": {
+      "version": "7.8.6",
+      "resolved": "https://registry.npmjs.org/semver/-/semver-7.8.6.tgz",
+      "integrity": "sha512-9lpSSU4Mly3mrtruwLs1eLK6+gzbzqeBFwRNjIjE+9LuDpWdYctrQlQ3ej1Ilgi7gknpsTRnPoLP8DpCHqHIJw==",
+      "license": "ISC",
+      "bin": {
+        "semver": "bin/semver.js"
+      },
+      "engines": {
+        "node": ">=10"
+      }
+    },
+    "node_modules/sharp": {
+      "version": "0.35.5",
+      "resolved": "https://registry.npmjs.org/sharp/-/sharp-0.35.5.tgz",
+      "integrity": "sha512-Ywn4OnzGukp7CDMrp08RQ50YKmuwG47brZgIVPTvBaaAfQlRlygrRqSrxdCiL9M+LlzLBiJ68IR1QqvzHyjC7g==",
+      "license": "Apache-2.0",
+      "dependencies": {
+        "@img/colour": "^1.1.0",
+        "detect-libc": "^2.1.2",
+        "semver": "^7.8.5"
+      },
+      "engines": {
+        "node": ">=20.9.0"
+      },
+      "funding": {
+        "url": "https://opencollective.com/libvips"
+      },
+      "optionalDependencies": {
+        "@img/sharp-darwin-arm64": "0.35.5",
+        "@img/sharp-darwin-x64": "0.35.5",
+        "@img/sharp-freebsd-wasm32": "0.35.5",
+        "@img/sharp-libvips-darwin-arm64": "1.3.4",
+        "@img/sharp-libvips-darwin-x64": "1.3.4",
+        "@img/sharp-libvips-linux-arm": "1.3.4",
+        "@img/sharp-libvips-linux-arm64": "1.3.4",
+        "@img/sharp-libvips-linux-ppc64": "1.3.4",
+        "@img/sharp-libvips-linux-riscv64": "1.3.4",
+        "@img/sharp-libvips-linux-s390x": "1.3.4",
+        "@img/sharp-libvips-linux-x64": "1.3.4",
+        "@img/sharp-libvips-linuxmusl-arm64": "1.3.4",
+        "@img/sharp-libvips-linuxmusl-x64": "1.3.4",
+        "@img/sharp-linux-arm": "0.35.5",
+        "@img/sharp-linux-arm64": "0.35.5",
+        "@img/sharp-linux-ppc64": "0.35.5",
+        "@img/sharp-linux-riscv64": "0.35.5",
+        "@img/sharp-linux-s390x": "0.35.5",
+        "@img/sharp-linux-x64": "0.35.5",
+        "@img/sharp-linuxmusl-arm64": "0.35.5",
+        "@img/sharp-linuxmusl-x64": "0.35.5",
+        "@img/sharp-webcontainers-wasm32": "0.35.5",
+        "@img/sharp-win32-arm64": "0.35.5",
+        "@img/sharp-win32-ia32": "0.35.5",
+        "@img/sharp-win32-x64": "0.35.5"
+      },
+      "peerDependenciesMeta": {
+        "@types/node": {
+          "optional": true
+        }
+      }
+    },
+    "node_modules/tslib": {
+      "version": "2.9.1",
+      "resolved": "https://registry.npmjs.org/tslib/-/tslib-2.9.1.tgz",
+      "integrity": "sha512-a4Ux9VKuIMHsOS7ENbEq6hK2ZGYIT27Rtl0E4eD9KqwxhKiQeMZE/9xb3IdYwWaSOyIBQLExhQgXDTYoiCxnWA==",
+      "license": "0BSD",
+      "optional": true
+    },
+    "node_modules/uniq": {
+      "version": "1.0.1",
+      "resolved": "https://registry.npmjs.org/uniq/-/uniq-1.0.1.tgz",
+      "integrity": "sha512-Gw+zz50YNKPDKXs+9d+aKAjVwpjNwqzvNpLigIruT4HA9lMZNdMqs9x07kKHB/L9WRzqp4+DlTU5s4wG2esdoA==",
+      "license": "MIT"
+    }
+  }
+}

recipe/package.json

@@ -0,0 +1 @@
+{"private":true,"type":"module","dependencies":{"@gltf-transform/core":"4.5.1","@gltf-transform/extensions":"4.5.1","@gltf-transform/functions":"4.5.1","meshoptimizer":"1.3.0"}}

recipe/pipeline.py

@@ -0,0 +1,581 @@
+"""ABO mesh-proxy continuation of Forma3D Tiny 2. No large teacher models run."""
+import argparse
+import fcntl
+import getpass
+import hashlib
+import importlib.util
+import importlib.metadata
+import json
+import math
+from pathlib import Path
+import random
+import re
+import shutil
+import subprocess
+import sys
+import time
+
+BASE = 'Lucasgitguy-co/forma3d-tiny-2'
+BASE_REV = '1648582b07a0f7f9d482a8c0f4cf89e6ecd86972'
+DATA = 'codepawl/abo-glb'
+DATA_REV = 'c7c8293fed3b7ab122ef5d7896521a187e0962d7'
+DEST = 'Lucasgitguy-co/forma3d-tiny-3'
+HERE = Path(__file__).resolve().parent
+
+
+def dump(path, value):
+    path = Path(path)
+    tmp = path.with_suffix(path.suffix + '.tmp')
+    tmp.write_text(json.dumps(value, indent=2, allow_nan=False) + '\n')
+    tmp.replace(path)
+
+
+def sha(path):
+    h = hashlib.sha256()
+    with Path(path).open('rb') as f:
+        for chunk in iter(lambda: f.read(1024 * 1024), b''):
+            h.update(chunk)
+    return h.hexdigest()
+
+
+def read(path):
+    return json.loads(Path(path).read_text())
+
+
+def log(**kw):
+    print(json.dumps(kw, allow_nan=False), flush=True)
+
+
+def authenticate():
+    from huggingface_hub import HfApi, get_token, login
+    token = get_token()
+    if not token:
+        print('Enter a Hugging Face WRITE token for Lucasgitguy-co. Input is hidden.\n'
+              'Create one at https://huggingface.co/settings/tokens', flush=True)
+        token = getpass.getpass('Hugging Face token: ')
+        login(token=token, add_to_git_credential=False)
+    api = HfApi(token=token)
+    identity = api.whoami()
+    owner = DEST.split('/')[0]
+    valid_owner = identity['name'].lower() == owner.lower()
+    valid_org = any(o['name'].lower() == owner.lower() and o.get('roleInOrg') in ('admin', 'write')
+                    for o in identity.get('orgs', []))
+    if not (valid_owner or valid_org):
+        raise RuntimeError(f'This login cannot publish under {owner}. Use a token for that account.')
+    if identity.get('auth', {}).get('accessToken', {}).get('role') == 'read':
+        raise RuntimeError('This is a read-only token. Use a write token.')
+    print('Hugging Face login verified. No repository is created until evaluation passes.', flush=True)
+    return api
+
+
+def upstream(root):
+    from huggingface_hub import snapshot_download
+    source = root / 'upstream'
+    snapshot_download(BASE, revision=BASE_REV, local_dir=source,
+                      allow_patterns=['src/*', 'scripts/prepare_hf.py', 'model.pt', 'config.json',
+                                      'pyproject.toml', 'LICENSE', 'NOTICE', 'THIRD_PARTY.md',
+                                      'licenses/*', 'ATTRIBUTIONS.json', 'README.md'], max_workers=2)
+    sys.path.insert(0, str(source / 'src'))
+    spec = importlib.util.spec_from_file_location('base_prepare', source / 'scripts/prepare_hf.py')
+    mod = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(mod)
+    return source, mod
+
+
+def prepare(root, source, helper, args):
+    import numpy as np
+    from huggingface_hub import hf_hub_download
+    from image3d_student.data import cache_sample, CachedDataset
+    from image3d_student.splats import Splats, preview
+    from image3d_student.engine import split_rows
+    folder = root / 'data'
+    folder.mkdir(exist_ok=True)
+    ready = folder / 'preparation.json'
+    if ready.exists():
+        for split in ('train', 'validation', 'test'):
+            CachedDataset(folder / f'{split}.jsonl')
+        print('Reusing verified prepared data.', flush=True)
+        return folder
+    metadata = hf_hub_download(DATA, 'metadata.jsonl', repo_type='dataset', revision=DATA_REV,
+                               local_dir=root / 'metadata')
+    license_path = hf_hub_download(DATA, 'LICENSE-CC-BY-4.0.txt', repo_type='dataset',
+                                   revision=DATA_REV, local_dir=root / 'metadata')
+    shutil.copy2(license_path, folder / 'LICENSE-ABO-CC-BY-4.0.txt')
+    records = [json.loads(line) for line in Path(metadata).read_text().splitlines() if line.strip()]
+    candidates = [r for r in records if 0 < r.get('triangles', 0) <= 200_000
+                  and 0 < r.get('pack_bytes', 0) <= 8 * 1024**2
+                  and re.fullmatch(r'[A-Za-z0-9_-]+', r['id'])]
+    candidates.sort(key=lambda r: r['id'])
+    random.Random(args.seed).shuffle(candidates)
+    progress = folder / 'progress.json'
+    state = read(progress) if progress.exists() else {'rows': [], 'sources': [], 'skipped': []}
+    rows, sources = state['rows'], state['sources']
+    completed = {s['asset_id'] for s in sources}
+    prior = read(source / 'ATTRIBUTIONS.json')
+    blocked_hashes = set()
+    def visit(x):
+        if isinstance(x, dict):
+            for k, v in x.items():
+                if k == 'sha256' and isinstance(v, str):
+                    blocked_hashes.add(v)
+                visit(v)
+        elif isinstance(x, list):
+            for v in x:
+                visit(v)
+    visit(prior)
+    seen_hashes = {s['sha256'] for s in sources} | blocked_hashes
+    fetch = helper.Downloader(root / 'downloads', 8, 3072, 4)
+    for record in candidates:
+        if len(sources) >= args.objects:
+            break
+        uid = record['id']
+        if uid in completed:
+            continue
+        stage = folder / '_staging'
+        if stage.exists():
+            shutil.rmtree(stage)
+        stage.mkdir()
+        try:
+            filename = f'objects/{uid}/{uid}.glb'
+            raw = fetch.get(DATA, DATA_REV, filename)
+            digest = sha(raw)
+            if digest in seen_hashes:
+                continue
+            decoded = stage / 'decoded.glb'
+            subprocess.run(['node', str(HERE / 'decode.mjs'), str(raw), str(decoded)],
+                           check=True, capture_output=True, text=True, timeout=120)
+            sample_seed = int(digest[:8], 16) ^ args.seed
+            splats, normalization = helper.mesh_splats(decoded, 4096, 16, sample_seed)
+            info = {'repo': DATA, 'revision': DATA_REV, 'path': filename, 'sha256': digest,
+                    'decoded_sha256': sha(decoded), 'asset_id': uid, 'object_id': 'abo-' + uid,
+                    'amazon_item_ids': record.get('amazon_item_ids', []),
+                    'title': record.get('name', uid), 'product_type': record.get('product_type'),
+                    'author': 'Amazon.com; Amazon Berkeley Objects contributors',
+                    'conversion': 'CodePawl GLB conversion; decompressed, normalized and sampled for training',
+                    'license': 'cc-by-4.0', 'license_url': 'https://creativecommons.org/licenses/by/4.0/',
+                    'source_url': f'https://huggingface.co/datasets/{DATA}/blob/{DATA_REV}/{filename}'}
+            new_rows = []
+            for view in range(4):
+                yaw = 2 * np.pi * view / 4
+                c, s = np.cos(yaw), np.sin(yaw)
+                rotation = np.array([[c, 0, s], [0, 1, 0], [-s, 0, c]], np.float32)
+                rotated = Splats(splats.xyz @ rotation.T, splats.rgb, splats.scale,
+                                 splats.quat, splats.opacity)
+                picture = preview(rotated, size=128)
+                if picture.getbbox() is None:
+                    raise ValueError('Invisible proxy render')
+                picture.save(stage / 'input.png')
+                new_rows.append(cache_sample(stage, f'abo-{uid}-v{view}', stage / 'input.png',
+                    rotated, 16, source='mesh-proxy:' + DATA,
+                    extra={**info, 'normalization_matrix': normalization, 'yaw_radians': float(yaw),
+                           'render': 'orthographic Gaussian proxy on black; camera +z',
+                           'target': 'mesh-derived isotropic surface samples; no pretrained teacher'}))
+            for name in ('images', 'targets'):
+                (folder / name).mkdir(exist_ok=True)
+                for p in (stage / name).iterdir():
+                    p.replace(folder / name / p.name)
+            rows.extend(new_rows)
+            sources.append(info)
+            seen_hashes.add(digest)
+            completed.add(uid)
+            dump(progress, state)
+            log(prepared_objects=len(sources), requested=args.objects, asset=uid)
+        except RuntimeError:
+            raise
+        except Exception as exc:
+            error = str(exc)[:300]
+            if isinstance(exc, subprocess.CalledProcessError):
+                error = exc.stderr[-500:]
+            state['skipped'].append({'id': uid, 'error': error})
+            dump(progress, state)
+            log(skipped=uid, error=error)
+            if len(state['skipped']) >= 20 and not sources:
+                raise RuntimeError('Twenty objects failed. Inspect data/progress.json before continuing.') from exc
+        finally:
+            shutil.rmtree(stage, ignore_errors=True)
+    if len(sources) < args.objects:
+        raise RuntimeError(f'Only {len(sources)} usable objects; need {args.objects}. Progress is saved.')
+    # Connect duplicate objects, shared Amazon item IDs and exact rendered data before splitting.
+    parent = {s['object_id']: s['object_id'] for s in sources}
+    def find(x):
+        while parent[x] != x:
+            parent[x] = parent[parent[x]]
+            x = parent[x]
+        return x
+    def union(a, b):
+        a, b = find(a), find(b)
+        parent[max(a, b)] = min(a, b)
+    identities = {}
+    for info in sources:
+        for key in [('mesh', info['sha256'])] + [('amazon', a) for a in info['amazon_item_ids']]:
+            if key in identities:
+                union(info['object_id'], identities[key])
+            identities[key] = info['object_id']
+    for row in rows:
+        for field in ('image_sha256', 'target_sha256'):
+            key = (field, row[field])
+            if key in identities:
+                union(row['metadata']['object_id'], identities[key])
+            identities[key] = row['metadata']['object_id']
+    for row in rows:
+        row['metadata']['object_id'] = find(row['metadata']['object_id'])
+    for info in sources:
+        info['object_id'] = find(info['object_id'])
+    development, test = split_rows(rows, .15, args.seed + 1)
+    training, validation = split_rows(development, .20, args.seed + 2)
+    splits = {'train': training, 'validation': validation, 'test': test}
+    for name, items in splits.items():
+        (folder / f'{name}.jsonl').write_text(''.join(json.dumps(r) + '\n' for r in items))
+        CachedDataset(folder / f'{name}.jsonl')
+    dump(folder / 'sources.json', sources)
+    dump(ready, {'dataset': DATA, 'revision': DATA_REV, 'objects': len(sources), 'views': len(rows),
+                'groups': {k: len({r['metadata']['object_id'] for r in v}) for k, v in splits.items()},
+                'split_views': {k: len(v) for k, v in splits.items()},
+                'manifest_sha256': {k: sha(folder / f'{k}.jsonl') for k in splits},
+                'grouping': 'object IDs, shared Amazon item IDs, exact mesh/image/target hashes',
+                'limitations': 'Near duplicates can remain. Cross-dataset overlap with ancestor training '
+                               'is not fully known; only recorded exact source hashes were excluded.'})
+    return folder
+
+
+def cpu_tree(value):
+    import torch
+    if isinstance(value, torch.Tensor):
+        return value.detach().cpu()
+    if isinstance(value, dict):
+        return {k: cpu_tree(v) for k, v in value.items()}
+    if isinstance(value, list):
+        return [cpu_tree(v) for v in value]
+    if isinstance(value, tuple):
+        return tuple(cpu_tree(v) for v in value)
+    return value
+
+
+def train(root, source, folder, args):
+    import torch
+    from torch.utils.data import DataLoader, default_collate
+    from image3d_student.data import CachedDataset
+    from image3d_student.model import Student, distillation_loss
+    from image3d_student.engine import device_for, evaluate, on_device
+    device = device_for(args.device)
+    torch.manual_seed(args.seed)
+    run = root / 'training'
+    run.mkdir(exist_ok=True)
+    train_data = CachedDataset(folder / 'train.jsonl')
+    val_data = CachedDataset(folder / 'validation.jsonl')
+    val_loader = DataLoader(val_data, batch_size=1, num_workers=0)
+    base = torch.load(source / 'model.pt', map_location='cpu', weights_only=True)
+    if base['config'] != {'grid': 16, 'width': 64} or base['format'] != 1:
+        raise RuntimeError('Unexpected base model architecture.')
+    model = Student(**base['config']).to(device)
+    model.load_state_dict(base['model'], strict=True)
+    optimizer = torch.optim.AdamW(model.parameters(), lr=args.lr, weight_decay=1e-4)
+    rng = random.Random(args.seed)
+    meta = {'base_model': BASE, 'base_revision': BASE_REV, 'base_sha256': sha(source / 'model.pt'),
+            'parameters': sum(p.numel() for p in model.parameters()), 'device': str(device),
+            'torch': str(torch.__version__), 'dataset': DATA, 'dataset_revision': DATA_REV,
+            'steps_requested': args.steps, 'batch_size': args.batch_size, 'learning_rate': args.lr,
+            'seed': args.seed, 'teacher_models_run': [], 'contains_synthetic': False,
+            'rendered_mesh_proxies': True, 'optimizer': 'fresh AdamW, resumed on interruption',
+            'data': read(folder / 'preparation.json')}
+    step, best_step = 0, 0
+    if (run / 'last.pt').exists():
+        last = torch.load(run / 'last.pt', map_location='cpu', weights_only=True)
+        model.load_state_dict(last['model'])
+        optimizer.load_state_dict(last['optimizer'])
+        rng.setstate(last['python_rng'])
+        step, best_step, best_loss = last['step'], last['best_step'], last['best_loss']
+        meta = last['metadata']
+        log(resuming_from_step=step)
+    else:
+        meta['baseline_validation'] = evaluate(model, val_loader, device)
+        best_loss = meta['baseline_validation']['loss']
+        if not math.isfinite(best_loss):
+            raise RuntimeError('Nonfinite baseline evaluation.')
+        dump(run / 'training.json', meta)
+    started = time.monotonic()
+    starting_step = step
+    def save(path, include_optimizer):
+        payload = {'format': 1, 'config': model.config, 'model': cpu_tree(model.state_dict()),
+                   'step': step, 'metadata': meta}
+        if include_optimizer:
+            payload.update(optimizer=cpu_tree(optimizer.state_dict()), python_rng=rng.getstate(),
+                           best_step=best_step, best_loss=best_loss)
+        tmp = path.with_suffix('.tmp')
+        torch.save(payload, tmp)
+        tmp.replace(path)
+    try:
+        while step < args.steps:
+            images, target = default_collate([train_data[rng.randrange(len(train_data))]
+                                               for _ in range(args.batch_size)])
+            model.train()
+            optimizer.zero_grad(set_to_none=True)
+            prediction = model(images.to(device))
+            loss, _ = distillation_loss(prediction, on_device(target, device), model.grid)
+            if not torch.isfinite(loss):
+                raise RuntimeError('Nonfinite training loss; publication disabled.')
+            loss.backward()
+            torch.nn.utils.clip_grad_norm_(model.parameters(), 1., error_if_nonfinite=True)
+            optimizer.step()
+            step += 1
+            if step == 1 or step % 50 == 0:
+                log(step=step, total=args.steps, loss=float(loss.detach()),
+                    elapsed_seconds=round(time.monotonic() - started),
+                    steps_per_second=round((step - starting_step) / max(time.monotonic()-started, .001), 3))
+            if step % args.eval_every == 0 or step == args.steps:
+                metrics = evaluate(model, val_loader, device)
+                if not all(math.isfinite(v) for v in metrics.values()):
+                    raise RuntimeError('Nonfinite validation metrics.')
+                if metrics['loss'] < best_loss:
+                    best_loss, best_step = metrics['loss'], step
+                    save(run / 'best.pt', False)
+                record = {'step': step, 'validation': metrics, 'best_step': best_step}
+                with (run / 'metrics.jsonl').open('a') as f:
+                    f.write(json.dumps(record) + '\n')
+                log(**record)
+                save(run / 'last.pt', True)
+    finally:
+        if step:
+            save(run / 'last.pt', True)
+    if step != args.steps:
+        raise RuntimeError('Training incomplete; no publication.')
+    if not best_step:
+        raise RuntimeError('Validation did not improve over v2. Checkpoints are local; no publication.')
+    dump(run / 'completed.json', {'completed_steps': step, 'selected_step': best_step,
+                                 'best_validation_loss': best_loss})
+    return run
+
+
+def assess(root, source, folder, run, args):
+    import torch
+    from torch.utils.data import DataLoader
+    from image3d_student.data import CachedDataset
+    from image3d_student.model import Student
+    from image3d_student.engine import device_for, evaluate
+    device = device_for(args.device)
+    loader = DataLoader(CachedDataset(folder / 'test.jsonl'), batch_size=1, num_workers=0)
+    result = {}
+    for name, checkpoint in [('base_v2', source / 'model.pt'), ('candidate_v3', run / 'best.pt')]:
+        state = torch.load(checkpoint, map_location='cpu', weights_only=True)
+        model = Student(**state['config']).to(device)
+        model.load_state_dict(state['model'], strict=True)
+        metrics = evaluate(model, loader, device)
+        if not all(math.isfinite(v) for v in metrics.values()):
+            raise RuntimeError('Nonfinite test metrics.')
+        result[name] = {'sha256': sha(checkpoint), 'metrics': metrics}
+        del model
+    before, after = result['base_v2']['metrics'], result['candidate_v3']['metrics']
+    meta = read(run / 'training.json')
+    completed = read(run / 'completed.json')
+    gates = {'training_complete': completed['completed_steps'] == args.steps,
+             'validation_loss_improved': completed['best_validation_loss'] < meta['baseline_validation']['loss'],
+             'test_loss_improved_at_least_half_percent': after['loss'] <= before['loss'] * .995,
+             'test_occupancy_iou_not_worse': after['occupancy_iou'] >= before['occupancy_iou'],
+             'weights_changed': result['base_v2']['sha256'] != result['candidate_v3']['sha256']}
+    report = {**result, 'gates': gates, 'passed': all(gates.values()),
+              'test_manifest_sha256': sha(folder / 'test.jsonl'),
+              'measurement': 'mean per-view proxy loss and occupancy IoU, threshold 0.5, batch size 1',
+              'limitation': 'Not evidence of natural-photo, mesh, texture or photorealistic rendering quality.'}
+    dump(root / 'evaluation.json', report)
+    log(evaluation=report)
+    return report
+
+
+def package(root, source, folder, run, report):
+    release = root / 'release'
+    release.mkdir(exist_ok=True)
+    shutil.copy2(run / 'best.pt', release / 'model.pt')
+    for name in ('LICENSE', 'NOTICE', 'THIRD_PARTY.md', 'config.json'):
+        shutil.copy2(source / name, release / name)
+    for name in ('src', 'licenses'):
+        shutil.copytree(source / name, release / name, dirs_exist_ok=True,
+                        ignore=shutil.ignore_patterns('__pycache__', '*.pyc'))
+    project = (source / 'pyproject.toml').read_text().replace('forma3d-tiny-2', 'forma3d-tiny-3')
+    project = project.replace('version = "0.3.0"', 'version = "0.4.0"')
+    (release / 'pyproject.toml').write_text(project)
+    shutil.copy2(folder / 'LICENSE-ABO-CC-BY-4.0.txt', release / 'licenses/LICENSE-ABO-CC-BY-4.0.txt')
+    for path in (run / 'training.json', run / 'completed.json', run / 'metrics.jsonl',
+                 folder / 'preparation.json', root / 'evaluation.json', root / 'settings.json'):
+        shutil.copy2(path, release / path.name)
+    dump(release / 'ATTRIBUTIONS.json', {'inherited': read(source / 'ATTRIBUTIONS.json'),
+                                       'abo_continuation': read(folder / 'sources.json')})
+    (release / 'splits').mkdir(exist_ok=True)
+    for name in ('train', 'validation', 'test'):
+        shutil.copy2(folder / f'{name}.jsonl', release / 'splits' / f'{name}.jsonl')
+    recipe = release / 'recipe'
+    recipe.mkdir(exist_ok=True)
+    for name in ('pipeline.py', 'decode.mjs', 'requirements.txt', 'package.json', 'package-lock.json', 'run.command'):
+        shutil.copy2(HERE / name, recipe / name)
+    inherited_notice = (release / 'NOTICE').read_text()
+    (release / 'NOTICE').write_text(inherited_notice + '\nABO continuation data: Amazon.com, Amazon Berkeley '
+        'Objects contributors; converted to GLB by CodePawl. CC BY 4.0. Training preprocessing '
+        'decompresses geometry, normalizes objects, samples surface colors and renders Gaussian proxies. '
+        'See ATTRIBUTIONS.json and licenses/LICENSE-ABO-CC-BY-4.0.txt. No endorsement implied.\n')
+    base = report['base_v2']['metrics']
+    candidate = report['candidate_v3']['metrics']
+    prep = read(folder / 'preparation.json')
+    completed = read(run / 'completed.json')
+    (release / 'README.md').write_text(f'''---
+license: apache-2.0
+pipeline_tag: image-to-3d
+base_model: {BASE}
+base_model_relation: finetune
+model_name: Forma3D Tiny 3
+datasets:
+- codepawl/abo-glb
+tags:
+- pytorch
+- gaussian-splatting
+- mesh-proxy-supervision
+- research-prototype
+---
+# Forma3D Tiny 3
+
+Continued from [{BASE}](https://huggingface.co/{BASE}) at `{BASE_REV}`.
+Same 306,321-parameter architecture, 16 cubed grid, width 64, maximum 4,096 Gaussian slots.
+Fresh AdamW optimizer at the start of continuation. Completed {completed['completed_steps']} steps;
+selected step {completed['selected_step']} by validation loss only.
+
+## Data and scope
+
+{prep['objects']} ABO objects, {prep['views']} orthographic Gaussian-proxy images on black.
+Data revision: `{DATA_REV}`. Targets are isotropic mesh surface samples, compressed to
+one Gaussian per occupied grid cell. Texture surface colors are sampled; full PBR rendering
+and differentiable rendering are not used. No natural-photo training is claimed.
+MeshAnythingV2, Idol Diffusers, SHARP, Pixal3D, Idol Turbo and Qwen3.5-4B-3D-Coder
+were **not run, merged, or distilled** in this Mac-only recipe.
+
+Objects, shared Amazon item IDs and exact mesh/image/target hashes are grouped before splitting.
+Split groups: {json.dumps(prep['groups'])}. Test data is excluded from training and checkpoint selection.
+Near duplicates can remain; overlap with ancestor training datasets is not fully known.
+
+## Evaluation
+
+Both checkpoints were evaluated on the identical held-out ABO proxy views.
+
+| Metric | Starting v2 | Selected v3 |
+|---|---:|---:|
+| Mean test loss | {base['loss']:.6f} | {candidate['loss']:.6f} |
+| Mean view occupancy IoU, threshold 0.5 | {base['occupancy_iou']:.6f} | {candidate['occupancy_iou']:.6f} |
+
+These measurements do not establish natural-photo reconstruction, photorealism, mesh quality,
+novel-view rendering quality or improvement on v2's original domains. No confidence intervals
+or broad generalization claim. See evaluation.json, preparation.json and split manifests.
+
+## Use
+
+With Python 3.11, install this repository using `pip install .`, then:
+
+```bash
+image3d generate --checkpoint model.pt --image centered-object-on-black.png --out object.ply --device mps
+image3d preview --ply object.ply --out preview.png
+```
+
+Output is Gaussian PLY, not a textured GLB mesh. Inputs should match centered objects on black.
+The model has no text prompt conditioning. Reproduction launcher and locked dependencies are in recipe/.
+
+## Attribution
+
+Publisher source and weights: Apache 2.0. Retain inherited NOTICE, THIRD_PARTY.md and ATTRIBUTIONS.json.
+ABO models, images and listing text: Amazon.com and the Amazon Berkeley Objects contributors,
+CC BY 4.0; converted to GLB by CodePawl. The recipe further decompresses geometry,
+normalizes coordinates, samples colored surfaces and renders proxy images.
+See [ABO dataset](https://huggingface.co/datasets/codepawl/abo-glb),
+ATTRIBUTIONS.json and licenses/LICENSE-ABO-CC-BY-4.0.txt. Raw assets are not bundled.
+''')
+    freeze = ''.join(sorted(f"{d.metadata['Name']}=={d.version}\n"
+                            for d in importlib.metadata.distributions()))
+    (release / 'environment.txt').write_text(freeze)
+    sums = ''.join(f'{sha(p)}  {p.relative_to(release)}\n' for p in sorted(release.rglob('*'))
+                   if p.is_file() and p.name != 'SHA256SUMS')
+    (release / 'SHA256SUMS').write_text(sums)
+    return release
+
+
+def publish(api, root, release):
+    from huggingface_hub import hf_hub_download
+    from huggingface_hub.errors import RepositoryNotFoundError, EntryNotFoundError
+    marker = root / 'publication.json'
+    expected = sha(release / 'model.pt')
+    try:
+        info = api.model_info(DEST)
+    except RepositoryNotFoundError:
+        info = None
+    if info is not None:
+        try:
+            remote = hf_hub_download(DEST, 'model.pt', revision=info.sha, token=api.token)
+        except EntryNotFoundError:
+            if not marker.exists():
+                raise RuntimeError(f'{DEST} already exists. Refusing to overwrite an unrelated repository.')
+        else:
+            if sha(remote) == expected:
+                print(f'Already published and verified: https://huggingface.co/{DEST}', flush=True)
+                return
+            raise RuntimeError(f'{DEST} already has different weights; refusing to overwrite them.')
+    else:
+        api.create_repo(DEST, repo_type='model', private=False, exist_ok=False)
+        dump(marker, {'repo_id': DEST, 'expected_model_sha256': expected})
+    commit = api.upload_folder(repo_id=DEST, repo_type='model', folder_path=release,
+                               commit_message='Publish evaluated Forma3D Tiny 3 ABO continuation')
+    remote = hf_hub_download(DEST, 'model.pt', revision=commit.oid, token=api.token)
+    if sha(remote) != expected:
+        raise RuntimeError('Uploaded checkpoint verification failed.')
+    dump(marker, {'repo_id': DEST, 'model_sha256': expected, 'commit': commit.oid, 'verified': True})
+    print(f'Published and verified: https://huggingface.co/{DEST}', flush=True)
+
+
+def main():
+    p = argparse.ArgumentParser(description=__doc__)
+    p.add_argument('--root', type=Path, default=HERE / 'run')
+    p.add_argument('--objects', type=int, default=512)
+    p.add_argument('--steps', type=int, default=6000)
+    p.add_argument('--batch-size', type=int, default=4)
+    p.add_argument('--lr', type=float, default=5e-5)
+    p.add_argument('--eval-every', type=int, default=250)
+    p.add_argument('--seed', type=int, default=44)
+    p.add_argument('--device', choices=['mps', 'cpu'], default='mps')
+    p.add_argument('--publish', action='store_true')
+    p.add_argument('--prepare-only', action='store_true')
+    args = p.parse_args()
+    if args.objects < 12 or min(args.steps, args.batch_size, args.eval_every) < 1 or args.lr <= 0:
+        p.error('Need at least 12 objects and positive training settings.')
+    if args.publish and (args.objects < 128 or args.steps < 1000 or args.device != 'mps'):
+        p.error('Publication requires >=128 objects, >=1000 steps and MPS; small runs are tests only.')
+    root = args.root.resolve()
+    root.mkdir(parents=True, exist_ok=True)
+    with (root / '.lock').open('w') as lock:
+        try:
+            fcntl.flock(lock, fcntl.LOCK_EX | fcntl.LOCK_NB)
+        except BlockingIOError:
+            raise RuntimeError('Another run is already using this directory.')
+        settings = {k: v for k, v in vars(args).items() if k not in ('root', 'publish', 'prepare_only')}
+        settings.update(base_revision=BASE_REV, data_revision=DATA_REV, recipe_sha256=sha(__file__))
+        settings_path = root / 'settings.json'
+        if settings_path.exists() and read(settings_path) != settings:
+            raise RuntimeError('Run settings/code changed. Use --root with a new directory.')
+        dump(settings_path, settings)
+        if shutil.disk_usage(root).free < 8 * 1024**3:
+            raise RuntimeError('Need at least 8 GiB free disk space before starting.')
+        api = authenticate() if args.publish and not args.prepare_only else None
+        source, helper = upstream(root)
+        folder = prepare(root, source, helper, args)
+        if args.prepare_only:
+            return
+        run = train(root, source, folder, args)
+        report = assess(root, source, folder, run, args)
+        if not report['passed']:
+            print('Release checks did not pass. Results and checkpoints are saved locally; nothing published.')
+            sys.exit(2)
+        release = package(root, source, folder, run, report)
+        if args.publish:
+            publish(api, root, release)
+        else:
+            print(f'Local test only; no publication. Release package: {release}')
+
+
+if __name__ == '__main__':
+    try:
+        main()
+    except KeyboardInterrupt:
+        print('\nInterrupted. Rerun the same command to continue from saved progress.', file=sys.stderr)
+        sys.exit(130)

recipe/requirements.txt

@@ -0,0 +1,8 @@
+torch==2.15.0
+numpy==2.4.6
+pillow==13.0.0
+plyfile==1.1.5
+trimesh==5.2.0
+scipy==1.17.1
+huggingface-hub==2.4.0
+pyarrow==26.0.0

recipe/run.command

@@ -0,0 +1,27 @@
+#!/bin/bash
+set -euo pipefail
+cd -- "$(dirname -- "$0")"
+export PATH="/opt/homebrew/bin:/usr/local/bin:$PATH"
+if [[ "$(uname -s)" != Darwin || "$(uname -m)" != arm64 ]]; then
+  echo 'Run this launcher in a native Apple Silicon macOS Terminal.'; exit 1
+fi
+if ! command -v uv >/dev/null || ! command -v node >/dev/null || ! command -v npm >/dev/null; then
+  echo 'Missing prerequisites. Install uv and Node.js, then rerun. With Homebrew: brew install uv node'
+  exit 1
+fi
+node -e 'if(Number(process.versions.node.split(".")[0])<20)process.exit(1)' || {
+  echo 'Node.js 20 or later is required.'; exit 1;
+}
+export UV_CACHE_DIR="$PWD/.cache/uv"
+export HF_HOME="$PWD/.cache/huggingface"
+export PYTHONUNBUFFERED=1
+export OMP_NUM_THREADS=4
+export PYTORCH_ENABLE_MPS_FALLBACK=1
+uv venv --python 3.11 --allow-existing .venv
+uv pip install --python .venv/bin/python -r requirements.txt
+if [[ ! -d node_modules ]]; then
+  npm ci --ignore-scripts --no-audit --no-fund
+fi
+echo 'Preparing 512 ABO objects, training 6,000 steps, then evaluating and publishing if the release checks pass.'
+echo 'Keep your Mac connected to power and its lid open. Rerun this same command after an interruption.'
+exec caffeinate -i .venv/bin/python pipeline.py --publish "$@"

settings.json

@@ -0,0 +1,12 @@
+{
+  "objects": 512,
+  "steps": 6000,
+  "batch_size": 4,
+  "lr": 5e-05,
+  "eval_every": 250,
+  "seed": 44,
+  "device": "mps",
+  "base_revision": "1648582b07a0f7f9d482a8c0f4cf89e6ecd86972",
+  "data_revision": "c7c8293fed3b7ab122ef5d7896521a187e0962d7",
+  "recipe_sha256": "33ef603b3550a78eb982138540bcdbbca596d3b3f697368593a6d5ca3ff4b436"
+}

src/image3d_student/__init__.py

@@ -0,0 +1,5 @@
+# SPDX-License-Identifier: Apache-2.0
+# Copyright 2026 Lucasgitguy-co
+"""Research prototype; no pretrained general-purpose student weights are bundled."""
+
+__version__ = "0.2.0"

src/image3d_student/cli.py

@@ -0,0 +1,126 @@
+# SPDX-License-Identifier: Apache-2.0
+# Copyright 2026 Lucasgitguy-co
+import argparse
+import importlib.util
+import json
+import platform
+import shutil
+import sys
+from pathlib import Path
+
+import torch
+
+
+def parser():
+    p = argparse.ArgumentParser(description="Local image-to-Gaussian student research prototype")
+    sub = p.add_subparsers(dest="command", required=True)
+    sub.add_parser("doctor", help="Check dependencies, Metal availability and disk space; no downloads")
+    demo = sub.add_parser("demo-data", help="Create synthetic code-test fixtures, NOT teacher data")
+    demo.add_argument("--out", required=True)
+    demo.add_argument("--count", type=int, default=12)
+    demo.add_argument("--grid", type=int, choices=[8,16,32], default=8)
+    cache = sub.add_parser("cache", help="Cache Idol PLY with optional aligned geometry teacher meshes")
+    cache.add_argument("--image", required=True, help="Exact prepared/framed input used by teacher")
+    cache.add_argument("--idol-ply", required=True)
+    cache.add_argument("--out", required=True)
+    cache.add_argument("--id", required=True)
+    cache.add_argument("--object-id", help="Shared ID for all images of the same object, to prevent validation leakage")
+    cache.add_argument("--grid", type=int, choices=[8,16,32], default=16)
+    cache.add_argument("--coarse-mesh", help="InstantMesh output; this command imports, does not run InstantMesh")
+    cache.add_argument("--coarse-transform", help="JSON 4x4 mesh-to-Idol-PLY matrix")
+    cache.add_argument("--fine-mesh", help="Hi3D output; this command imports, does not run Hi3D")
+    cache.add_argument("--fine-transform", help="JSON 4x4 mesh-to-Idol-PLY matrix")
+    train = sub.add_parser("train", help="Train the student on cached targets")
+    train.add_argument("--manifest", required=True)
+    train.add_argument("--out", required=True)
+    train.add_argument("--device", choices=["auto","cuda","mps","cpu"], default="auto")
+    train.add_argument("--init-from", help="Post-train checkpoint weights; optimizer starts fresh")
+    train.add_argument("--steps", type=int, default=1000)
+    train.add_argument("--batch-size", type=int, default=1)
+    train.add_argument("--width", type=int, default=128)
+    train.add_argument("--lr", type=float, default=3e-4)
+    train.add_argument("--seed", type=int, default=42)
+    train.add_argument("--eval-every", type=int, default=50)
+    train.add_argument("--validation-fraction", type=float, default=.2)
+    train.add_argument("--allow-synthetic", action="store_true")
+    generate = sub.add_parser("generate", help="Generate standard 3DGS PLY with a trained student")
+    generate.add_argument("--checkpoint", required=True)
+    generate.add_argument("--image", required=True, help="Centered cutout or teacher-prepared image, black background")
+    generate.add_argument("--out", required=True)
+    generate.add_argument("--device", choices=["auto","cuda","mps","cpu"], default="auto")
+    generate.add_argument("--threshold", type=float, default=.5)
+    generate.add_argument("--max-splats", type=int, default=32768)
+    render = sub.add_parser("preview", help="CPU diagnostic turntable contact sheet")
+    render.add_argument("--ply", required=True)
+    render.add_argument("--out", required=True)
+    teacher = sub.add_parser("teacher-idol", help="EXPERIMENTAL staged Mac runner; weights not bundled")
+    teacher.add_argument("--image", required=True)
+    teacher.add_argument("--out", required=True)
+    teacher.add_argument("--cache", default=".cache/huggingface")
+    teacher.add_argument("--weights", default="speridlabs/idol")
+    teacher.add_argument("--device", choices=["mps","cpu"], default="mps")
+    teacher.add_argument("--mode", choices=["real","synthetic"], default="synthetic")
+    teacher.add_argument("--steps", type=int, default=20)
+    teacher.add_argument("--gaussians", type=int, default=32768)
+    teacher.add_argument("--query-chunk", type=int, default=128)
+    teacher.add_argument("--seed", type=int, default=42)
+    teacher.add_argument("--allow-download", action="store_true", help="Explicitly allow downloading model weights and gated encoders")
+    return p
+
+
+def main():
+    p = parser()
+    args = p.parse_args()
+    try:
+        if args.command == "doctor":
+            report = {"python": platform.python_version(), "platform": platform.platform(), "torch": str(torch.__version__),
+                      "mps_available": torch.backends.mps.is_available(), "mps_built": torch.backends.mps.is_built(),
+                      "free_disk_gib": round(shutil.disk_usage(Path.cwd()).free / 1024**3, 2),
+                      "idol_installed": importlib.util.find_spec("idol") is not None,
+                      "teacher_status": {"Idol": "experimental adapter, real weights unverified",
+                                         "InstantMesh": "cached mesh import only; no Mac execution adapter",
+                                         "Hi3D": "cached mesh import only; no Mac execution adapter"},
+                      "weights_bundled": False, "quantization": "FP32 student; no binary kernels or 1-bit claims"}
+            print(json.dumps(report, indent=2))
+        elif args.command == "demo-data":
+            from .demo import create_demo
+            print(create_demo(args.out, args.count, args.grid))
+        elif args.command == "cache":
+            from .data import cache_sample
+            from .splats import read_ply
+            print(json.dumps(cache_sample(args.out, args.id, args.image, read_ply(args.idol_ply), args.grid,
+                coarse=args.coarse_mesh, coarse_transform=args.coarse_transform,
+                fine=args.fine_mesh, fine_transform=args.fine_transform,
+                extra={"object_id": args.object_id or args.id, "idol_ply": str(Path(args.idol_ply).resolve())}), indent=2))
+        elif args.command == "train":
+            from .engine import train
+            train(args)
+        elif args.command == "generate":
+            from .engine import generate
+            print(json.dumps(generate(args.checkpoint, args.image, args.out, args.device, args.threshold, args.max_splats), indent=2))
+        elif args.command == "preview":
+            from PIL import Image, ImageDraw
+            import numpy as np
+            from .splats import preview, read_ply
+            splats = read_ply(args.ply)
+            sheet = Image.new("RGB", (1024, 280), "#111111")
+            draw = ImageDraw.Draw(sheet)
+            for i in range(4):
+                sheet.paste(preview(splats, yaw=i*np.pi/2), (i*256, 24))
+                draw.text((i*256+8, 6), f"{i*90} degrees - diagnostic view", fill="white")
+            out = Path(args.out)
+            if out.exists():
+                raise ValueError("Preview already exists")
+            out.parent.mkdir(parents=True, exist_ok=True)
+            sheet.save(out)
+        elif args.command == "teacher-idol":
+            from .teacher_idol import run_idol
+            run_idol(args)
+    except (ValueError, RuntimeError, FileNotFoundError, ImportError) as exc:
+        print(f"Error: {exc}", file=sys.stderr)
+        return 2
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

src/image3d_student/data.py

@@ -0,0 +1,149 @@
+# SPDX-License-Identifier: Apache-2.0
+# Copyright 2026 Lucasgitguy-co
+import hashlib
+import json
+from pathlib import Path
+
+import numpy as np
+import torch
+from PIL import Image, ImageOps
+from torch.utils.data import Dataset
+
+from .splats import Splats, read_ply
+
+
+def grid_centers(grid):
+    axis = (np.arange(grid, dtype=np.float32) + .5) / grid - .5
+    return np.stack(np.meshgrid(axis, axis, axis, indexing="ij"), axis=-1).reshape(-1, 3)
+
+
+def cell_indices(xyz, grid):
+    if not np.isfinite(xyz).all() or (np.abs(xyz) > .50001).any():
+        raise ValueError("Targets must be aligned inside [-0.5,0.5]^3. No silent normalization is performed.")
+    ijk = np.floor((xyz + .5) * grid).astype(np.int64).clip(0, grid-1)
+    return (ijk[:, 0] * grid + ijk[:, 1]) * grid + ijk[:, 2]
+
+
+def splat_targets(splats, grid):
+    """One highest-opacity teacher Gaussian per occupied cell; explicitly lossy."""
+    cells = cell_indices(splats.xyz, grid)
+    order = np.argsort(-splats.opacity[:, 0], kind="stable")
+    _, first = np.unique(cells[order], return_index=True)
+    keep = order[first]
+    slots = cells[keep]
+    result = {"occ": np.zeros((grid**3, 1), np.float32), "xyz": grid_centers(grid),
+              "rgb": np.zeros((grid**3, 3), np.float32),
+              "scale": np.full((grid**3, 3), 1 / grid / 3, np.float32),
+              "quat": np.tile(np.array([1, 0, 0, 0], np.float32), (grid**3, 1)),
+              "opacity": np.zeros((grid**3, 1), np.float32),
+              "geometry": np.zeros((grid**3, 2), np.float32),
+              "geometry_valid": np.zeros(2, np.float32), "grid": np.array(grid, np.int32)}
+    result["occ"][slots] = 1
+    for key in ("xyz", "rgb", "scale", "quat", "opacity"):
+        result[key][slots] = getattr(splats, key)[keep]
+    return result
+
+
+def mesh_occupancy(path, transform_path, grid):
+    import trimesh
+    if not transform_path:
+        raise ValueError("Every geometry teacher needs an explicit --*-transform JSON matrix, even for identity.")
+    transform = np.asarray(json.loads(Path(transform_path).read_text()), dtype=float)
+    if transform.shape != (4, 4) or not np.isfinite(transform).all() or not np.allclose(transform[3], [0,0,0,1]):
+        raise ValueError("Transform must be a finite affine 4x4 matrix")
+    mesh = trimesh.load(str(path), force="mesh", process=False)
+    if not isinstance(mesh, trimesh.Trimesh) or len(mesh.faces) == 0:
+        raise ValueError("Geometry teacher must contain a triangle mesh")
+    mesh.apply_transform(transform)
+    cell_indices(np.asarray(mesh.vertices), grid)  # validates the whole object
+    points, _ = trimesh.sample.sample_surface(mesh, min(200_000, grid**3 * 16), seed=42)
+    mask = np.zeros(grid**3, np.float32)
+    mask[np.unique(cell_indices(points, grid))] = 1
+    return mask
+
+
+def cache_sample(root, sample_id, image_path, splats, grid=16, source="idol",
+                 coarse=None, coarse_transform=None, fine=None, fine_transform=None, extra=None):
+    root = Path(root)
+    if not sample_id or any(c not in "abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789-_" for c in sample_id):
+        raise ValueError("Sample ID may contain only letters, digits, - and _")
+    if grid not in (8, 16, 32):
+        raise ValueError("Grid must be 8, 16 or 32")
+    target = splat_targets(splats, grid)
+    for channel, mesh, transform in [(0, coarse, coarse_transform), (1, fine, fine_transform)]:
+        if mesh:
+            target["geometry"][:, channel] = mesh_occupancy(mesh, transform, grid)
+            target["geometry_valid"][channel] = 1
+    row = {"id": sample_id, "image": f"images/{sample_id}.png", "target": f"targets/{sample_id}.npz",
+           "source": source, "grid": grid, "teachers": {"appearance": source,
+           "coarse": "InstantMesh" if coarse else None, "fine": "Hi3D" if fine else None},
+           "teacher_gaussians": len(splats.xyz), "retained_gaussians": int(target["occ"].sum()),
+           "geometry_transforms": {"coarse": json.loads(Path(coarse_transform).read_text()) if coarse else None,
+                                   "fine": json.loads(Path(fine_transform).read_text()) if fine else None},
+           "metadata": extra or {}}
+    manifest = root / "manifest.jsonl"
+    rows = load_manifest(manifest) if manifest.exists() else []
+    if any(r["id"] == sample_id for r in rows):
+        raise ValueError(f"Sample {sample_id} already exists; choose a new ID")
+    if rows and any(r["grid"] != grid for r in rows):
+        raise ValueError("Do not mix grid resolutions in one dataset")
+    image = Image.open(image_path)
+    image.load()
+    if root.joinpath(row["image"]).exists() or root.joinpath(row["target"]).exists():
+        raise ValueError("Sample files already exist; refusing to overwrite")
+    root.joinpath("images").mkdir(parents=True, exist_ok=True)
+    root.joinpath("targets").mkdir(parents=True, exist_ok=True)
+    image.save(root / row["image"])
+    row["image_sha256"] = hashlib.sha256((root / row["image"]).read_bytes()).hexdigest()
+    np.savez_compressed(root / row["target"], **target)
+    row["target_sha256"] = hashlib.sha256((root / row["target"]).read_bytes()).hexdigest()
+    # Single-writer dataset. Atomic manifest replacement avoids partial JSON lines.
+    tmp = manifest.with_suffix(".tmp")
+    tmp.write_text("".join(json.dumps(r) + "\n" for r in [*rows, row]))
+    tmp.replace(manifest)
+    return row
+
+
+def load_manifest(path):
+    rows = [json.loads(line) for line in Path(path).read_text().splitlines() if line.strip()]
+    if not rows or len({r["id"] for r in rows}) != len(rows):
+        raise ValueError("Manifest must contain nonempty, unique sample IDs")
+    return rows
+
+
+def image_tensor(path, size=128):
+    """Already-framed RGB or RGBA cutout; black background, square letterbox."""
+    with Image.open(path) as original:
+        rgba = ImageOps.exif_transpose(original).convert("RGBA")
+        bg = Image.new("RGBA", rgba.size, (0, 0, 0, 255))
+        bg.alpha_composite(rgba)
+        image = ImageOps.pad(bg.convert("RGB"), (size, size), method=Image.Resampling.LANCZOS, color="black")
+    return torch.from_numpy(np.array(image, dtype=np.float32).transpose(2, 0, 1) / 255)
+
+
+class CachedDataset(Dataset):
+    def __init__(self, manifest, rows=None):
+        self.root = Path(manifest).resolve().parent
+        self.rows = load_manifest(manifest) if rows is None else rows
+        if not self.rows:
+            raise ValueError("Empty dataset")
+        self.grid = self.rows[0]["grid"]
+        for row in self.rows:
+            if row["grid"] != self.grid:
+                raise ValueError("Mixed grids")
+            for key in ("image", "target"):
+                p = (self.root / row[key]).resolve()
+                if not p.is_relative_to(self.root) or not p.is_file():
+                    raise ValueError(f"Invalid dataset {key} path")
+                digest = hashlib.sha256(p.read_bytes()).hexdigest()
+                if digest != row[f"{key}_sha256"]:
+                    raise ValueError(f"Dataset {key} hash mismatch for {row['id']}")
+
+    def __len__(self):
+        return len(self.rows)
+
+    def __getitem__(self, i):
+        row = self.rows[i]
+        with np.load(self.root / row["target"], allow_pickle=False) as cached:
+            target = {k: torch.from_numpy(cached[k].copy()).float() for k in cached.files if k != "grid"}
+        return image_tensor(self.root / row["image"]), target

src/image3d_student/demo.py

@@ -0,0 +1,31 @@
+# SPDX-License-Identifier: Apache-2.0
+# Copyright 2026 Lucasgitguy-co
+from pathlib import Path
+
+import numpy as np
+
+from .data import cache_sample
+from .splats import Splats, preview
+
+
+def create_demo(root, count=12, grid=8):
+    """Procedural ellipsoids only. Never presented as outputs of any real teacher."""
+    if count < 4:
+        raise ValueError("Use at least four fixtures")
+    root = Path(root)
+    root.mkdir(parents=True, exist_ok=True)
+    rng = np.random.default_rng(17)
+    phi, theta = np.meshgrid(np.linspace(.06, np.pi-.06, 14), np.linspace(0, 2*np.pi, 28, endpoint=False))
+    unit = np.stack([np.sin(phi)*np.cos(theta), np.cos(phi), np.sin(phi)*np.sin(theta)], axis=-1).reshape(-1, 3)
+    for i in range(count):
+        radii = rng.uniform(.17, .36, 3)
+        xyz = (unit * radii).astype(np.float32)
+        colour = rng.uniform(.2, .95, 3)
+        rgb = np.clip(colour[None] * (.8 + .2 * unit[:, 1:2]), 0, 1)
+        splats = Splats(xyz, rgb, np.full_like(xyz, .035), np.tile([1,0,0,0], (len(xyz),1)), np.full((len(xyz),1), .9))
+        image_path = root / f"fixture-{i:03}.png"
+        preview(splats, size=128).save(image_path)
+        cache_sample(root, f"fixture-{i:03}", image_path, splats, grid, source="synthetic",
+                     extra={"purpose": "code verification only", "object_id": f"fixture-{i:03}"})
+        image_path.unlink()
+    return root / "manifest.jsonl"

src/image3d_student/engine.py

@@ -0,0 +1,204 @@
+# SPDX-License-Identifier: Apache-2.0
+# Copyright 2026 Lucasgitguy-co
+import json
+import hashlib
+import random
+import time
+from pathlib import Path
+
+import numpy as np
+import torch
+from torch.utils.data import DataLoader
+
+from .data import CachedDataset, image_tensor, load_manifest
+from .model import Student, distillation_loss
+from .splats import Splats, write_ply
+
+
+def device_for(name="auto"):
+    if name == "auto":
+        name = "cuda" if torch.cuda.is_available() else ("mps" if torch.backends.mps.is_available() else "cpu")
+    if name == "mps" and not torch.backends.mps.is_available():
+        raise ValueError("Metal GPU unavailable in this process. Run in a normal macOS Terminal, or use --device cpu.")
+    if name == "cuda" and not torch.cuda.is_available():
+        raise ValueError("CUDA requested but unavailable")
+    if name not in ("mps", "cpu", "cuda"):
+        raise ValueError("Supported devices: cpu, mps, cuda")
+    torch.set_num_threads(min(4, torch.get_num_threads()))
+    return torch.device(name)
+
+
+def split_rows(rows, fraction, seed):
+    if not 0 <= fraction < 1:
+        raise ValueError("Validation fraction must lie in [0,1)")
+    # Keep repeated views/crops of the same object together. Supply object_id in cache metadata.
+    groups = {}
+    for row in rows:
+        group = row.get("metadata", {}).get("object_id", row["id"])
+        groups.setdefault(group, []).append(row)
+    keys = sorted(groups)
+    random.Random(seed).shuffle(keys)
+    n = max(1, round(len(keys) * fraction)) if fraction else 0
+    if n >= len(keys):
+        raise ValueError("Need at least two different objects for validation, or explicitly use --validation-fraction 0 for an overfit test")
+    val_keys = set(keys[:n])
+    train = [r for k in keys if k not in val_keys for r in groups[k]]
+    val = [r for k in keys if k in val_keys for r in groups[k]]
+    if {r["image_sha256"] for r in train} & {r["image_sha256"] for r in val}:
+        raise ValueError("Identical images occur across training/validation. Assign the same object-id to related samples.")
+    return train, val
+
+
+def on_device(target, device):
+    return {k: v.to(device) for k, v in target.items()}
+
+
+@torch.no_grad()
+def evaluate(model, loader, device):
+    model.eval()
+    sums = {}
+    for image, target in loader:
+        target = on_device(target, device)
+        pred = model(image.to(device))
+        loss, terms = distillation_loss(pred, target, model.grid)
+        occupied = pred["occ"].sigmoid() > .5
+        truth = target["occ"] > .5
+        terms = {**terms, "loss": loss, "occupancy_iou": (occupied & truth).sum() / (occupied | truth).sum().clamp_min(1)}
+        for key, value in terms.items():
+            sums[key] = sums.get(key, 0.) + float(value)
+    return {k: v / len(loader) for k, v in sums.items()}
+
+
+def save_checkpoint(path, model, optimizer, step, metadata):
+    payload = {"format": 1, "config": model.config, "model": {k: v.detach().cpu() for k, v in model.state_dict().items()},
+               "optimizer": optimizer.state_dict(), "step": step, "metadata": metadata}
+    tmp = Path(path).with_suffix(".tmp")
+    torch.save(payload, tmp)
+    tmp.replace(path)
+
+
+def train(args):
+    if args.steps < 1 or args.batch_size < 1 or args.lr <= 0 or args.eval_every < 1:
+        raise ValueError("Steps, batch size, learning rate, and evaluation interval must be positive")
+    device = device_for(args.device)
+    random.seed(args.seed)
+    np.random.seed(args.seed)
+    torch.manual_seed(args.seed)
+    rows = load_manifest(args.manifest)
+    synthetic = any(r["source"] == "synthetic" for r in rows)
+    if synthetic and not args.allow_synthetic:
+        raise ValueError("Synthetic fixtures are code tests, not teacher data. Add --allow-synthetic for an explicit smoke test.")
+    train_rows, val_rows = split_rows(rows, args.validation_fraction, args.seed)
+    train_data = CachedDataset(args.manifest, train_rows)
+    generator = torch.Generator().manual_seed(args.seed)
+    loader = DataLoader(train_data, batch_size=args.batch_size, shuffle=True, num_workers=0, generator=generator)
+    val_loader = DataLoader(CachedDataset(args.manifest, val_rows), batch_size=1) if val_rows else None
+    model = Student(train_data.grid, args.width).to(device)
+    initialization = None
+    if getattr(args, "init_from", None):
+        initial_path = Path(args.init_from)
+        state = torch.load(initial_path, map_location="cpu", weights_only=True)
+        if state.get("format") != 1 or state["config"]["width"] != args.width:
+            raise ValueError("Initialization requires format=1 and matching --width")
+        # Coordinates are deterministic buffers, not learned weights. Rebuild them
+        # for the target grid while preserving every learned encoder/decoder weight.
+        learned = {k: v for k, v in state["model"].items() if k not in ("centers", "coords")}
+        result = model.load_state_dict(learned, strict=False)
+        if set(result.missing_keys) != {"centers", "coords"} or result.unexpected_keys:
+            raise ValueError("Checkpoint architecture mismatch")
+        initialization = {"sha256": hashlib.sha256(initial_path.read_bytes()).hexdigest(),
+                          "config": state["config"], "step": state["step"],
+                          "optimizer": "fresh AdamW; weights-only post-training"}
+    optimizer = torch.optim.AdamW(model.parameters(), lr=args.lr, weight_decay=1e-4)
+    run = Path(args.out)
+    if run.exists() and any(run.iterdir()):
+        raise ValueError("Run directory must be empty; choose a new --out directory")
+    run.mkdir(parents=True, exist_ok=True)
+    meta = {"synthetic_only": all(r["source"] == "synthetic" for r in rows),
+            "contains_synthetic": synthetic, "device": str(device), "torch": str(torch.__version__),
+            "seed": args.seed, "train_ids": [r["id"] for r in train_rows], "val_ids": [r["id"] for r in val_rows],
+            "parameters": sum(p.numel() for p in model.parameters()),
+            "teachers": sorted({v for r in rows for v in r["teachers"].values() if v}),
+            "validation": "held-out objects" if val_rows else "none; training overfit test only",
+            "dataset": str(Path(args.manifest).resolve()),
+            "manifest_sha256": hashlib.sha256(Path(args.manifest).read_bytes()).hexdigest(),
+            "initialization": initialization, "steps_requested": args.steps,
+            "learning_rate": args.lr, "batch_size": args.batch_size,
+            "validation_fraction": args.validation_fraction}
+    if val_loader:
+        meta["baseline_validation"] = evaluate(model, val_loader, device)
+    (run / "run.json").write_text(json.dumps(meta, indent=2))
+    print(json.dumps(meta), flush=True)
+    step, best, started = 0, float("inf"), time.monotonic()
+    iterator = iter(loader)
+    try:
+        while step < args.steps:
+            try:
+                images, target = next(iterator)
+            except StopIteration:
+                iterator = iter(loader)
+                images, target = next(iterator)
+            model.train()
+            optimizer.zero_grad(set_to_none=True)
+            pred = model(images.to(device))
+            loss, terms = distillation_loss(pred, on_device(target, device), model.grid)
+            if not torch.isfinite(loss):
+                raise RuntimeError("Nonfinite training loss; stopping")
+            loss.backward()
+            torch.nn.utils.clip_grad_norm_(model.parameters(), 1.)
+            optimizer.step()
+            step += 1
+            if step == 1 or step % args.eval_every == 0 or step == args.steps:
+                record = {"step": step, "seconds": round(time.monotonic()-started, 3),
+                          "train_loss": float(loss.detach()), **{k: float(v.detach()) for k, v in terms.items()}}
+                if val_loader:
+                    record["validation"] = evaluate(model, val_loader, device)
+                    score = record["validation"]["loss"]
+                    if score < best:
+                        best = score
+                        save_checkpoint(run / "best.pt", model, optimizer, step, meta)
+                with (run / "metrics.jsonl").open("a") as handle:
+                    handle.write(json.dumps(record) + "\n")
+                print(json.dumps(record), flush=True)
+                save_checkpoint(run / "last.pt", model, optimizer, step, meta)
+    except KeyboardInterrupt:
+        print("Interrupted; saving completed optimizer steps.", flush=True)
+    finally:
+        if step:
+            save_checkpoint(run / "last.pt", model, optimizer, step, meta)
+    return meta
+
+
+@torch.no_grad()
+def generate(checkpoint, image, out, device="auto", threshold=.5, max_splats=32768):
+    if not 0 < threshold < 1 or max_splats < 1:
+        raise ValueError("Threshold must be in (0,1) and max-splats positive")
+    device = device_for(device)
+    state = torch.load(checkpoint, map_location="cpu", weights_only=True)
+    if state.get("format") != 1 or state.get("step", 0) < 1:
+        raise ValueError("Expected a trained image3d-student checkpoint")
+    model = Student(**state["config"])
+    model.load_state_dict(state["model"])
+    model.to(device).eval()
+    if device.type == "mps":
+        torch.mps.synchronize()
+    started = time.monotonic()
+    pred = model(image_tensor(image)[None].to(device))
+    score = pred["occ"][0, :, 0].sigmoid()
+    valid = torch.nonzero(score >= threshold).flatten()
+    if len(valid) == 0:
+        raise ValueError("No occupied cells above threshold. Train longer or inspect validation; no fabricated fallback splats were exported.")
+    valid = valid[torch.argsort(score[valid], descending=True)[:max_splats]]
+    values = {k: pred[k][0, valid].cpu().numpy() for k in ("xyz", "rgb", "scale", "quat", "opacity")}
+    elapsed = time.monotonic() - started
+    splats = Splats(**values)
+    out = Path(out)
+    if out.exists() or out.with_suffix(".json").exists():
+        raise ValueError("Output already exists; choose a new filename")
+    write_ply(out, splats)
+    report = {"gaussians": len(valid), "seconds_preprocess_and_forward": elapsed,
+              "device": str(device), "checkpoint_step": state["step"], "training": state["metadata"],
+              "note": ("Synthetic-trained output is a pipeline demonstration, not a pretrained image-to-3D result."
+                       if state["metadata"].get("contains_synthetic") else "Experimental cached-target student; inspect unseen-object quality.")}
+    out.with_suffix(".json").write_text(json.dumps(report, indent=2))
+    return report

src/image3d_student/model.py

@@ -0,0 +1,76 @@
+# SPDX-License-Identifier: Apache-2.0
+# Copyright 2026 Lucasgitguy-co
+import math
+
+import torch
+from torch import nn
+from torch.nn import functional as F
+
+from .data import grid_centers
+
+
+class Student(nn.Module):
+    """Small image-conditioned coordinate MLP; fixed cells avoid unordered point regression.
+
+    15 Gaussian outputs + 2 auxiliary geometry logits. This is a coarse baseline,
+    not an architecture expected to reproduce million-splat teacher detail.
+    """
+    def __init__(self, grid=16, width=128):
+        super().__init__()
+        if grid not in (8, 16, 32) or width < 16:
+            raise ValueError("Unsupported grid or width")
+        self.config = {"grid": grid, "width": width}
+        self.grid = grid
+        blocks, channels = [], 3
+        for out in (24, 48, 96, 128):
+            blocks.extend([nn.Conv2d(channels, out, 3, stride=2, padding=1), nn.GroupNorm(8, out), nn.SiLU()])
+            channels = out
+        self.encoder = nn.Sequential(*blocks, nn.AdaptiveAvgPool2d(4), nn.Flatten(),
+                                     nn.Linear(128*4*4, width), nn.SiLU())
+        centers = torch.from_numpy(grid_centers(grid))
+        freq = 2**torch.arange(4, dtype=torch.float32) * math.pi * 2
+        angles = centers[..., None] * freq
+        self.register_buffer("centers", centers)
+        self.register_buffer("coords", torch.cat([centers, angles.sin().flatten(1), angles.cos().flatten(1)], dim=1))
+        self.query = nn.Sequential(nn.Linear(27, width), nn.SiLU())
+        self.decoder = nn.Sequential(nn.Linear(width, width), nn.SiLU(), nn.Linear(width, width), nn.SiLU(), nn.Linear(width, 17))
+        with torch.no_grad():
+            self.decoder[-1].bias.zero_()
+            self.decoder[-1].bias[0] = -2
+
+    def forward(self, images):
+        features = self.encoder(images)
+        raw = self.decoder(features[:, None, :] + self.query(self.coords)[None])
+        quat = raw[..., 10:14] + raw.new_tensor([1, 0, 0, 0])
+        return {"occ": raw[..., :1], "xyz": self.centers[None] + raw[..., 1:4].tanh() / (2*self.grid),
+                "rgb": raw[..., 4:7].sigmoid(),
+                "scale": (raw[..., 7:10].clamp(-8, 5) - math.log(self.grid*3)).exp(),
+                "quat": F.normalize(quat, dim=-1, eps=1e-8), "opacity": raw[..., 14:15].sigmoid(),
+                "geometry": raw[..., 15:17]}
+
+
+def balanced_bce(logits, target):
+    error = F.binary_cross_entropy_with_logits(logits, target, reduction="none")
+    positive = (error * target).sum() / target.sum().clamp_min(1)
+    negative = (error * (1-target)).sum() / (1-target).sum().clamp_min(1)
+    return (positive + negative) / 2
+
+
+def distillation_loss(pred, target, grid):
+    mask = target["occ"]
+    def masked(value):
+        return (value * mask).sum() / (mask.sum().clamp_min(1) * value.shape[-1])
+    terms = {"occupancy": balanced_bce(pred["occ"], mask),
+             "position": masked(((pred["xyz"] - target["xyz"]) * grid).square()),
+             "colour": masked((pred["rgb"] - target["rgb"].clamp(0, 1)).square()),
+             "scale": masked((pred["scale"].log() - target["scale"].clamp_min(1e-8).log()).square()),
+             "rotation": masked(1 - (pred["quat"] * target["quat"]).sum(-1, keepdim=True).square().clamp(0, 1)),
+             "opacity": masked((pred["opacity"] - target["opacity"]).square())}
+    geometry = pred["geometry"].sum() * 0
+    for i in range(2):
+        available = target["geometry_valid"][:, i] > 0
+        if available.any():
+            geometry = geometry + balanced_bce(pred["geometry"][available, :, i:i+1], target["geometry"][available, :, i:i+1])
+    terms["geometry"] = geometry
+    total = terms["occupancy"] + terms["position"] + 2*terms["colour"] + .1*terms["scale"] + .1*terms["rotation"] + terms["opacity"] + .25*geometry
+    return total, terms

src/image3d_student/splats.py

@@ -0,0 +1,108 @@
+# SPDX-License-Identifier: Apache-2.0
+# Copyright 2026 Lucasgitguy-co
+"""Activated Gaussian attributes and standard degree-zero 3DGS PLY IO.
+
+Coordinates are preserved as supplied. Idol's *exported PLY* uses its y-up frame;
+we do not apply Idol's internal z-up conversion a second time.
+"""
+from dataclasses import dataclass
+from pathlib import Path
+
+import numpy as np
+from plyfile import PlyData, PlyElement
+
+C0 = 0.28209479177387814
+
+
+@dataclass
+class Splats:
+    xyz: np.ndarray
+    rgb: np.ndarray
+    scale: np.ndarray
+    quat: np.ndarray  # w,x,y,z
+    opacity: np.ndarray
+
+    def __post_init__(self):
+        n = len(self.xyz)
+        if n == 0:
+            raise ValueError("No Gaussians: refusing to write or train on an empty object.")
+        for name, width in [("xyz", 3), ("rgb", 3), ("scale", 3), ("quat", 4), ("opacity", 1)]:
+            a = np.asarray(getattr(self, name), dtype=np.float32).reshape(-1, width)
+            if a.shape != (n, width) or not np.isfinite(a).all():
+                raise ValueError(f"Invalid {name} shape or nonfinite values")
+            setattr(self, name, a)
+        if (self.scale <= 0).any():
+            raise ValueError("Gaussian scales must be positive")
+        if (self.opacity < 0).any() or (self.opacity > 1).any():
+            raise ValueError("Opacity must lie in [0,1]")
+        norm = np.linalg.norm(self.quat, axis=1, keepdims=True)
+        if (norm < 1e-8).any():
+            raise ValueError("Zero quaternion")
+        self.quat = self.quat / norm
+
+    def take(self, indices):
+        return Splats(**{k: getattr(self, k)[indices] for k in self.__dataclass_fields__})
+
+
+def read_ply(path):
+    v = PlyData.read(str(path))["vertex"].data
+    required = ["x", "y", "z", "f_dc_0", "f_dc_1", "f_dc_2", "opacity",
+                "scale_0", "scale_1", "scale_2", "rot_0", "rot_1", "rot_2", "rot_3"]
+    if not set(required).issubset(v.dtype.names):
+        raise ValueError("Expected a Gaussian-splat PLY, not a mesh or ordinary point-cloud PLY")
+    col = lambda names: np.column_stack([v[k] for k in names]).astype(np.float32)
+    return Splats(col(["x", "y", "z"]), 0.5 + C0 * col([f"f_dc_{i}" for i in range(3)]),
+                  np.exp(np.clip(col([f"scale_{i}" for i in range(3)]), -20, 5)),
+                  col([f"rot_{i}" for i in range(4)]),
+                  1 / (1 + np.exp(-np.clip(col(["opacity"]), -30, 30))))
+
+
+def write_ply(path, splats):
+    path = Path(path)
+    path.parent.mkdir(parents=True, exist_ok=True)
+    names = ["x", "y", "z", "nx", "ny", "nz", "f_dc_0", "f_dc_1", "f_dc_2", "opacity",
+             "scale_0", "scale_1", "scale_2", "rot_0", "rot_1", "rot_2", "rot_3"]
+    opacity = np.clip(splats.opacity, 1e-6, 1 - 1e-6)
+    values = np.concatenate([splats.xyz, np.zeros_like(splats.xyz), (splats.rgb - 0.5) / C0,
+                             np.log(opacity / (1 - opacity)), np.log(splats.scale), splats.quat], axis=1)
+    table = np.empty(len(values), dtype=[(k, "f4") for k in names])
+    for i, name in enumerate(names):
+        table[name] = values[:, i]
+    PlyData([PlyElement.describe(table, "vertex")], text=False).write(str(path))
+
+
+def rotation_matrices(q):
+    w, x, y, z = q.T
+    return np.stack([1-2*(y*y+z*z), 2*(x*y-z*w), 2*(x*z+y*w),
+                     2*(x*y+z*w), 1-2*(x*x+z*z), 2*(y*z-x*w),
+                     2*(x*z-y*w), 2*(y*z+x*w), 1-2*(x*x+y*y)], axis=-1).reshape(-1, 3, 3)
+
+
+def preview(splats, size=256, yaw=0.0):
+    """CPU orthographic Gaussian preview; debugging only, not an evaluation renderer."""
+    from PIL import Image
+    c, s = np.cos(yaw), np.sin(yaw)
+    view = np.array([[c, 0, s], [0, 1, 0], [-s, 0, c]], dtype=np.float32)
+    xyz = splats.xyz @ view.T
+    rot = rotation_matrices(splats.quat)
+    cov = (rot * (splats.scale ** 2)[:, None, :]) @ rot.transpose(0, 2, 1)
+    cov = view[None] @ cov @ view.T[None]
+    pixels = size / 1.25
+    canvas = np.zeros((size, size, 3), dtype=np.float32)
+    # Back to front, camera on +z. Image y points down.
+    for i in np.argsort(xyz[:, 2]):
+        center = np.array([xyz[i, 0], -xyz[i, 1]]) * pixels + size / 2
+        flip = np.diag([1., -1.])
+        covariance = flip @ cov[i, :2, :2] @ flip * pixels ** 2 + np.eye(2) * 0.3
+        radius = min(size, int(np.ceil(3 * np.sqrt(np.linalg.eigvalsh(covariance).max()))))
+        lo = np.maximum(0, np.floor(center - radius).astype(int))
+        hi = np.minimum(size, np.ceil(center + radius + 1).astype(int))
+        if np.any(hi <= lo):
+            continue
+        yy, xx = np.mgrid[lo[1]:hi[1], lo[0]:hi[0]]
+        delta = np.stack([xx - center[0], yy - center[1]], axis=-1)
+        exponent = np.einsum("...i,ij,...j->...", delta, np.linalg.inv(covariance), delta)
+        alpha = (splats.opacity[i, 0] * np.exp(-0.5 * exponent)).clip(0, .99)[..., None]
+        patch = canvas[lo[1]:hi[1], lo[0]:hi[0]]
+        patch[:] = patch * (1-alpha) + np.clip(splats.rgb[i], 0, 1) * alpha
+    return Image.fromarray((canvas.clip(0, 1) * 255).astype(np.uint8))

src/image3d_student/teacher_idol.py

@@ -0,0 +1,141 @@
+# SPDX-License-Identifier: Apache-2.0
+# Copyright 2026 Lucasgitguy-co
+"""Experimental, staged Idol inference for Apple MPS.
+
+Upstream revision: 4702a7f00850e34b6e83a2170cc123c3e9570744.
+No weights are bundled. Full-weight inference has NOT been verified by this project.
+"""
+import gc
+import json
+import os
+import shutil
+from pathlib import Path
+
+import numpy as np
+import torch
+from PIL import Image
+
+from .engine import device_for
+
+
+def patch_attention(layers, query_chunk=128):
+    """Bound attention working memory by splitting only the query dimension.
+
+    Each query still sees ALL keys/values. Does not split or change softmax's key axis.
+    Disable CUDA-specific optimized sampling and avoid complex RoPE tensors on MPS.
+    """
+    if query_chunk < 1:
+        raise ValueError("query_chunk must be positive")
+    from torch.nn import functional as F
+
+    def attention(*args):
+        q, k, v = args[0].unbind(dim=2) if len(args) == 1 else args
+        q, k, v = (t.permute(0, 2, 1, 3) for t in (q, k, v))
+        chunks = [F.scaled_dot_product_attention(q[:, :, start:start+query_chunk], k, v)
+                  for start in range(0, q.shape[2], query_chunk)]
+        return torch.cat(chunks, dim=2).permute(0, 2, 1, 3)
+
+    layers.scaled_dot_product_attention = attention
+    layers.RePo3DRotaryEmbedding.real_valued = True
+    return attention
+
+
+def release(device):
+    gc.collect()
+    if device.type == "mps":
+        torch.mps.synchronize()
+        torch.mps.empty_cache()
+
+
+@torch.no_grad()
+def run_idol(args):
+    if args.steps < 1 or args.gaussians < 32768 or args.gaussians > 1048576 or args.gaussians % 32:
+        raise ValueError("Steps must be positive; Idol requires 32768..1048576 Gaussians, divisible by 32")
+    device = device_for(args.device)
+    cache = Path(args.cache).resolve()
+    cache.mkdir(parents=True, exist_ok=True)
+    os.environ["HF_HOME"] = str(cache)
+    os.environ["HF_HUB_OFFLINE"] = "0" if args.allow_download else "1"
+    os.environ["ATTN_BACKEND"] = "sdpa"
+    if args.allow_download and shutil.disk_usage(cache).free < 16 * 1024**3:
+        raise ValueError("Less than 16 GiB disk space available. This conservative download guard leaves room for teacher weights, encoders and temporary files. Free space, or use an existing complete cache without --allow-download.")
+    try:
+        from huggingface_hub import hf_hub_download, snapshot_download
+        from safetensors.torch import load_file
+        from tensordict import TensorDict
+        from idol.conditioning import ImageEncoder, require_encoder_access
+        from idol.models import BiRefNet, GaussianFixedlenDecoder, LatentSeqMMFlowModel, OctreeProbabilityFixedlenDecoder, layers
+        from idol.preprocess import CROP_MARGIN, preprocess_image, has_real_alpha
+        from idol.sampler import sample_flow
+        from idol.camera import decode_camera
+    except ImportError as exc:
+        raise RuntimeError("Install the optional teacher dependencies: python -m pip install '.[teacher]'") from exc
+    out = Path(args.out)
+    if out.exists():
+        raise ValueError("Teacher output directory already exists; choose a new --out")
+    # Local-only by default. Hugging Face authentication is never written to project files.
+    config_path = hf_hub_download(args.weights, "config.json", local_files_only=not args.allow_download)
+    config = json.loads(Path(config_path).read_text())
+    encoders = config["image_encoders"]
+    require_encoder_access([encoders["dinov3"], encoders["flux2_vae"]])
+    weights = Path(snapshot_download(args.weights, allow_patterns=["config.json", "*.safetensors"],
+                                    local_files_only=not args.allow_download))
+    patch_attention(layers, args.query_chunk)
+    torch.manual_seed(args.seed)
+
+    def load(model, name):
+        state = load_file(str(weights / f"{name}.safetensors"), device="cpu")
+        model.load_state_dict(state, strict=True)
+        del state
+        return model.eval().requires_grad_(False).to(device)
+
+    print("Experimental Idol MPS adapter: full-weight compatibility and quality remain unverified.", flush=True)
+    with Image.open(args.image) as opened:
+        image = opened.copy()
+    background = None
+    if not has_real_alpha(image):
+        print("Stage 1: background removal", flush=True)
+        background = load(BiRefNet(), "birefnet")
+    prepared = preprocess_image(image, background, config["image_size"], CROP_MARGIN[args.mode])
+    del background
+    release(device)
+    pixels = torch.from_numpy(np.array(prepared)).permute(2, 0, 1).float()[None].div(255).to(device)
+    print("Stage 2: image conditioning", flush=True)
+    encoder = ImageEncoder(encoders["dinov3"], encoders["flux2_vae"], device="cpu")
+    # Both encoders initially reside on CPU; only the active encoder is moved to MPS.
+    encoder.dinov3.to(device)
+    feature1 = encoder._dinov3_tokens(pixels)
+    del encoder.dinov3
+    release(device)
+    encoder.flux2_vae.to(device)
+    feature2 = encoder._flux2_tokens(pixels)
+    del encoder, pixels
+    release(device)
+    cond = TensorDict({"feature1": feature1, "feature2": feature2}, batch_size=1, device=device)
+    print("Stage 3: latent sampling", flush=True)
+    model = load(LatentSeqMMFlowModel(**config["denoiser"]["args"]), "denoiser")
+    noise = TensorDict({"latent": torch.randn(1, model.q_token_length, model.in_channels, device=device),
+                        "camera": torch.randn(1, 1, model.cam_channels, device=device)}, batch_size=1, device=device)
+    result = sample_flow(model, noise, cond=cond, neg_cond=cond.apply(torch.zeros_like), steps=args.steps,
+                         rescale_t=3., cfg_strength=3., verbose=True, batch_cfg=False)
+    latent, camera = result["latent"], decode_camera(result["camera"][0, 0])
+    del model, noise, cond, feature1, feature2, result
+    release(device)
+    print("Stage 4: octree decoding", flush=True)
+    model = load(OctreeProbabilityFixedlenDecoder(**config["decoder"]["args"]), "decoder")
+    per_anchor = config["decoder_gs"]["args"]["representation_config"]["num_gaussians"]
+    anchors = OctreeProbabilityFixedlenDecoder.sample(model, latent, num_points=args.gaussians // per_anchor,
+                                                     level=config["max_voxel_level"])
+    del model
+    release(device)
+    print("Stage 5: Gaussian decoding", flush=True)
+    model = load(GaussianFixedlenDecoder(**config["decoder_gs"]["args"]), "decoder_gs")
+    gaussian = model.to_representation(anchors, model(anchors, latent))[0]
+    out.mkdir(parents=True)
+    gaussian.save_ply(str(out / "teacher.ply"))
+    prepared.save(out / "input.png")
+    (out / "metadata.json").write_text(json.dumps({"teacher": args.weights, "steps": args.steps,
+        "gaussians": args.gaussians, "seed": args.seed, "device": str(device), "camera": camera,
+        "sdk_revision": "4702a7f00850e34b6e83a2170cc123c3e9570744", "weights_snapshot": weights.name,
+        "coordinate_frame": "Idol exported PLY (y-up)", "adapter": "experimental staged MPS"}, indent=2))
+    print(f"Teacher output saved to {out}", flush=True)

training.json

@@ -0,0 +1,52 @@
+{
+  "base_model": "Lucasgitguy-co/forma3d-tiny-2",
+  "base_revision": "1648582b07a0f7f9d482a8c0f4cf89e6ecd86972",
+  "base_sha256": "c051b3f93d874f7c638588c9d0381754d3f954b1cd271121a033b2478d36bb1a",
+  "parameters": 306321,
+  "device": "mps",
+  "torch": "2.15.0",
+  "dataset": "codepawl/abo-glb",
+  "dataset_revision": "c7c8293fed3b7ab122ef5d7896521a187e0962d7",
+  "steps_requested": 6000,
+  "batch_size": 4,
+  "learning_rate": 5e-05,
+  "seed": 44,
+  "teacher_models_run": [],
+  "contains_synthetic": false,
+  "rendered_mesh_proxies": true,
+  "optimizer": "fresh AdamW, resumed on interruption",
+  "data": {
+    "dataset": "codepawl/abo-glb",
+    "revision": "c7c8293fed3b7ab122ef5d7896521a187e0962d7",
+    "objects": 512,
+    "views": 2048,
+    "groups": {
+      "train": 348,
+      "validation": 87,
+      "test": 77
+    },
+    "split_views": {
+      "train": 1392,
+      "validation": 348,
+      "test": 308
+    },
+    "manifest_sha256": {
+      "train": "65af1c16cefde7e9cd411af055ccdee36c183382db18a4fd9a9d4ea82fb248ee",
+      "validation": "65ca208e5b7d59d398056c997751b12a18ce05c9361e37f4160f3b1420cbe52a",
+      "test": "c8f927c42ba2ccecd960536de8c7c7431c8fe674401e1fbe7d7613d18cab860d"
+    },
+    "grouping": "object IDs, shared Amazon item IDs, exact mesh/image/target hashes",
+    "limitations": "Near duplicates can remain. Cross-dataset overlap with ancestor training is not fully known; only recorded exact source hashes were excluded."
+  },
+  "baseline_validation": {
+    "occupancy": 0.5408538651877436,
+    "position": 0.0941663452948647,
+    "colour": 0.046021819156333646,
+    "scale": 0.002074153210627231,
+    "rotation": 1.2924113261747727e-05,
+    "opacity": 0.0002730773832950192,
+    "geometry": 0.0,
+    "loss": 0.7275456369950853,
+    "occupancy_iou": 0.2717048296217817
+  }
+}