Release evaluated Forma3D Tiny 2 continuation

COMMANDS.md

@@ -0,0 +1,160 @@
+# Forma3D Tiny 2 on an M4 MacBook Air with 16 GB RAM
+
+This is a proposed weights-only continuation of `Lucasgitguy-co/forma3d-tiny`,
+named `Lucasgitguy-co/forma3d-tiny-2`. It preserves the small FP32 architecture:
+306,321 parameters, grid 16 cubed, decoder width 64. It aims to improve coarse
+proxy reconstruction through more object diversity. No v2 training has been run
+as part of preparing this package, and improvement is not guaranteed.
+
+## Run the commands
+
+Extract the kit into a local folder. Open macOS Terminal in that folder. Use a
+folder stored locally rather than an offloaded iCloud folder. Keep the Mac on
+power and allow cooling during a sustained run.
+
+```bash
+# If uv is not installed, install it with Homebrew first.
+brew install uv
+
+# From the extracted forma3d-tiny-2-kit folder:
+bash posttrain.sh setup
+bash posttrain.sh prepare
+bash posttrain.sh train
+bash posttrain.sh evaluate
+```
+
+Run each command only after the previous one succeeds. Setup downloads the source
+and current v1 weights at the fixed revision
+`e80b8d895cc2e405894473abe4ce40b3472eaca7`. It installs Python 3.11 and the
+publisher's tested dependency lock in an isolated environment under
+`~/Library/Application Support/Forma3D-tiny-2/venv`. Setup does not train or upload.
+`image3d doctor` must report Metal available. These public source files execute
+locally during preparation/training; inspect the scripts before running them.
+
+Preparation requests 128 eligible Scenario meshes plus 128 CC0 Objaverse meshes,
+four views each. It excludes known v1 asset IDs, paths, source groups, and exact
+mesh hashes. It keeps every view of each related object in the same group. A
+separate 15 percent test split is frozen before training. Validation uses 20
+percent of the remaining development groups. Counts depend on duplicate groups;
+read `data/forma3d-v2/preparation.json` and `v2-audit.json` for the realized counts.
+
+The mesh-download budget is 4,096 MiB per preparation invocation, excluding dataset
+metadata and Python packages. It reserves 8 GiB of free disk while fetching meshes.
+Have comfortably more than 12 GiB available before setup and preparation; this is
+a planning allowance, not a measured total. RAM and duration have not been
+benchmarked for this exact v2 recipe. No pretrained teacher is loaded.
+
+Training initializes from **v1 model.pt**, rather than its original ellipsoid
+checkpoint. It uses fresh AdamW, batch size 2, learning rate 0.00005, 8,000 optimizer
+steps, weight decay 0.0001, gradient clipping at norm 1, seed 43, and validation
+every 200 steps. This lower learning rate is a proposed conservative setting, not
+a measured optimum. The best validation loss selects `best.pt`.
+
+The underlying training command is:
+
+```bash
+PY="$HOME/Library/Application Support/Forma3D-tiny-2/venv/bin/python"
+caffeinate -i "$PY" -m image3d_student.cli train \
+  --manifest data/forma3d-v2/manifest.jsonl \
+  --init-from upstream/model.pt \
+  --out runs/forma3d-v2 --device mps --width 64 \
+  --steps 8000 --batch-size 2 --lr 0.00005 \
+  --eval-every 200 --validation-fraction 0.2 --seed 43
+```
+
+Do not substitute grid 32 in this recipe: it increases query cells eightfold and
+changes the evaluation representation. A width change is incompatible with the
+starting learned weights.
+
+## Inspect and optionally publish
+
+Evaluation compares v1 and the selected v2 checkpoint on **the same new test
+objects**, requiring lower test loss and higher test occupancy IoU, plus lower
+validation loss, a completed run, source separation, and nonempty qualitative
+predictions. It writes local comparisons to `runs/forma3d-v2/inspection/` and
+stages `release/forma3d-tiny-2/` only if the gates pass. Inspect these PNGs.
+The release card uses the actual run measurements and correctly records v1 as
+its parent. No scores are prefilled.
+
+The test set is for final assessment. If a release gate fails, do not repeatedly
+tune hyperparameters against that test set. Develop on validation data and reserve
+another genuinely unused object set for a later final claim.
+
+To publish after inspection:
+
+```bash
+"$HOME/Library/Application Support/Forma3D-tiny-2/venv/bin/hf" auth login
+bash posttrain.sh publish
+```
+
+Use your own Hugging Face write token in Terminal, not chat. This command creates
+`Lucasgitguy-co/forma3d-tiny-2` privately, uploads the evaluated package, and makes
+it public after the upload succeeds. It refuses to overwrite an existing repo.
+A failed upload may leave a private partial repo; inspect that repo before
+attempting recovery. Only the staged release folder is uploaded. Raw meshes,
+download caches, credentials, and optimizer state are excluded.
+
+## Generate a Gaussian PLY
+
+Use a centered object cutout on black. Replace the example path with your image:
+
+```bash
+PY="$HOME/Library/Application Support/Forma3D-tiny-2/venv/bin/python"
+"$PY" -m image3d_student.cli generate \
+  --checkpoint runs/forma3d-v2/best.pt --image /path/to/your-cutout.png \
+  --out results/object.ply --device mps
+"$PY" -m image3d_student.cli preview \
+  --ply results/object.ply --out results/preview.png
+```
+
+This model outputs Gaussian PLY, not a GLB or triangle mesh. It has no text
+conditioner, automatic background remover, or verified natural-photo training.
+The training images are renders of mesh-derived Gaussian proxies. The metadata
+flag `contains_synthetic: false` means no procedural smoke-test fixtures; it does
+not mean the input images are photographs or that all upstream meshes are human
+made. Scenario includes generated 3D assets.
+
+## Recovery and adjustments
+
+Dataset preparation can resume: repeat `bash posttrain.sh prepare`. If there are
+not enough eligible assets, edit `--objaverse-shards 16` to 32 in `posttrain.sh`
+and repeat preparation; the upstream parser permits up to 160. If the download
+budget is exhausted, the completed objects remain saved; rerun or increase the
+budget after checking free space. Budgets apply per invocation.
+
+Training requires an empty run directory. Ctrl-C saves completed steps to
+`last.pt`, but the trainer does not implement exact optimizer-state resume.
+The provided release pipeline intentionally expects initialization from pinned
+v1, so a run restarted from an interrupted v2 checkpoint requires a separately
+implemented evaluation/release path and is not supported here. Preserve the old
+run and start a new output directory for a fresh attempt.
+
+For memory pressure, close other large apps and use batch size 1 in a **fresh**
+run. Keep training/evaluation devices consistent. Do not disable the MPS memory
+limit. Do not promise a training duration: the fanless M4 Air may slow under load.
+If evaluation fails, its diagnostic report remains in the run directory and
+nothing is uploaded. Every evaluation staging attempt needs a fresh release path.
+
+## Files and validation
+
+`prepare_v2.py` wraps the pinned upstream preprocessing without changing its
+renderer or labels. `audit_data.py` checks known v1 overlap, cache hashes, and
+split separation. `stage_v2.py` reuses upstream evaluation and writes correct v2
+provenance. `publish_v2.py` verifies a complete SHA256 inventory before upload.
+
+The kit was syntax-checked; its exclusion and data-audit logic was tested with
+small local fixtures. Flag compatibility was checked against the pinned parser.
+The full dataset download, MPS training, and Hugging Face publication were not
+executed. This is a runnable recipe requiring validation on your Mac, not a
+completed training result.
+
+## Primary sources
+
+- [Pinned model and code](https://huggingface.co/Lucasgitguy-co/forma3d-tiny/tree/e80b8d895cc2e405894473abe4ce40b3472eaca7)
+- [Original model commands](https://huggingface.co/Lucasgitguy-co/forma3d-tiny/blob/e80b8d895cc2e405894473abe4ce40b3472eaca7/COMMANDS.md)
+- [Scenario dataset](https://huggingface.co/datasets/scenario-labs/3d-collection/tree/55b4c002b4c1529fc48da3dff98516c3069bfa3f)
+- [Objaverse dataset](https://huggingface.co/datasets/allenai/objaverse/tree/556637099bf4fa79ea7b239d0d9c328b8a2e9ac8)
+
+Preserve per-asset attributions. This package uses the existing Apache 2.0
+implementation. Its source/data filtering additions are provided under Apache
+2.0; the original NOTICE and third-party/data license terms still apply.

DATASETS.md

@@ -0,0 +1,32 @@
+# Data selection and attribution
+
+Reviewed 2026-11-02. User requested commercial-use-compatible data and exclusion
+of noncommercial datasets. This recipe uses only the sources explicitly marked
+included below. Repository-level labels do not replace individual asset terms.
+
+| Source | Status | Reason |
+|---|---|---|
+| [scenario-labs/3d-collection](https://huggingface.co/datasets/scenario-labs/3d-collection) | Included, bounded GLB subset | Explicit CC-BY-4.0 row filter; Hunyuan-labeled models excluded; checksums verified against metadata. Attribution: Scenario; modifications: normalization, surface sampling, Gaussian proxy rendering. |
+| [scenario-labs/3d-collection-hunyuan](https://huggingface.co/datasets/scenario-labs/3d-collection-hunyuan) | Excluded | Dataset expressly prohibits using assets to train or improve AI models. |
+| [3dlg-hcvc/MultiScan](https://huggingface.co/datasets/3dlg-hcvc/MultiScan) | Excluded | CC-BY-NC-4.0, gated scene data. |
+| [huanngzh/3D-Front](https://huggingface.co/datasets/huanngzh/3D-Front) | Excluded | CC-BY-NC-4.0, indoor scenes rather than directly aligned object targets. |
+| [facebook/show3d-dataset](https://huggingface.co/datasets/facebook/show3d-dataset) | Excluded | CC-BY-NC-4.0; interaction/video data needs a separate task-specific pipeline. |
+| [Voxel51/gaussian_splatting](https://huggingface.co/datasets/Voxel51/gaussian_splatting) | Deferred; not used | Card labels Apache-2.0 and describes a few scene reconstructions. This object-centered recipe does not establish camera alignment, object crops, or source-scene rights from the card alone. No importer or download is provided. |
+| [allenai/objaverse](https://huggingface.co/datasets/allenai/objaverse) | Added: CC0 assets only | Dataset compilation is ODC-By; assets have separate licenses. Script accepts only individual `cc0` metadata entries, retains author/title/source links, and excludes animated assets. |
+| [allenai/objaverse-xl](https://huggingface.co/datasets/allenai/objaverse-xl) | Future candidate; not used | Heterogeneous per-file licensing; no blanket commercial-use assumption or importer in this kit. |
+
+Pinned revisions:
+
+- Scenario: `55b4c002b4c1529fc48da3dff98516c3069bfa3f`
+- Objaverse: `556637099bf4fa79ea7b239d0d9c328b8a2e9ac8`
+- Original model: `1738cdfaf1bb940bf576a96d11b742ce014b9139`
+
+The actual asset inventory is generated as `sources.json`, with asset IDs, source
+URLs, authors, licenses, revision IDs and SHA-256 hashes. Published releases copy
+this file to `ATTRIBUTIONS.json`. Keep it with the released model. Rejected assets
+are recorded in `skipped.json`. The model card must not list excluded or merely
+considered datasets as training sources.
+
+License references: [CC-BY-4.0](https://creativecommons.org/licenses/by/4.0/),
+[CC0](https://creativecommons.org/publicdomain/zero/1.0/),
+[ODC-By](https://opendatacommons.org/licenses/by/1-0/).

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,11 @@
+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.

README.md

@@ -0,0 +1,68 @@
+---
+license: apache-2.0
+pipeline_tag: image-to-3d
+base_model: Lucasgitguy-co/forma3d-tiny
+base_model_relation: finetune
+model_name: Forma3D Tiny 2
+datasets:
+- allenai/objaverse
+- scenario-labs/3d-collection
+tags:
+- pytorch
+- gaussian-splatting
+- mesh-proxy-supervision
+- research-prototype
+---
+# Forma3D Tiny 2
+
+A 306,321-parameter image-to-Gaussian research model continued from
+Lucasgitguy-co/forma3d-tiny at revision `e80b8d895cc2e405894473abe4ce40b3472eaca7`. The optimizer starts fresh. It uses a
+16 cubed grid and width 64.
+Selected checkpoint step 7800 from 8000 completed steps.
+
+## Training
+
+See training.json and metrics.jsonl for actual optimizer settings and validation
+history. Inputs are orthographic renders of centered mesh-derived Gaussian proxy
+clouds on black. Targets are isotropic surface samples compressed to one Gaussian
+per occupied grid cell. No pretrained 3D teacher was run. No natural-photo training
+or differentiable rendering is claimed. Asset IDs, known source groups, and exact
+mesh hashes from all 96 known v1 assets were excluded. Near duplicates can remain.
+The separate 15 percent object-group test split does not enter checkpoint selection;
+20 percent of development groups supply validation. Counts are realized counts in
+preparation.json and data-audit.json, not assumed independent asset counts.
+
+## Evaluation
+
+Both checkpoints were evaluated on the same new held-out proxy data.
+
+| Metric | Starting Forma3D Tiny | Selected Forma3D Tiny 2 |
+|---|---:|---:|
+| Mean test loss | 0.616513 | 0.570490 |
+| Mean view occupancy IoU at threshold 0.5 | 0.286327 | 0.327870 |
+
+Test groups: 36; views: 156.
+See evaluation.json for hashes and release gates. Metrics are view-averaged over
+proxy renders. They do not establish photo realism, novel-view image quality,
+mesh quality, texture fidelity, gameplay, or general-purpose 3D reconstruction.
+
+## Use
+
+Install this source with Python 3.11 and `uv pip install ".[data]"` in a virtual
+environment, then run:
+
+```bash
+image3d generate --checkpoint model.pt --image your-centered-cutout.png \
+  --out results/object.ply --device mps
+image3d preview --ply results/object.ply --out results/preview.png
+```
+
+Output is Gaussian PLY. Inputs should match centered objects on black. See
+COMMANDS.md for the complete continuation recipe. This model retains the same
+architecture; no text-prompt conditioning or new mesh decoder was added.
+
+## License
+
+Publisher source and weights are offered under Apache 2.0. Retain NOTICE,
+THIRD_PARTY.md and ATTRIBUTIONS.json. CC BY Scenario assets and CC0 Objaverse
+assets have their own attribution and license records in DATASETS.md.

SHA256SUMS

@@ -0,0 +1,33 @@
+78da3c349a48a35a9377f255731816f6305b9f9bd6a4a1bd2e8558f730b235bc  ATTRIBUTIONS.json
+65c732b729f360fc635af852cbf9a806cade0ddd39fb8796d438b93ce6afdedc  COMMANDS.md
+4c09bfeb821d41b9da58c9a20c28c4000f40956f4359a04274556436a4ed009f  DATASETS.md
+cfc7749b96f63bd31c3c42b5c471bf756814053e847c10f3eb003417bc523d30  LICENSE
+05f38086626c05b43280173a453858ff2eb4273d63b554c94492c64f09a20ab3  NOTICE
+345b746672faf2fcc79e7936de113ef7c16ce3c2e4d65220c2c7e5a0aaafc083  README.md
+ef7c689f184a7921b02887eeb8d859e8cca77da6d2082999bb19bf29beda61f1  THIRD_PARTY.md
+171d8c1bbcbdff4c7e1e30c139a38ee213de626c25efc94e109eed53a052eb3a  audit_data.py
+25d53c6500d9e45aca8a2ce1fe54030e05a0822c554ab24cfcbfeaa631ee9c91  config.json
+91e4d34b8eb0ebffd9ba574780df886dd2e2a27fcc860d4456477e62a71a676e  data-audit.json
+c3bb8be792cef70bbb0f2db68a7008d63770ebaf935f79064157705b06630872  environment.txt
+27bdd414748a7e0ceccfce35b7f3c6dbc5398c5c35ef1bfc7f4538d0d437ada0  evaluation.json
+cfc7749b96f63bd31c3c42b5c471bf756814053e847c10f3eb003417bc523d30  licenses/Idol-APACHE-2.0.txt
+cabfa52ac7194eff926410d8c1d009eae46eb0baf5ec9d8702a16155d503d242  metrics.jsonl
+c051b3f93d874f7c638588c9d0381754d3f954b1cd271121a033b2478d36bb1a  model.pt
+ac809ac48df5c9227cf88e723d3be0befd719902924254e577bf82622558994c  posttrain.sh
+74f287ea799dbcad69fe61ad6bc176d890883a7ac0c1489a72ab8348d2947439  preparation.json
+c4c25055a96becb3996885e204e9a70e94b706c1d5dd5e58bd2ade038f3e80cd  prepare_v2.py
+5f87c57440379f6de332b75450c0a60e7e5c287f2ef4147cc69e1b77e70341ff  publish_v2.py
+05b58f19668b5c7778ac9aa9d1aee03eb60771b9850a138533fda97498dd5e46  pyproject.toml
+53dc8f90461d899ed8c15574c3e96f9bf07da4d3ee783a47ec3a3b077b6ee9ca  requirements-tested-macos.txt
+03325cb525f9e0562865f8df123678a147db38680b024f0845482dc2d5bc1651  scripts/prepare_hf.py
+96f7df49a214e05b86c2d86023d6500986a4d17b2dfe8b23ab7d213d75375fad  scripts/release.py
+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
+78f2c8dbf24c7b2eaba4bc203e7b15e2fd8d043c5509b788bd1565773d31478a  stage_v2.py
+0148fd204dd45f37ed53746859cf1d953ac49d16aa9cf3bcd77946a4c4f8c613  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.

audit_data.py

@@ -0,0 +1,59 @@
+"""Check published source identities plus split and exact-byte separation."""
+import hashlib
+import json
+import sys
+from pathlib import Path
+
+
+def identity_sets(rows):
+    result = {'asset': set(), 'path': set(), 'group': set(), 'sha256': set()}
+    for r in rows:
+        repo = r['repo']
+        if r.get('asset_id'): result['asset'].add((repo, r['asset_id']))
+        if r.get('path'): result['path'].add((repo, r['path']))
+        for key in ('object_id', 'source_object_id'):
+            if r.get(key): result['group'].add((repo, r[key]))
+        if r.get('sha256'): result['sha256'].add(r['sha256'])
+    return result
+
+
+def conflicts(row, blocked):
+    current = identity_sets([row])
+    return any(current[k] & blocked[k] for k in blocked)
+
+
+def audit(data, original):
+    data, original = Path(data), Path(original)
+    old = json.loads(original.read_text())
+    new = json.loads((data / 'sources.json').read_text())
+    blocked = identity_sets(old)
+    if any(conflicts(r, blocked) for r in new):
+        raise ValueError('v1 identity or mesh-byte overlap detected')
+    dev, test = [[json.loads(s) for s in (data / f).read_text().splitlines() if s.strip()]
+                 for f in ('manifest.jsonl', 'test-manifest.jsonl')]
+    if not dev or not test:
+        raise ValueError('Both development and test data must be nonempty')
+    for rows in (dev, test):
+        for row in rows:
+            if conflicts(row['metadata'], blocked):
+                raise ValueError('Manifest includes a known v1 source')
+            for kind in ('image', 'target'):
+                p = (data / row[kind]).resolve()
+                if not p.is_relative_to(data.resolve()):
+                    raise ValueError('Manifest path escapes dataset directory')
+                if hashlib.sha256(p.read_bytes()).hexdigest() != row[kind + '_sha256']:
+                    raise ValueError('Cached file checksum mismatch')
+    for getter in (lambda r:r['metadata']['object_id'], lambda r:r['image_sha256'], lambda r:r['target_sha256']):
+        if {getter(r) for r in dev} & {getter(r) for r in test}:
+            raise ValueError('Development/test overlap detected')
+    report = {'known_v1_sources_excluded': len(old), 'new_mesh_assets':len(new),
+              'development_samples':len(dev), 'test_samples':len(test),
+              'test_object_groups':len({r['metadata']['object_id'] for r in test}),
+              'checks':'source IDs, groups, source hashes, cache hashes, split groups and exact bytes',
+              'limitation':'Semantic near duplicates and unknown upstream overlap can remain.'}
+    (data / 'v2-audit.json').write_text(json.dumps(report, indent=2))
+    print(json.dumps(report, indent=2))
+    return report
+
+if __name__ == '__main__':
+    audit(*sys.argv[1:])

config.json

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

data-audit.json

@@ -0,0 +1,9 @@
+{
+  "known_v1_sources_excluded": 96,
+  "new_mesh_assets": 256,
+  "development_samples": 868,
+  "test_samples": 156,
+  "test_object_groups": 36,
+  "checks": "source IDs, groups, source hashes, cache hashes, split groups and exact bytes",
+  "limitation": "Semantic near duplicates and unknown upstream overlap can remain."
+}

environment.txt

@@ -0,0 +1,33 @@
+anyio==4.16.0
+click==8.5.0
+filelock==4.2.7
+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
+iniconfig==2.3.1
+jinja2==3.1.6
+markupsafe==3.0.4
+mpmath==1.3.0
+networkx==3.6.1
+numpy==2.4.6
+packaging==26.3
+pillow==13.0.0
+pluggy==1.7.0
+plyfile==1.1.5
+pyarrow==26.0.0
+pygments==2.21.0
+pytest==9.2.0
+pyyaml==6.0.3
+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
+# Local forma3d-tiny 0.2.0 source: Lucasgitguy-co/forma3d-tiny @ e80b8d895cc2e405894473abe4ce40b3472eaca7

evaluation.json

@@ -0,0 +1,40 @@
+{
+  "checkpoint_sha256": "e0fd24520297a11102412ba8cf5a0fcc1f1103100368d0a438ca63507f581665",
+  "base_sha256": "83c065d2a50cf086928542cf8d40dc4416b379e38b9aa61d842dc9106d4b3306",
+  "test_manifest_sha256": "5d93ad4fb6c0b9047d06aeae0bd8df76bedcbb3a591d39e00f112c2d7cabfcb1",
+  "test_objects": 36,
+  "test_samples": 156,
+  "baseline_test": {
+    "occupancy": 0.45381076557513994,
+    "position": 0.09375727468003066,
+    "colour": 0.03423368351128048,
+    "scale": 0.0023920839437498497,
+    "rotation": 9.140115868761383e-05,
+    "opacity": 0.00022972543981781293,
+    "geometry": 0.0,
+    "loss": 0.6165134836083803,
+    "occupancy_iou": 0.28632665831500137
+  },
+  "posttrained_test": {
+    "occupancy": 0.4105527498401128,
+    "position": 0.093269259071885,
+    "colour": 0.033224766163561396,
+    "scale": 0.001095225648150051,
+    "rotation": 5.7498695502416895e-06,
+    "opacity": 0.00010812017677754062,
+    "geometry": 0.0,
+    "loss": 0.5704897603927515,
+    "occupancy_iou": 0.32786990109926617
+  },
+  "checks": {
+    "validation_loss_improved": true,
+    "test_loss_improved": true,
+    "test_occupancy_iou_improved": true,
+    "test_occupancy_iou_at_least_005": true
+  },
+  "passed": true,
+  "scope": "Rendered mesh-proxy evaluation only; does not establish real-photo or mesh reconstruction quality",
+  "base_model": "Lucasgitguy-co/forma3d-tiny",
+  "base_revision": "e80b8d895cc2e405894473abe4ce40b3472eaca7",
+  "published_model_sha256": "c051b3f93d874f7c638588c9d0381754d3f954b1cd271121a033b2478d36bb1a"
+}

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.

metrics.jsonl

@@ -0,0 +1,41 @@
+{"step": 1, "seconds": 2.226, "train_loss": 0.7118504047393799, "occupancy": 0.5707302093505859, "position": 0.09329640120267868, "colour": 0.02375972457230091, "scale": 0.00139362714253366, "rotation": 0.00013228011084720492, "opacity": 0.00015177681052591652, "geometry": 0.0, "validation": {"occupancy": 0.4518862460222509, "position": 0.0943518355074856, "colour": 0.033528136679928544, "scale": 0.00237332220422104, "rotation": 0.00010222768609714371, "opacity": 0.000220453495194306, "geometry": 0.0, "loss": 0.6137623639570342, "occupancy_iou": 0.2452177435159683}}
+{"step": 200, "seconds": 9.907, "train_loss": 0.6102267503738403, "occupancy": 0.3629882037639618, "position": 0.1010059267282486, "colour": 0.07303024083375931, "scale": 0.001368745812214911, "rotation": 3.1407173082698137e-05, "opacity": 3.210359864169732e-05, "geometry": 0.0, "validation": {"occupancy": 0.4392792442606555, "position": 0.09434974806176291, "colour": 0.03353508860131519, "scale": 0.0019467268908758544, "rotation": 7.532406785281233e-05, "opacity": 0.0001515494514706006, "geometry": 0.0, "loss": 0.6010529238316747, "occupancy_iou": 0.2503086172665159}}
+{"step": 400, "seconds": 17.151, "train_loss": 0.36874061822891235, "occupancy": 0.23984085023403168, "position": 0.09525543451309204, "colour": 0.016660282388329506, "scale": 0.0022550125140696764, "rotation": 5.368763959268108e-05, "opacity": 9.286287968279794e-05, "geometry": 0.0, "validation": {"occupancy": 0.4414640225470066, "position": 0.09427301647762458, "colour": 0.03249235675450311, "scale": 0.0021028166339318788, "rotation": 5.6945074523658455e-05, "opacity": 0.00013960947958366888, "geometry": 0.0, "loss": 0.6010773383908802, "occupancy_iou": 0.24863199333970745}}
+{"step": 600, "seconds": 26.22, "train_loss": 0.6636115312576294, "occupancy": 0.557167649269104, "position": 0.09432454407215118, "colour": 0.005989818833768368, "scale": 0.0010824797209352255, "rotation": 2.2256899683270603e-05, "opacity": 2.9281885872478597e-05, "geometry": 0.0, "validation": {"occupancy": 0.44066500614086784, "position": 0.09423391732076804, "colour": 0.03306895266545729, "scale": 0.0017604425968278923, "rotation": 5.2143132658481285e-05, "opacity": 0.00013570198060885256, "geometry": 0.0, "loss": 0.6013537890381283, "occupancy_iou": 0.26753482399508355}}
+{"step": 800, "seconds": 33.596, "train_loss": 0.709161102771759, "occupancy": 0.5743151307106018, "position": 0.09445250779390335, "colour": 0.019850170239806175, "scale": 0.004002443514764309, "rotation": 3.6538607673719525e-05, "opacity": 0.0002892622142098844, "geometry": 0.0, "validation": {"occupancy": 0.4343525725106398, "position": 0.09426615482403172, "colour": 0.031267428182117224, "scale": 0.0022783598438965986, "rotation": 5.059475087768482e-05, "opacity": 0.00017218820794874369, "geometry": 0.0, "loss": 0.5915586706664827, "occupancy_iou": 0.25203666733577845}}
+{"step": 1000, "seconds": 39.104, "train_loss": 0.478383868932724, "occupancy": 0.3632516860961914, "position": 0.0865977555513382, "colour": 0.014173795469105244, "scale": 0.00096982711693272, "rotation": 5.3548519645119086e-05, "opacity": 8.451077155768871e-05, "geometry": 0.0, "validation": {"occupancy": 0.42965368785791924, "position": 0.09419222561021647, "colour": 0.03181575125264418, "scale": 0.0019403017205250864, "rotation": 4.755257740119608e-05, "opacity": 0.00015420117577680988, "geometry": 0.0, "loss": 0.5878304019570351, "occupancy_iou": 0.2599639593209657}}
+{"step": 1200, "seconds": 43.034, "train_loss": 0.3406582474708557, "occupancy": 0.18636450171470642, "position": 0.09451016783714294, "colour": 0.02972484566271305, "scale": 0.0024863339494913816, "rotation": 2.946602580777835e-05, "opacity": 8.229353261413053e-05, "geometry": 0.0, "validation": {"occupancy": 0.42523774239752027, "position": 0.09409754392173555, "colour": 0.03096643993986719, "scale": 0.0020236761727978267, "rotation": 4.635460904864885e-05, "opacity": 0.0002172642122205717, "geometry": 0.0, "loss": 0.5816924356751971, "occupancy_iou": 0.25514045654692585}}
+{"step": 1400, "seconds": 46.627, "train_loss": 0.5402199029922485, "occupancy": 0.40528902411460876, "position": 0.09599009901285172, "colour": 0.01943030022084713, "scale": 0.0004655070079024881, "rotation": 1.4336257663671859e-05, "opacity": 3.219417340005748e-05, "geometry": 0.0, "validation": {"occupancy": 0.4270147377418147, "position": 0.09427343706289927, "colour": 0.0308504894980514, "scale": 0.0019938124537778397, "rotation": 3.838655797052424e-05, "opacity": 0.00015617236028649334, "geometry": 0.0, "loss": 0.5833485422862901, "occupancy_iou": 0.2615635176499685}}
+{"step": 1600, "seconds": 50.953, "train_loss": 0.4305267035961151, "occupancy": 0.31603896617889404, "position": 0.08737245947122574, "colour": 0.013378691859543324, "scale": 0.0014701660256832838, "rotation": 1.3187261174607556e-05, "opacity": 0.0002095560048473999, "geometry": 0.0, "validation": {"occupancy": 0.4317949041724205, "position": 0.09412531273232566, "colour": 0.03117768721001792, "scale": 0.0017864460874180723, "rotation": 3.7251114496130966e-05, "opacity": 0.00014699193042259947, "geometry": 0.0, "loss": 0.5886049575275845, "occupancy_iou": 0.25071487617161536}}
+{"step": 1800, "seconds": 54.626, "train_loss": 0.6337854266166687, "occupancy": 0.45424965023994446, "position": 0.09028906375169754, "colour": 0.044515978544950485, "scale": 0.0011866714339703321, "rotation": 4.060083665535785e-05, "opacity": 9.203815716318786e-05, "geometry": 0.0, "validation": {"occupancy": 0.42853521431485814, "position": 0.09408483128580782, "colour": 0.030684983537907506, "scale": 0.0018963307412276562, "rotation": 3.8867297088371643e-05, "opacity": 0.00013767477012152085, "geometry": 0.0, "loss": 0.5843212089604801, "occupancy_iou": 0.26198453576200537}}
+{"step": 2000, "seconds": 58.299, "train_loss": 0.4911178946495056, "occupancy": 0.3473135232925415, "position": 0.09329692274332047, "colour": 0.02516920119524002, "scale": 0.0009039711439982057, "rotation": 1.2793458154192194e-05, "opacity": 7.736129919067025e-05, "geometry": 0.0, "validation": {"occupancy": 0.4308644436299801, "position": 0.09404570534825325, "colour": 0.03126794581443796, "scale": 0.001913158190695362, "rotation": 3.8796406690582645e-05, "opacity": 0.000161123547008578, "geometry": 0.0, "loss": 0.5878023596273528, "occupancy_iou": 0.26729344308583275}}
+{"step": 2200, "seconds": 62.423, "train_loss": 0.49473559856414795, "occupancy": 0.39490997791290283, "position": 0.09424534440040588, "colour": 0.0026967048179358244, "scale": 0.001267485087737441, "rotation": 2.2478219761978835e-05, "opacity": 5.78755461901892e-05, "geometry": -0.0, "validation": {"occupancy": 0.42324845335549777, "position": 0.09407929811212752, "colour": 0.030908581189255022, "scale": 0.001734178906190209, "rotation": 2.9401834669645017e-05, "opacity": 0.00013252917611781515, "geometry": 0.0, "loss": 0.5794538059168391, "occupancy_iou": 0.26256160982367066}}
+{"step": 2400, "seconds": 66.234, "train_loss": 0.5510505437850952, "occupancy": 0.3978094458580017, "position": 0.09358540922403336, "colour": 0.029724668711423874, "scale": 0.001308542676270008, "rotation": 2.4227834728662856e-05, "opacity": 7.308263593586162e-05, "geometry": 0.0, "validation": {"occupancy": 0.4158506722913848, "position": 0.0939772955659363, "colour": 0.03368225522701525, "scale": 0.0016470129029282057, "rotation": 3.0246070622928934e-05, "opacity": 0.0001484720899245278, "geometry": 0.0, "loss": 0.5775086745619774, "occupancy_iou": 0.26686940054512687}}
+{"step": 2600, "seconds": 69.678, "train_loss": 0.5078648924827576, "occupancy": 0.4009518027305603, "position": 0.09459930658340454, "colour": 0.006019631866365671, "scale": 0.00107279303483665, "rotation": 2.1116564312251285e-05, "opacity": 0.00016517315816599876, "geometry": 0.0, "validation": {"occupancy": 0.4215878984166516, "position": 0.0941099154866404, "colour": 0.030351898755503093, "scale": 0.002087128064886201, "rotation": 3.372074203424644e-05, "opacity": 0.0001546000525498433, "geometry": 0.0, "loss": 0.5767682999372482, "occupancy_iou": 0.26642631568635505}}
+{"step": 2800, "seconds": 73.936, "train_loss": 0.5524424314498901, "occupancy": 0.45049646496772766, "position": 0.08658759295940399, "colour": 0.00761753274127841, "scale": 0.0006960614700801671, "rotation": 2.2003196136211045e-05, "opacity": 5.14989260409493e-05, "geometry": 0.0, "validation": {"occupancy": 0.41681441391507784, "position": 0.09399882223871019, "colour": 0.030614230668612033, "scale": 0.0018567735597672355, "rotation": 2.7371126323790427e-05, "opacity": 0.0001512159914960244, "geometry": 0.0, "loss": 0.5723813250660896, "occupancy_iou": 0.2721572133091589}}
+{"step": 3000, "seconds": 77.85, "train_loss": 0.47857388854026794, "occupancy": 0.32654982805252075, "position": 0.0985688716173172, "colour": 0.026567257940769196, "scale": 0.0018755781929939985, "rotation": 1.0815320820256602e-05, "opacity": 0.00013207261508796364, "geometry": 0.0, "validation": {"occupancy": 0.4110039444433318, "position": 0.09397411880393823, "colour": 0.03051911240812236, "scale": 0.0018324703995151342, "rotation": 2.6987933491303314e-05, "opacity": 0.00015093530021456698, "geometry": 0.0, "loss": 0.5663531646132469, "occupancy_iou": 0.26360250164030324}}
+{"step": 3200, "seconds": 82.182, "train_loss": 0.5254156589508057, "occupancy": 0.3551676273345947, "position": 0.09234742075204849, "colour": 0.038872893899679184, "scale": 0.0010524942772462964, "rotation": 1.719896317808889e-05, "opacity": 4.7851517592789605e-05, "geometry": 0.0, "validation": {"occupancy": 0.4228256072435114, "position": 0.09399812126325237, "colour": 0.0307030633609328, "scale": 0.0016338224047406887, "rotation": 2.9768100080218574e-05, "opacity": 0.0001273464747100661, "geometry": 0.0, "loss": 0.5785235651665264, "occupancy_iou": 0.2846426756017738}}
+{"step": 3400, "seconds": 87.183, "train_loss": 0.4364839792251587, "occupancy": 0.3158171772956848, "position": 0.09616897255182266, "colour": 0.012188517488539219, "scale": 0.0007229623151943088, "rotation": 1.076408716471633e-05, "opacity": 4.740383883472532e-05, "geometry": -0.0, "validation": {"occupancy": 0.4094659690227773, "position": 0.09397175216840373, "colour": 0.03179174260003492, "scale": 0.001720584945966645, "rotation": 2.1549060081977384e-05, "opacity": 0.00012737575575051273, "geometry": 0.0, "loss": 0.5673228002256817, "occupancy_iou": 0.2701680043194857}}
+{"step": 3600, "seconds": 91.249, "train_loss": 0.49549779295921326, "occupancy": 0.34523046016693115, "position": 0.08855268359184265, "colour": 0.030767172574996948, "scale": 0.0006670482689514756, "rotation": 2.0991266865166835e-05, "opacity": 0.00011153484228998423, "geometry": 0.0, "validation": {"occupancy": 0.41149804004364543, "position": 0.09396016506685151, "colour": 0.031038793543120845, "scale": 0.0016648945602355525, "rotation": 2.195297413436492e-05, "opacity": 0.00015779983397502898, "geometry": 0.0, "loss": 0.5678622765673531, "occupancy_iou": 0.27745231499688494}}
+{"step": 3800, "seconds": 95.935, "train_loss": 0.45338520407676697, "occupancy": 0.2673555910587311, "position": 0.09842601418495178, "colour": 0.043742645531892776, "scale": 0.0007127065327949822, "rotation": 1.5850951967877336e-05, "opacity": 4.546590207610279e-05, "geometry": 0.0, "validation": {"occupancy": 0.4185141497188144, "position": 0.09392823518978224, "colour": 0.030558659026994266, "scale": 0.0016994932399635825, "rotation": 2.1529511650442144e-05, "opacity": 0.0001690847278748859, "geometry": 0.0, "loss": 0.5739008857972092, "occupancy_iou": 0.28688534133964116}}
+{"step": 4000, "seconds": 99.234, "train_loss": 0.557262122631073, "occupancy": 0.41419923305511475, "position": 0.1001129150390625, "colour": 0.021421322599053383, "scale": 0.0008524729055352509, "rotation": 8.493616405758075e-06, "opacity": 2.1267600459395908e-05, "geometry": 0.0, "validation": {"occupancy": 0.4045540635784467, "position": 0.09390666542781724, "colour": 0.030530943222887193, "scale": 0.0015784881295985542, "rotation": 1.953120323605617e-05, "opacity": 0.00014177847832696797, "geometry": 0.0, "loss": 0.5598241958353255, "occupancy_iou": 0.27434742067837053}}
+{"step": 4200, "seconds": 103.185, "train_loss": 0.6259624361991882, "occupancy": 0.3919915556907654, "position": 0.09183152765035629, "colour": 0.07100241631269455, "scale": 0.0011714748106896877, "rotation": 1.2915494153276086e-05, "opacity": 1.6088246411527507e-05, "geometry": 0.0, "validation": {"occupancy": 0.40893695917394424, "position": 0.09394071011079683, "colour": 0.031102682888417298, "scale": 0.0016566178788909585, "rotation": 2.15832443422591e-05, "opacity": 0.0001230442787598602, "geometry": 0.0, "loss": 0.5653738988770379, "occupancy_iou": 0.2786702503139774}}
+{"step": 4400, "seconds": 107.226, "train_loss": 0.6597180366516113, "occupancy": 0.4113847017288208, "position": 0.09409773349761963, "colour": 0.07705115526914597, "scale": 0.0007961074006743729, "rotation": 1.7088928871089593e-05, "opacity": 5.190773299545981e-05, "geometry": 0.0, "validation": {"occupancy": 0.40834645562701755, "position": 0.09393176059756014, "colour": 0.03059931747460117, "scale": 0.001580410228537706, "rotation": 1.9219402352316846e-05, "opacity": 0.00011282105082904713, "geometry": 0.0, "loss": 0.5637496335638894, "occupancy_iou": 0.28006390310409995}}
+{"step": 4600, "seconds": 111.711, "train_loss": 0.469024121761322, "occupancy": 0.25593164563179016, "position": 0.09084726125001907, "colour": 0.06106134131550789, "scale": 0.0006797174573875964, "rotation": 2.7496407710714266e-05, "opacity": 5.18183151143603e-05, "geometry": -0.0, "validation": {"occupancy": 0.4052144769165251, "position": 0.09393522159920799, "colour": 0.03133135766385951, "scale": 0.0014389909564569178, "rotation": 1.879761312137715e-05, "opacity": 0.00015053203554392288, "geometry": 0.0, "loss": 0.5621087267994881, "occupancy_iou": 0.2752341095565094}}
+{"step": 4800, "seconds": 118.367, "train_loss": 0.4867999255657196, "occupancy": 0.3837716579437256, "position": 0.09228860586881638, "colour": 0.005275615490972996, "scale": 0.0010446624364703894, "rotation": 2.072399547614623e-05, "opacity": 8.185891783796251e-05, "geometry": 0.0, "validation": {"occupancy": 0.4076536825133695, "position": 0.09397915200226836, "colour": 0.030453578963836967, "scale": 0.0015870701287187532, "rotation": 1.7866719237089355e-05, "opacity": 0.00014790454023467546, "geometry": 0.0, "loss": 0.5628483845955796, "occupancy_iou": 0.2745954434387386}}
+{"step": 5000, "seconds": 126.698, "train_loss": 0.5417315363883972, "occupancy": 0.3388543426990509, "position": 0.0951608270406723, "colour": 0.053798988461494446, "scale": 0.0008181341690942645, "rotation": 1.32617697090609e-05, "opacity": 3.5288030630908906e-05, "geometry": 0.0, "validation": {"occupancy": 0.40258289178212486, "position": 0.09389113494091564, "colour": 0.030977234217183045, "scale": 0.0015717818333844966, "rotation": 1.7154699538776994e-05, "opacity": 0.00012996606800596864, "geometry": 0.0, "loss": 0.5587173554632399, "occupancy_iou": 0.278588663517601}}
+{"step": 5200, "seconds": 136.791, "train_loss": 0.4986310303211212, "occupancy": 0.39215320348739624, "position": 0.09362593293190002, "colour": 0.0063873776234686375, "scale": 0.0005547901382669806, "rotation": 1.3301656508701853e-05, "opacity": 2.0309231331339106e-05, "geometry": 0.0, "validation": {"occupancy": 0.40034629594948556, "position": 0.0939166457288795, "colour": 0.0316381377083922, "scale": 0.0013407457458217524, "rotation": 1.5355411326507036e-05, "opacity": 9.307003478069318e-05, "geometry": 0.0, "loss": 0.5577678953607877, "occupancy_iou": 0.28428437142736385}}
+{"step": 5400, "seconds": 147.671, "train_loss": 0.5063523054122925, "occupancy": 0.37988996505737305, "position": 0.09676655381917953, "colour": 0.014790681190788746, "scale": 0.000719499948900193, "rotation": 1.0230924090137705e-05, "opacity": 4.14770474890247e-05, "geometry": 0.0, "validation": {"occupancy": 0.406855690644847, "position": 0.094014210999012, "colour": 0.030220710265954645, "scale": 0.0014052534357890383, "rotation": 1.3710945721514792e-05, "opacity": 0.00012029510183108667, "geometry": 0.0, "loss": 0.5615735145906607, "occupancy_iou": 0.2955626644194126}}
+{"step": 5600, "seconds": 158.543, "train_loss": 0.4793046712875366, "occupancy": 0.31926438212394714, "position": 0.09948806464672089, "colour": 0.030066760256886482, "scale": 0.0016735820099711418, "rotation": 3.527296030370053e-06, "opacity": 0.00025098398327827454, "geometry": 0.0, "validation": {"occupancy": 0.4096036763654815, "position": 0.0940052620238728, "colour": 0.030777640448003594, "scale": 0.0017037645920128044, "rotation": 1.2175207258577655e-05, "opacity": 9.953662891146249e-05, "geometry": 0.0, "loss": 0.5654353524247805, "occupancy_iou": 0.29424606011145643}}
+{"step": 5800, "seconds": 169.06, "train_loss": 0.5487256646156311, "occupancy": 0.4067179262638092, "position": 0.08838052302598953, "colour": 0.026750687509775162, "scale": 0.0008282989729195833, "rotation": 6.190408385009505e-06, "opacity": 4.235693268128671e-05, "geometry": 0.0, "validation": {"occupancy": 0.4043719614545504, "position": 0.0938253727224138, "colour": 0.03032789862126164, "scale": 0.0014254298906760394, "rotation": 1.2701534732665701e-05, "opacity": 0.0001225527391397918, "geometry": 0.0, "loss": 0.5591194975707267, "occupancy_iou": 0.28225652354045044}}
+{"step": 6000, "seconds": 178.463, "train_loss": 0.7709605693817139, "occupancy": 0.6320652365684509, "position": 0.10362475365400314, "colour": 0.017524851486086845, "scale": 0.0013552490854635835, "rotation": 1.1179777175129857e-05, "opacity": 8.425069972872734e-05, "geometry": -0.0, "validation": {"occupancy": 0.40365004216631256, "position": 0.09382433742284775, "colour": 0.030227608712933337, "scale": 0.0013439785144227143, "rotation": 1.3150008344887789e-05, "opacity": 0.00011520726076115453, "geometry": 0.0, "loss": 0.5581805180344317, "occupancy_iou": 0.289635895875593}}
+{"step": 6200, "seconds": 188.743, "train_loss": 0.4993472695350647, "occupancy": 0.3844979405403137, "position": 0.0935329720377922, "colour": 0.010608968324959278, "scale": 0.0006603781948797405, "rotation": 5.173298632143997e-06, "opacity": 3.185215246048756e-05, "geometry": 0.0, "validation": {"occupancy": 0.39319998257690003, "position": 0.093823934180869, "colour": 0.03010780170184767, "scale": 0.0013350714630279172, "rotation": 1.0495416969054835e-05, "opacity": 8.886457434932203e-05, "geometry": 0.0, "loss": 0.5474629404644171, "occupancy_iou": 0.28641757027556497}}
+{"step": 6400, "seconds": 198.688, "train_loss": 0.4189801514148712, "occupancy": 0.2826651334762573, "position": 0.09773959964513779, "colour": 0.019192663952708244, "scale": 0.0007928699487820268, "rotation": 7.733145139354747e-06, "opacity": 0.00011002655810443684, "geometry": -0.0, "validation": {"occupancy": 0.4008911026020845, "position": 0.09377840674585766, "colour": 0.030930962648967074, "scale": 0.0013093957671016041, "rotation": 1.0876036795555894e-05, "opacity": 9.485433270128851e-05, "geometry": 0.0, "loss": 0.5567583110597398, "occupancy_iou": 0.2885369167766637}}
+{"step": 6600, "seconds": 207.607, "train_loss": 0.5430406928062439, "occupancy": 0.40279972553253174, "position": 0.0946291834115982, "colour": 0.02274857833981514, "scale": 0.00046750501496717334, "rotation": 3.858339823636925e-06, "opacity": 6.750710599590093e-05, "geometry": 0.0, "validation": {"occupancy": 0.3953916298846404, "position": 0.09387033122281234, "colour": 0.029838704274799156, "scale": 0.001385571199514541, "rotation": 1.1168679466461779e-05, "opacity": 0.00012542731134696322, "geometry": 0.0, "loss": 0.549204474604792, "occupancy_iou": 0.29114852864295243}}
+{"step": 6800, "seconds": 217.242, "train_loss": 0.42363783717155457, "occupancy": 0.3095293641090393, "position": 0.07285671681165695, "colour": 0.020542502403259277, "scale": 0.0011710914550349116, "rotation": 6.151235993456794e-06, "opacity": 4.898784391116351e-05, "geometry": 0.0, "validation": {"occupancy": 0.3905657473537657, "position": 0.09377354122698307, "colour": 0.030009023019293736, "scale": 0.0013380147245091697, "rotation": 9.336464271806714e-06, "opacity": 9.46656024098047e-05, "geometry": 0.0, "loss": 0.5445867335630787, "occupancy_iou": 0.28344639133041105}}
+{"step": 7000, "seconds": 226.267, "train_loss": 0.3683210015296936, "occupancy": 0.2541470527648926, "position": 0.0920795351266861, "colour": 0.011000635102391243, "scale": 0.00044253666419535875, "rotation": 8.873310434864834e-06, "opacity": 4.801345494342968e-05, "geometry": -0.0, "validation": {"occupancy": 0.38817514338427117, "position": 0.09379746023979452, "colour": 0.030292692528908243, "scale": 0.0013068688216864958, "rotation": 9.695720117027425e-06, "opacity": 0.00010475461714476195, "geometry": 0.0, "loss": 0.5427944011158413, "occupancy_iou": 0.28759642725603446}}
+{"step": 7200, "seconds": 236.128, "train_loss": 0.5596817135810852, "occupancy": 0.4352259635925293, "position": 0.09255465120077133, "colour": 0.015911228954792023, "scale": 0.0004941098159179091, "rotation": 5.525091637537116e-06, "opacity": 2.8721509806928225e-05, "geometry": 0.0, "validation": {"occupancy": 0.3937354901184638, "position": 0.09382040939397282, "colour": 0.029826522268639463, "scale": 0.0012667472010232611, "rotation": 9.296284631293223e-06, "opacity": 0.00012043797467716406, "geometry": 0.0, "loss": 0.5474569886922837, "occupancy_iou": 0.2878855074652367}}
+{"step": 7400, "seconds": 245.65, "train_loss": 0.4626730978488922, "occupancy": 0.3224141299724579, "position": 0.09337978810071945, "colour": 0.02338295243680477, "scale": 0.0007951300358399749, "rotation": 3.5533946629584534e-06, "opacity": 3.340890907566063e-05, "geometry": 0.0, "validation": {"occupancy": 0.3877126969397068, "position": 0.0938801984820101, "colour": 0.030403074356986002, "scale": 0.00118190329085337, "rotation": 7.93976443813133e-06, "opacity": 9.667932798341402e-05, "geometry": 0.0, "loss": 0.5426147082613574, "occupancy_iou": 0.2788545132097271}}
+{"step": 7600, "seconds": 255.315, "train_loss": 0.3988212049007416, "occupancy": 0.27856338024139404, "position": 0.0932641476392746, "colour": 0.013418144546449184, "scale": 0.0009028896456584334, "rotation": 3.5423447570792632e-06, "opacity": 6.672731979051605e-05, "geometry": 0.0, "validation": {"occupancy": 0.3907282780028052, "position": 0.09378029331564904, "colour": 0.03218639403607489, "scale": 0.0011547023844387797, "rotation": 8.038774109309087e-06, "opacity": 9.087624960102403e-05, "geometry": 0.0, "loss": 0.5490885093808174, "occupancy_iou": 0.29333951137959957}}
+{"step": 7800, "seconds": 264.733, "train_loss": 0.43082183599472046, "occupancy": 0.3145463764667511, "position": 0.0849197506904602, "colour": 0.015606578439474106, "scale": 0.0010680370032787323, "rotation": 3.66301378562639e-06, "opacity": 3.537732845870778e-05, "geometry": -0.0, "validation": {"occupancy": 0.3866305548283789, "position": 0.09380314374963443, "colour": 0.02985135869692183, "scale": 0.0011766884298089685, "rotation": 7.77004361667524e-06, "opacity": 0.00013522217013309677, "geometry": 0.0, "loss": 0.5403900866707166, "occupancy_iou": 0.2947235658764839}}
+{"step": 8000, "seconds": 274.229, "train_loss": 0.4784364402294159, "occupancy": 0.35019439458847046, "position": 0.09252085536718369, "colour": 0.01773099973797798, "scale": 0.0023379335179924965, "rotation": 4.9215291255677585e-06, "opacity": 2.4880051569198258e-05, "geometry": -0.0, "validation": {"occupancy": 0.3940945436557134, "position": 0.09373144254916244, "colour": 0.031111064605000946, "scale": 0.0012088158114541632, "rotation": 7.342030562540458e-06, "opacity": 9.256118964913184e-05, "geometry": 0.0, "loss": 0.5502622892459234, "occupancy_iou": 0.2887043085984058}}

model.pt

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

posttrain.sh

@@ -0,0 +1,56 @@
+#!/bin/bash
+# Source and weights are pinned; no training or upload starts during setup.
+set -euo pipefail
+cd "$(dirname "$0")"
+STAGE="${1:-help}"
+RUNTIME="${FORMA3D_V2_RUNTIME:-$HOME/Library/Application Support/Forma3D-tiny-2/venv}"
+PY="$RUNTIME/bin/python"
+export HF_HUB_DISABLE_TELEMETRY=1
+export OMP_NUM_THREADS=4
+export VECLIB_MAXIMUM_THREADS=4
+REV=e80b8d895cc2e405894473abe4ce40b3472eaca7
+case "$STAGE" in
+  setup)
+    if ! command -v uv >/dev/null; then
+      echo 'Install uv first: brew install uv'; exit 1
+    fi
+    [ -x "$PY" ] || uv venv --python 3.11 "$RUNTIME"
+    uv pip install --python "$PY" 'huggingface_hub[cli]>=0.34'
+    "$RUNTIME/bin/hf" download Lucasgitguy-co/forma3d-tiny --revision "$REV" --local-dir upstream
+    uv pip install --python "$PY" -r upstream/requirements-tested-macos.txt
+    uv pip install --python "$PY" './upstream[data]'
+    "$PY" -m image3d_student.cli doctor
+    "$PY" -c 'import torch; assert torch.backends.mps.is_available(), "Metal unavailable; run in macOS Terminal"'
+    mkdir -p runs
+    uv pip freeze --python "$PY" > runs/environment.txt
+    ;;
+  prepare)
+    [ -x "$PY" ] || { echo 'Run bash posttrain.sh setup first'; exit 1; }
+    "$PY" prepare_v2.py --out data/forma3d-v2 --cache data/downloads \
+      --scenario 128 --objaverse 128 --objaverse-shards 16 --resume \
+      --grid 16 --views 4 --surface-points 4096 --seed 43 \
+      --max-file-mb 16 --max-download-mb 4096 --reserve-gb 8
+    ;;
+  train)
+    [ -x "$PY" ] || { echo 'Run bash posttrain.sh setup first'; exit 1; }
+    "$PY" audit_data.py data/forma3d-v2 upstream/ATTRIBUTIONS.json
+    # A fresh output directory is required. Ctrl-C saves last.pt, not optimizer resume.
+    caffeinate -i "$PY" -m image3d_student.cli train \
+      --manifest data/forma3d-v2/manifest.jsonl --init-from upstream/model.pt \
+      --out runs/forma3d-v2 --device mps --width 64 \
+      --steps 8000 --batch-size 2 --lr 0.00005 \
+      --eval-every 200 --validation-fraction 0.2 --seed 43
+    ;;
+  evaluate)
+    "$PY" stage_v2.py --run runs/forma3d-v2 --data data/forma3d-v2 \
+      --base upstream/model.pt --release release/forma3d-tiny-2 --device mps
+    ;;
+  publish)
+    # Explicit command only. Creates a private repo; makes it public after upload.
+    "$PY" publish_v2.py release/forma3d-tiny-2
+    ;;
+  *)
+    echo 'Run stages in order: setup, prepare, train, evaluate, publish (optional).'
+    echo 'Example: bash posttrain.sh setup'
+    ;;
+esac

preparation.json

@@ -0,0 +1,36 @@
+{
+  "counts": {
+    "scenario-labs/3d-collection": {
+      "requested": 128,
+      "prepared": 128
+    },
+    "allenai/objaverse": {
+      "requested": 128,
+      "prepared": 128
+    }
+  },
+  "samples": 1024,
+  "objects": 256,
+  "distinct_groups": 239,
+  "settings": {
+    "scenario": 128,
+    "objaverse": 128,
+    "objaverse_shards": 16,
+    "resume": true,
+    "grid": 16,
+    "views": 4,
+    "surface_points": 4096,
+    "seed": 43,
+    "max_file_mb": 16,
+    "max_download_mb": 4096,
+    "reserve_gb": 8.0
+  },
+  "rendered_proxy_data": true,
+  "excluded": [
+    "scenario-labs/3d-collection-hunyuan",
+    "3dlg-hcvc/MultiScan",
+    "huanngzh/3D-Front",
+    "facebook/show3d-dataset",
+    "Voxel51/gaussian_splatting"
+  ]
+}

prepare_v2.py

@@ -0,0 +1,42 @@
+"""Use pinned upstream preprocessing while excluding every known v1 asset/group."""
+import importlib.util
+import json
+from pathlib import Path
+from audit_data import audit, identity_sets, conflicts
+
+ROOT = Path(__file__).resolve().parent
+
+def main():
+    upstream = ROOT / 'upstream'
+    old = json.loads((upstream / 'ATTRIBUTIONS.json').read_text())
+    blocked = identity_sets(old)
+    spec = importlib.util.spec_from_file_location('pinned_prepare', upstream / 'scripts/prepare_hf.py')
+    module = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(module)
+    for name in ('scenario_candidates', 'objaverse_candidates'):
+        original = getattr(module, name)
+        def filtered(*args, _original=original, **kwargs):
+            return [r for r in _original(*args, **kwargs) if not conflicts(r, blocked)]
+        setattr(module, name, filtered)
+    downloader = module.Downloader
+    class FilteredDownloader(downloader):
+        def get(self, *args, **kwargs):
+            path = super().get(*args, **kwargs)
+            if module.digest(path) in blocked['sha256']:
+                raise ValueError('Excluded byte-identical v1 mesh')
+            return path
+    module.Downloader = FilteredDownloader
+    original_prepare = module.prepare
+    def checked_prepare(args):
+        out = Path(args.out)
+        if (out / 'sources.json').exists():
+            for row in json.loads((out / 'sources.json').read_text()):
+                if conflicts(row, blocked):
+                    raise ValueError('Existing dataset overlaps v1; choose a fresh --out directory')
+        original_prepare(args)
+        audit(out, upstream / 'ATTRIBUTIONS.json')
+    module.prepare = checked_prepare
+    module.main()
+
+if __name__ == '__main__':
+    main()

publish_v2.py

@@ -0,0 +1,35 @@
+"""Explicit optional upload; creates a private repository before making it public."""
+import hashlib
+import json
+import sys
+from pathlib import Path
+from huggingface_hub import HfApi
+
+def main():
+    root = Path(sys.argv[1])
+    report = json.loads((root/'evaluation.json').read_text())
+    if not report.get('passed') or not all(report['checks'].values()):
+        raise ValueError('Evaluation gate failed')
+    lines = (root/'SHA256SUMS').read_text().splitlines()
+    expected = {}
+    for line in lines:
+        digest, filename = line.split('  ',1)
+        path = (root/filename).resolve()
+        if not path.is_relative_to(root.resolve()):
+            raise ValueError('Invalid checksum path')
+        expected[filename] = digest
+        if hashlib.sha256(path.read_bytes()).hexdigest() != digest:
+            raise ValueError('Changed release file: '+filename)
+    actual = {str(p.relative_to(root)) for p in root.rglob('*') if p.is_file() and p.name != 'SHA256SUMS'}
+    if actual != set(expected):
+        raise ValueError('Unlisted or missing release files')
+    repo = 'Lucasgitguy-co/forma3d-tiny-2'
+    api = HfApi()
+    api.create_repo(repo,repo_type='model',private=True,exist_ok=False)
+    api.upload_folder(repo_id=repo,repo_type='model',folder_path=str(root),
+                      commit_message='Release evaluated Forma3D Tiny 2 continuation')
+    api.update_repo_settings(repo_id=repo,repo_type='model',private=False)
+    print('Published https://huggingface.co/'+repo)
+
+if __name__ == '__main__':
+    main()

pyproject.toml

@@ -0,0 +1,28 @@
+[build-system]
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "forma3d-tiny-2"
+version = "0.3.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"]

requirements-tested-macos.txt

@@ -0,0 +1,32 @@
+anyio==4.16.0
+click==8.5.0
+filelock==4.2.7
+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
+iniconfig==2.3.1
+jinja2==3.1.6
+markupsafe==3.0.4
+mpmath==1.3.0
+networkx==3.6.1
+numpy==2.4.6
+packaging==26.3
+pillow==13.0.0
+pluggy==1.7.0
+plyfile==1.1.5
+pyarrow==26.0.0
+pygments==2.21.0
+pytest==9.2.0
+pyyaml==6.0.3
+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

scripts/prepare_hf.py

@@ -0,0 +1,463 @@
+"""Prepare paired, canonical rendered images and coarse Gaussian targets.
+
+These are mesh-derived proxy targets, NOT pretrained-teacher outputs or photos.
+Only public, explicitly allowed assets are downloaded. Source meshes stay local.
+"""
+import argparse
+import gzip
+import hashlib
+import json
+import random
+import shutil
+import time
+import urllib.error
+import urllib.request
+from pathlib import Path, PurePosixPath
+
+import numpy as np
+import pyarrow.parquet as pq
+import trimesh
+from huggingface_hub import hf_hub_download
+
+from image3d_student.data import cache_sample, splat_targets
+from image3d_student.splats import Splats, preview
+from image3d_student.engine import split_rows
+
+SCENARIO = ("scenario-labs/3d-collection", "55b4c002b4c1529fc48da3dff98516c3069bfa3f")
+OBJAVERSE = ("allenai/objaverse", "556637099bf4fa79ea7b239d0d9c328b8a2e9ac8")
+
+
+def digest(path):
+    h = hashlib.sha256()
+    with Path(path).open("rb") as f:
+        for block in iter(lambda: f.read(1024 * 1024), b""):
+            h.update(block)
+    return h.hexdigest()
+
+
+class Downloader:
+    def __init__(self, root, max_file_mb, max_total_mb, reserve_gb):
+        self.root = Path(root)
+        self.root.mkdir(parents=True, exist_ok=True)
+        self.max_file = int(max_file_mb * 1024**2)
+        self.max_total = int(max_total_mb * 1024**2)
+        self.reserve = int(reserve_gb * 1024**3)
+        self.total = 0
+
+    def get(self, repo, revision, filename, expected=None):
+        parts = PurePosixPath(filename)
+        if parts.is_absolute() or ".." in parts.parts or not filename.endswith(".glb"):
+            raise ValueError("Only relative GLB paths are allowed")
+        out = self.root / repo.replace("/", "--") / revision / filename
+        if out.exists():
+            if expected and digest(out) != expected:
+                raise ValueError("Cached source checksum mismatch")
+            if out.stat().st_size > self.max_file:
+                raise ValueError("Cached asset exceeds per-file limit")
+            return out
+        if self.total >= self.max_total:
+            raise RuntimeError("Download budget exhausted")
+        out.parent.mkdir(parents=True, exist_ok=True)
+        url = f"https://huggingface.co/datasets/{repo}/resolve/{revision}/{filename}"
+        for attempt in range(4):
+            tmp = out.with_suffix(".part")
+            try:
+                # Public URL only: credentials are never forwarded to asset hosts.
+                with urllib.request.urlopen(url, timeout=60) as response, tmp.open("wb") as f:
+                    length = int(response.headers.get("Content-Length", 0))
+                    if length > self.max_file:
+                        raise ValueError("Asset exceeds per-file limit")
+                    count = 0
+                    while block := response.read(1024 * 1024):
+                        count += len(block)
+                        self.total += len(block)
+                        if count > self.max_file:
+                            raise ValueError("Asset exceeds per-file limit")
+                        if self.total > self.max_total:
+                            raise RuntimeError("Download budget exhausted")
+                        if shutil.disk_usage(self.root).free < self.reserve + len(block):
+                            raise RuntimeError("Free disk space below reserve")
+                        f.write(block)
+                if expected and digest(tmp) != expected:
+                    raise ValueError("Source checksum mismatch")
+                tmp.replace(out)
+                return out
+            except urllib.error.HTTPError as exc:
+                if exc.code not in (429, 500, 502, 503, 504) or attempt == 3:
+                    raise
+                time.sleep(min(2**attempt, 8))
+            finally:
+                tmp.unlink(missing_ok=True)
+        raise RuntimeError("Download retries exhausted")
+
+
+def scenario_candidates(cache, seed):
+    repo, revision = SCENARIO
+    path = hf_hub_download(repo, "data/train-00000-of-00001.parquet", repo_type="dataset",
+                           revision=revision, local_dir=Path(cache) / "metadata/scenario")
+    rows = pq.read_table(path, columns=["id", "license", "model", "inputs", "outputs"]).to_pylist()
+    # Connected components keep alternate meshes generated from shared inputs together.
+    parent = {}
+
+    def find(x):
+        parent.setdefault(x, x)
+        if parent[x] != x:
+            parent[x] = find(parent[x])
+        return parent[x]
+
+    candidates = []
+    for row in rows:
+        if row["license"] != "cc-by-4.0" or "hunyuan" in (row["model"] or "").lower():
+            continue
+        assets = (row.get("inputs") or {}).get("assets") or []
+        keys = ["input:" + (a.get("sha256") or a["path"]) for a in assets if a.get("sha256") or a.get("path")]
+        keys += ["output:" + o["sha256"] for o in row["outputs"] if o.get("sha256")]
+        keys += [row["id"]]
+        for key in keys[1:]:
+            parent[find(key)] = find(keys[0])
+        for output in row["outputs"]:
+            if output.get("format") == "glb":
+                candidates.append({"repo": repo, "revision": revision, "path": output["path"],
+                    "sha256": output.get("sha256"), "asset_id": row["id"], "license": "cc-by-4.0",
+                    "author": "Scenario", "title": row["id"], "source_model": row["model"],
+                    "source_url": f"https://huggingface.co/datasets/{repo}", "group_key": keys[0]})
+                break
+    for row in candidates:
+        row["object_id"] = "scenario-" + hashlib.sha256(find(row.pop("group_key")).encode()).hexdigest()[:20]
+    candidates.sort(key=lambda r: r["asset_id"])
+    random.Random(seed).shuffle(candidates)
+    return candidates
+
+
+def objaverse_candidates(cache, seed, shards):
+    repo, revision = OBJAVERSE
+    candidates = []
+    for shard in range(shards):
+        part = f"000-{shard:03d}"
+        path = hf_hub_download(repo, f"metadata/{part}.json.gz", repo_type="dataset", revision=revision,
+                               local_dir=Path(cache) / "metadata/objaverse")
+        with gzip.open(path) as f:
+            records = json.load(f)
+        for uid, row in records.items():
+            # Start with the more conservative CC0 subset; no NC/SA/unknown assets.
+            if row.get("license") != "cc0" or row.get("isAgeRestricted") or row.get("animationCount", 0):
+                continue
+            candidates.append({"repo": repo, "revision": revision, "path": f"glbs/{part}/{uid}.glb",
+                "asset_id": uid, "object_id": "objaverse-" + uid, "license": "cc0-1.0",
+                "author": row.get("user", {}).get("displayName", "Unknown"), "title": row.get("name", uid),
+                "source_url": row.get("viewerUrl", f"https://sketchfab.com/3d-models/{uid}")})
+    candidates.sort(key=lambda r: r["asset_id"])
+    random.Random(seed).shuffle(candidates)
+    return candidates
+
+
+def mesh_splats(path, count, grid, seed):
+    scene = trimesh.load_scene(path, process=False)
+    meshes = []
+    for node in scene.graph.nodes_geometry:
+        matrix, name = scene.graph[node]
+        mesh = scene.geometry[name].copy()
+        if not isinstance(mesh, trimesh.Trimesh) or not len(mesh.faces):
+            continue
+        mesh.apply_transform(matrix)
+        meshes.append(mesh)
+    if not meshes or sum(len(m.faces) for m in meshes) > 500_000:
+        raise ValueError("Missing mesh or more than 500,000 triangles")
+    bounds = np.array([m.bounds for m in meshes])
+    low, high = bounds[:, 0].min(axis=0), bounds[:, 1].max(axis=0)
+    extent = float((high - low).max())
+    if not np.isfinite(bounds).all() or extent < 1e-8:
+        raise ValueError("Degenerate mesh")
+    center = (low + high) / 2
+    factor = .9 / extent
+    areas = np.array([m.area for m in meshes])
+    if not np.isfinite(areas).all() or areas.sum() <= 0:
+        raise ValueError("Invalid surface area")
+    counts = np.random.default_rng(seed).multinomial(count, areas / areas.sum())
+    points, colours = [], []
+    for mesh, n in zip(meshes, counts):
+        if not n:
+            continue
+        xyz, faces = trimesh.sample.sample_surface(mesh, int(n), seed=seed)
+        bary = trimesh.triangles.points_to_barycentric(mesh.triangles[faces], xyz)
+        vis = mesh.visual
+        if vis.kind == "texture" and vis.uv is not None:
+            uv = (vis.uv[mesh.faces[faces]] * bary[:, :, None]).sum(axis=1)
+            sampled = np.asarray(vis.material.to_color(uv))
+            if sampled.ndim == 0:
+                raise ValueError("Material has no usable texture or base colour")
+            # Untextured PBR materials can return one constant RGBA value.
+            if sampled.ndim == 1:
+                sampled = np.broadcast_to(sampled, (n, len(sampled)))
+            colour = sampled[:, :3] / 255.
+        elif vis.kind == "vertex":
+            colour = (vis.vertex_colors[mesh.faces[faces], :3] * bary[:, :, None]).sum(axis=1) / 255.
+        elif vis.kind == "face":
+            colour = vis.face_colors[faces, :3] / 255.
+        else:
+            colour = np.full((n, 3), .65)
+        points.append((xyz - center) * factor)
+        colours.append(colour)
+    xyz = np.concatenate(points).astype(np.float32)
+    rgb = np.concatenate(colours).astype(np.float32)
+    n = len(xyz)
+    splats = Splats(xyz, rgb, np.full((n, 3), .6 / grid),
+                    np.tile([1, 0, 0, 0], (n, 1)), np.full((n, 1), .9))
+    transform = np.eye(4)
+    transform[:3, :3] *= factor
+    transform[:3, 3] = -center * factor
+    return splats, transform.tolist()
+
+
+def save_progress(out, args, rows, provenance, failures):
+    state = {"version": 1, "settings": vars(args), "rows": rows,
+             "sources": provenance, "skipped": failures}
+    temporary = out / "progress.json.tmp"
+    temporary.write_text(json.dumps(state))
+    temporary.replace(out / "progress.json")
+
+
+def check_resume_settings(previous, args):
+    for key in ("grid", "views", "surface_points", "seed", "scenario", "objaverse"):
+        if previous[key] != getattr(args, key):
+            raise ValueError(f"Cannot change {key} while resuming; use a new dataset directory")
+
+
+def recover_legacy(out, args):
+    """Recover the old writer's completed files without rendering or downloading.
+
+    Old runs saved sources and arrays, but lost manifest rows on insufficient
+    candidates. Recreate those rows and verify targets against cached GLBs.
+    """
+    previous = json.loads((out / "preparation.json").read_text())["settings"]
+    check_resume_settings(previous, args)
+    provenance = json.loads((out / "sources.json").read_text())
+    failures = json.loads((out / "skipped.json").read_text())
+    rows = []
+    for index, item in enumerate(provenance):
+        path = Path(args.cache) / item["repo"].replace("/", "--") / item["revision"] / item["path"]
+        if not path.is_file() or digest(path) != item["sha256"]:
+            raise ValueError(f"Missing or corrupt cached source for {item['asset_id']}")
+        splats, transform = mesh_splats(path, args.surface_points, args.grid,
+                                        int(item["sha256"][:8], 16) ^ args.seed)
+        stem = hashlib.sha256((item["repo"] + item["asset_id"]).encode()).hexdigest()[:20]
+        for view in range(args.views):
+            sample_id = f"{stem}-v{view}"
+            image, target = f"images/{sample_id}.png", f"targets/{sample_id}.npz"
+            yaw = 2 * np.pi * view / args.views
+            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)
+            expected = splat_targets(rotated, args.grid)
+            with np.load(out / target, allow_pickle=False) as cached:
+                if set(cached.files) != set(expected):
+                    raise ValueError(f"Target fields differ for {sample_id}")
+                for key, value in expected.items():
+                    if not np.array_equal(cached[key], value):
+                        raise ValueError(f"Recovered target differs for {sample_id}: {key}")
+            from PIL import Image
+            with Image.open(out / image) as check:
+                check.verify()
+            rows.append({"id": sample_id, "image": image, "target": target,
+                "source": "mesh-proxy:" + item["repo"], "grid": args.grid,
+                "teachers": {"appearance": "mesh-proxy:" + item["repo"], "coarse": None, "fine": None},
+                "teacher_gaussians": len(splats.xyz), "retained_gaussians": int(expected["occ"].sum()),
+                "geometry_transforms": {"coarse": None, "fine": None},
+                "image_sha256": digest(out / image), "target_sha256": digest(out / target),
+                "metadata": {**item, "normalization_matrix": transform, "yaw_radians": float(yaw),
+                    "render": "orthographic Gaussian proxy, camera +z",
+                    "target": "isotropic surface-sampled mesh proxy; not a pretrained teacher"}})
+        if (index + 1) % 10 == 0 or index + 1 == len(provenance):
+            print(json.dumps({"recovered_objects": index + 1, "existing_objects": len(provenance)}), flush=True)
+    save_progress(out, args, rows, provenance, failures)
+    return rows, provenance, failures
+
+
+def load_progress(out, args):
+    if not (out / "progress.json").exists():
+        return recover_legacy(out, args)
+    state = json.loads((out / "progress.json").read_text())
+    if state.get("version") != 1:
+        raise ValueError("Unsupported preparation progress version")
+    check_resume_settings(state["settings"], args)
+    for row in state["rows"]:
+        for key in ("image", "target"):
+            path = (out / row[key]).resolve()
+            if not path.is_relative_to(out.resolve()) or digest(path) != row[key + "_sha256"]:
+                raise ValueError(f"Prepared file checksum mismatch: {row['id']} {key}")
+    return state["rows"], state["sources"], state["skipped"]
+
+
+def prune_invisible(out, rows, provenance, failures):
+    from PIL import Image
+    bad = set()
+    for row in rows:
+        with Image.open(out / row["image"]) as image:
+            if image.convert("RGB").getbbox() is None:
+                bad.add((row["metadata"]["repo"], row["metadata"]["asset_id"]))
+    for repo, asset in sorted(bad):
+        failures.append({"repo": repo, "asset": asset,
+                         "error": "Rendered view has no visible pixels", "terminal": True})
+    if bad:
+        print(json.dumps({"excluded_invisible_objects": len(bad), "existing_files_preserved": True}), flush=True)
+    return ([r for r in rows if (r["metadata"]["repo"], r["metadata"]["asset_id"]) not in bad],
+            [p for p in provenance if (p["repo"], p["asset_id"]) not in bad])
+
+
+def group_duplicates(rows, provenance):
+    """Link entire objects when any views or target files are byte-identical."""
+    parent = {}
+    def find(x):
+        parent.setdefault(x, x)
+        if parent[x] != x:
+            parent[x] = find(parent[x])
+        return parent[x]
+    hashes = {}
+    for row in rows:
+        meta = row["metadata"]
+        original = meta.setdefault("source_object_id", meta["object_id"])
+        find(original)
+        for field in ("image_sha256", "target_sha256"):
+            key = (field, row[field])
+            if key in hashes:
+                a, b = find(original), find(hashes[key])
+                parent[max(a, b)] = min(a, b)
+            else:
+                hashes[key] = original
+    for row in rows:
+        row["metadata"]["object_id"] = find(row["metadata"]["source_object_id"])
+    for item in provenance:
+        original = item.setdefault("source_object_id", item["object_id"])
+        item["object_id"] = find(original)
+
+
+def prepare(args):
+    out = Path(args.out)
+    occupied = out.exists() and any(out.iterdir())
+    if occupied and not getattr(args, "resume", False):
+        raise ValueError("Output is not empty. Use --resume to retain completed objects.")
+    if args.scenario + args.objaverse < 4:
+        raise ValueError("Request at least four objects")
+    out.mkdir(parents=True, exist_ok=True)
+    if occupied:
+        all_rows, provenance, failures = load_progress(out, args)
+    else:
+        all_rows, provenance, failures = [], [], []
+        save_progress(out, args, all_rows, provenance, failures)
+    all_rows, provenance = prune_invisible(out, all_rows, provenance, failures)
+    save_progress(out, args, all_rows, provenance, failures)
+    seen = {item["sha256"] for item in provenance}
+    completed = {(item["repo"], item["asset_id"]) for item in provenance}
+    rejected = {(f["repo"], f["asset"]) for f in failures if f.get("terminal")}
+    counts = {}
+    fetch = Downloader(args.cache, args.max_file_mb, args.max_download_mb, args.reserve_gb)
+    sources = []
+    if args.scenario:
+        ready = sum(item["repo"] == SCENARIO[0] for item in provenance)
+        candidates = scenario_candidates(args.cache, args.seed) if ready < args.scenario else []
+        sources.append((SCENARIO[0], candidates, args.scenario, ready))
+    if args.objaverse:
+        ready = sum(item["repo"] == OBJAVERSE[0] for item in provenance)
+        candidates = objaverse_candidates(args.cache, args.seed, args.objaverse_shards) if ready < args.objaverse else []
+        sources.append((OBJAVERSE[0], candidates, args.objaverse, ready))
+    for repo, candidates, wanted, accepted in sources:
+        for item in candidates:
+            if accepted >= wanted:
+                break
+            if (item["repo"], item["asset_id"]) in completed | rejected:
+                continue
+            staging = out / "_staging"
+            try:
+                path = fetch.get(item["repo"], item["revision"], item["path"], item.get("sha256"))
+                checksum = digest(path)
+                if checksum in seen:
+                    continue
+                item["sha256"] = checksum
+                item_seed = int(checksum[:8], 16) ^ args.seed
+                splats, transform = mesh_splats(path, args.surface_points, args.grid, item_seed)
+                stem = hashlib.sha256((item["repo"] + item["asset_id"]).encode()).hexdigest()[:20]
+                staging.mkdir(parents=True, exist_ok=True)
+                rows = []
+                for view in range(args.views):
+                    yaw = 2 * np.pi * view / args.views
+                    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)
+                    image = staging / "input.png"
+                    rendered = preview(rotated, size=128)
+                    if rendered.getbbox() is None:
+                        raise ValueError("Rendered view has no visible pixels")
+                    rendered.save(image)
+                    metadata = {**item, "object_id": item["object_id"], "normalization_matrix": transform,
+                                "yaw_radians": float(yaw), "render": "orthographic Gaussian proxy, camera +z",
+                                "target": "isotropic surface-sampled mesh proxy; not a pretrained teacher"}
+                    rows.append(cache_sample(staging, f"{stem}-v{view}", image, rotated, args.grid,
+                                             source="mesh-proxy:" + item["repo"], extra=metadata))
+                for folder in ("images", "targets"):
+                    (out / folder).mkdir(exist_ok=True)
+                    for file in (staging / folder).iterdir():
+                        file.replace(out / folder / file.name)
+                all_rows.extend(rows)
+                seen.add(checksum)
+                provenance.append(item)
+                completed.add((item["repo"], item["asset_id"]))
+                accepted += 1
+                save_progress(out, args, all_rows, provenance, failures)
+                print(json.dumps({"repo": item["repo"], "accepted": accepted, "requested": wanted,
+                                  "asset": item["asset_id"]}), flush=True)
+            except RuntimeError:
+                raise  # resource limits are a hard stop
+            except Exception as exc:
+                failures.append({"repo": item["repo"], "asset": item["asset_id"],
+                                 "error": type(exc).__name__ + ": " + str(exc)[:200],
+                                 "terminal": "no visible pixels" in str(exc)})
+                print(json.dumps({"skipped": item["asset_id"], "reason": failures[-1]["error"]}), flush=True)
+            finally:
+                shutil.rmtree(staging, ignore_errors=True)
+        counts[repo] = {"requested": wanted, "prepared": accepted}
+    group_duplicates(all_rows, provenance)
+    save_progress(out, args, all_rows, provenance, failures)
+    (out / "sources.json").write_text(json.dumps(provenance, indent=2))
+    (out / "skipped.json").write_text(json.dumps(failures, indent=2))
+    report = {"counts": counts, "samples": len(all_rows), "objects": len(provenance),
+              "distinct_groups": len({r["metadata"]["object_id"] for r in all_rows}),
+              "settings": vars(args), "rendered_proxy_data": True,
+              "excluded": ["scenario-labs/3d-collection-hunyuan", "3dlg-hcvc/MultiScan",
+                           "huanngzh/3D-Front", "facebook/show3d-dataset", "Voxel51/gaussian_splatting"]}
+    (out / "preparation.json").write_text(json.dumps(report, indent=2))
+    if any(v["prepared"] < v["requested"] for v in counts.values()):
+        raise ValueError("Not enough eligible assets. Completed objects are saved. Rerun with --resume and a larger --objaverse-shards value.")
+    if report["distinct_groups"] < 4:
+        raise ValueError("Not enough independent object groups")
+    # The test partition never enters training or checkpoint selection.
+    development, test = split_rows(all_rows, .15, args.seed + 1)
+    for name, rows in [("manifest.jsonl", development), ("test-manifest.jsonl", test)]:
+        (out / name).write_text("".join(json.dumps(r) + "\n" for r in rows))
+    print(json.dumps(report, indent=2))
+
+
+def main():
+    p = argparse.ArgumentParser(description=__doc__)
+    p.add_argument("--out", required=True)
+    p.add_argument("--cache", default="data/downloads")
+    p.add_argument("--scenario", type=int, default=64)
+    p.add_argument("--objaverse", type=int, default=32)
+    p.add_argument("--objaverse-shards", type=int, default=8)
+    p.add_argument("--resume", action="store_true", help="Reuse and verify completed objects, including older failed runs")
+    p.add_argument("--grid", type=int, choices=[8, 16, 32], default=16)
+    p.add_argument("--views", type=int, default=4)
+    p.add_argument("--surface-points", type=int, default=4096)
+    p.add_argument("--seed", type=int, default=42)
+    p.add_argument("--max-file-mb", type=int, default=16)
+    p.add_argument("--max-download-mb", type=int, default=2048)
+    p.add_argument("--reserve-gb", type=float, default=2)
+    args = p.parse_args()
+    if min(args.scenario, args.objaverse) < 0 or not 1 <= args.objaverse_shards <= 160:
+        p.error("Invalid object counts or shard count")
+    if min(args.views, args.surface_points, args.max_file_mb, args.max_download_mb, args.reserve_gb) <= 0:
+        p.error("Counts and limits must be positive")
+    prepare(args)
+
+
+if __name__ == "__main__":
+    main()

scripts/release.py

@@ -0,0 +1,228 @@
+"""Evaluate a completed run, stage a self-contained release, optionally publish it."""
+import argparse
+import hashlib
+import json
+import shutil
+from pathlib import Path
+
+import torch
+from torch.utils.data import DataLoader
+
+from image3d_student.data import CachedDataset, load_manifest
+from image3d_student.engine import device_for, evaluate, generate
+from image3d_student.model import Student
+
+
+def sha(path):
+    return hashlib.sha256(Path(path).read_bytes()).hexdigest()
+
+
+def evaluate_release(args):
+    run, dataset = Path(args.run), Path(args.data)
+    meta = json.loads((run / "run.json").read_text())
+    checkpoint = torch.load(run / "best.pt", map_location="cpu", weights_only=True)
+    last = torch.load(run / "last.pt", map_location="cpu", weights_only=True)
+    if last["step"] != meta["steps_requested"]:
+        raise ValueError("Training did not complete the requested steps")
+    if checkpoint.get("step", 0) < 1 or not meta.get("initialization"):
+        raise ValueError("Expected completed post-training from a base checkpoint")
+    if sha(args.base) != meta["initialization"]["sha256"]:
+        raise ValueError("Base checkpoint differs from the training initialization")
+    if sha(dataset / "manifest.jsonl") != meta["manifest_sha256"]:
+        raise ValueError("Training manifest changed")
+    development = load_manifest(dataset / "manifest.jsonl")
+    test = load_manifest(dataset / "test-manifest.jsonl")
+    selected_ids = set(meta["train_ids"]) | set(meta["val_ids"])
+    if selected_ids != {r["id"] for r in development}:
+        raise ValueError("Run split does not match development manifest")
+    if {r["metadata"]["object_id"] for r in development} & {r["metadata"]["object_id"] for r in test}:
+        raise ValueError("Test object leakage")
+    for key in ["image_sha256", "target_sha256"]:
+        if {r[key] for r in development} & {r[key] for r in test}:
+            raise ValueError("Duplicate data across development and test")
+    device = device_for(args.device)
+    model = Student(**checkpoint["config"]).to(device)
+    model.load_state_dict(checkpoint["model"])
+    loader = DataLoader(CachedDataset(dataset / "test-manifest.jsonl"), batch_size=1)
+    final = evaluate(model, loader, device)
+    base = torch.load(args.base, map_location="cpu", weights_only=True)
+    initial = Student(**checkpoint["config"]).to(device)
+    result = initial.load_state_dict({k: v for k, v in base["model"].items() if k not in ("coords", "centers")}, strict=False)
+    if set(result.missing_keys) != {"coords", "centers"} or result.unexpected_keys:
+        raise ValueError("Base architecture mismatch")
+    baseline = evaluate(initial, loader, device)
+    best_validation = min(json.loads(line)["validation"]["loss"] for line in
+                          (run / "metrics.jsonl").read_text().splitlines())
+    checks = {"validation_loss_improved": best_validation < meta["baseline_validation"]["loss"],
+              "test_loss_improved": final["loss"] < baseline["loss"],
+              "test_occupancy_iou_improved": final["occupancy_iou"] > baseline["occupancy_iou"],
+              "test_occupancy_iou_at_least_005": final["occupancy_iou"] >= .05}
+    report = {"checkpoint_sha256": sha(run / "best.pt"), "base_sha256": sha(args.base),
+              "test_manifest_sha256": sha(dataset / "test-manifest.jsonl"),
+              "test_objects": len({r["metadata"]["object_id"] for r in test}),
+              "test_samples": len(test), "baseline_test": baseline, "posttrained_test": final,
+              "checks": checks, "passed": all(checks.values()),
+              "scope": "Rendered mesh-proxy evaluation only; does not establish real-photo or mesh reconstruction quality"}
+    (run / "evaluation.json").write_text(json.dumps(report, indent=2))
+    print(json.dumps(report, indent=2), flush=True)
+    # Keep qualitative inspection files local; all held-out objects, first view.
+    example_dir = run / "inspection"
+    example_dir.mkdir(exist_ok=True)
+    seen = set()
+    from image3d_student.splats import preview, read_ply
+    from PIL import Image, ImageDraw
+    for row in test:
+        group = row["metadata"]["object_id"]
+        if group in seen:
+            continue
+        seen.add(group)
+        out = example_dir / (row["id"] + ".ply")
+        if not out.exists():
+            try:
+                generate(run / "best.pt", dataset / row["image"], out, args.device)
+            except ValueError as exc:
+                if "No occupied cells" not in str(exc):
+                    raise
+                report["checks"]["nonempty_examples"] = False
+                report["passed"] = False
+                continue
+        sheet = Image.new("RGB", (512, 152), "black")
+        sheet.paste(Image.open(dataset / row["image"]).convert("RGB").resize((128, 128)), (0, 24))
+        splats = read_ply(out)
+        for i, angle in enumerate([0, 1.5707963, 3.1415927]):
+            sheet.paste(preview(splats, size=128, yaw=angle), (128 * (i + 1), 24))
+        ImageDraw.Draw(sheet).text((5, 5), "Input proxy | prediction front | side | back", fill="white")
+        sheet.save(out.with_suffix(".png"))
+        if len(seen) >= 8:
+            break
+    (run / "evaluation.json").write_text(json.dumps(report, indent=2))
+    if not report["passed"]:
+        raise ValueError("Evaluation gate failed. Nothing was published. Inspect evaluation.json and improve data/training.")
+    return checkpoint, meta, report
+
+
+def stage(args, checkpoint, meta, report):
+    source = Path(__file__).resolve().parents[1]
+    release = Path(args.release)
+    if release.exists():
+        raise ValueError("Release directory already exists; choose a new --release path")
+    release.mkdir(parents=True)
+    shutil.copytree(source / "src", release / "src", ignore=shutil.ignore_patterns("__pycache__", "*.egg-info"))
+    shutil.copytree(source / "scripts", release / "scripts", ignore=shutil.ignore_patterns("__pycache__"))
+    shutil.copytree(source / "licenses", release / "licenses")
+    for filename in ["pyproject.toml", "LICENSE", "NOTICE", "THIRD_PARTY.md", "DATASETS.md", "COMMANDS.md", "setup-mac.sh", "train-mac.sh", "requirements-tested-macos.txt"]:
+        shutil.copyfile(source / filename, release / filename)
+    # Publish inference weights only; optimizer and local absolute paths stay local.
+    public_meta = {k: v for k, v in meta.items() if k != "dataset"}
+    torch.save({"format": 1, "config": checkpoint["config"], "model": checkpoint["model"],
+                "step": checkpoint["step"], "metadata": public_meta}, release / "model.pt")
+    (release / "config.json").write_text(json.dumps(checkpoint["config"], indent=2))
+    (release / "training.json").write_text(json.dumps(public_meta, indent=2))
+    (release / "evaluation.json").write_text(json.dumps({**report,
+        "published_model_sha256": sha(release / "model.pt")}, indent=2))
+    shutil.copyfile(Path(args.data) / "sources.json", release / "ATTRIBUTIONS.json")
+    used = sorted({r["repo"] for r in json.loads((release / "ATTRIBUTIONS.json").read_text())})
+    datasets_yaml = "\n".join("- " + repo for repo in used)
+    text = f'''---
+license: apache-2.0
+pipeline_tag: image-to-3d
+base_model: Lucasgitguy-co/image3d-student
+model_name: Forma3D-Tiny v0.2
+datasets:
+{datasets_yaml}
+tags:
+- pytorch
+- gaussian-splatting
+- research-prototype
+- mesh-proxy-supervision
+---
+# Forma3D-Tiny v0.2
+
+An experimental compact image-to-Gaussian model post-trained from Image3D Student's
+synthetic demonstration checkpoint. This is a coarse research baseline, not a
+general-purpose photo-to-3D model. Its grid is {checkpoint["config"]["grid"]} cubed and
+it has {meta["parameters"]:,} parameters. Selected checkpoint: step {checkpoint["step"]};
+completed run: {meta["steps_requested"]} steps.
+
+## Actual training data and preprocessing
+
+Only the datasets listed above were used, with per-asset provenance in ATTRIBUTIONS.json.
+Scenario assets are CC-BY-4.0; the Objaverse subset is CC0. Original objects were centered
+and uniformly scaled into a 0.9-wide cube, surface sampled, and converted to isotropic
+Gaussian proxy targets. Orthographic images were rendered from these same proxy clouds.
+This is not teacher distillation from Idol, Hunyuan, InstantMesh, or Hi3D, and it did not
+train on natural photographs, MultiScan, 3D-Front, Show3D, or Voxel51 scene splats.
+
+Related source inputs and all views stay in the same object group. A separate 15% test
+partition is excluded from training and validation-based checkpoint selection.
+
+## Measured results
+
+Independent test objects: {report["test_objects"]}; test views: {report["test_samples"]}.
+Base test loss: {report["baseline_test"]["loss"]:.6f}; post-trained test loss:
+{report["posttrained_test"]["loss"]:.6f}. Base occupancy IoU:
+{report["baseline_test"]["occupancy_iou"]:.6f}; post-trained occupancy IoU:
+{report["posttrained_test"]["occupancy_iou"]:.6f}.
+See evaluation.json for the full results and checks. These scores measure coarse proxy
+reconstruction on the rendered data distribution; they do not prove photo realism,
+watertight meshes, production quality, or texture fidelity. Near duplicates can remain
+despite source grouping and exact-byte deduplication.
+
+## Run on a Mac
+
+Download this repository, then run `bash setup-mac.sh` and
+`source "$HOME/Library/Application Support/Forma3D/venv/bin/activate"`.
+
+```sh
+image3d generate --checkpoint model.pt --image your-centered-cutout.png \\
+  --out results/object.ply --device mps
+image3d preview --ply results/object.ply --out results/preview.png
+```
+
+Inputs are centered objects on black, matching the training framing. Natural photos
+are outside the verified distribution. Output is Gaussian PLY, not a triangle mesh.
+CPU works with `--device cpu`; CUDA support is implemented but was not tested on the
+Mac used to prepare these scripts.
+
+## License and attribution
+
+Source code and these weights are offered under Apache-2.0. Dataset and individual
+asset licenses remain separate; retain ATTRIBUTIONS.json and consult DATASETS.md.
+This license statement does not grant rights to third-party trademarks or likenesses.
+See COMMANDS.md for reproduction commands.
+'''
+    (release / "README.md").write_text(text)
+    sums = [sha(p) + "  " + str(p.relative_to(release)) for p in sorted(release.rglob("*")) if p.is_file()]
+    (release / "SHA256SUMS").write_text("\n".join(sums) + "\n")
+    return release
+
+
+def main():
+    p = argparse.ArgumentParser(description=__doc__)
+    p.add_argument("--run", required=True)
+    p.add_argument("--data", required=True)
+    p.add_argument("--base", required=True)
+    p.add_argument("--release", default="release/forma3d-tiny")
+    p.add_argument("--repo", default="Lucasgitguy-co/forma3d-tiny")
+    p.add_argument("--device", choices=["mps", "cpu", "cuda", "auto"], default="mps")
+    p.add_argument("--publish", action="store_true")
+    args = p.parse_args()
+    checkpoint, meta, report = evaluate_release(args)
+    release = stage(args, checkpoint, meta, report)
+    if args.publish:
+        from huggingface_hub import HfApi
+        api = HfApi()
+        # Refuse accidental replacement of a previously published model.
+        if api.repo_exists(args.repo, repo_type="model"):
+            raise ValueError("Repository already exists. Choose a new --repo; no overwrite was performed.")
+        api.create_repo(args.repo, repo_type="model", private=True)
+        commit = api.upload_folder(repo_id=args.repo, folder_path=release,
+                                   commit_message="Publish evaluated Forma3D-Tiny v0.2")
+        api.update_repo_settings(args.repo, private=False)
+        print(f"Published https://huggingface.co/{args.repo} at {commit.oid}")
+    else:
+        print(f"Evaluated release staged at {release}; nothing published.")
+
+
+if __name__ == "__main__":
+    main()

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)

stage_v2.py

@@ -0,0 +1,159 @@
+"""Evaluate versus pinned forma3d-tiny, stage honest v2 metadata, never upload."""
+import argparse
+import hashlib
+import importlib.util
+import json
+import shutil
+from pathlib import Path
+import torch
+from audit_data import audit
+
+ROOT = Path(__file__).resolve().parent
+REV = 'e80b8d895cc2e405894473abe4ce40b3472eaca7'
+BASE = 'Lucasgitguy-co/forma3d-tiny'
+
+def sha(p):
+    return hashlib.sha256(Path(p).read_bytes()).hexdigest()
+
+
+def main():
+    p = argparse.ArgumentParser()
+    for name in ('run','data','base','release'):
+        p.add_argument('--'+name, required=True)
+    p.add_argument('--device', default='mps', choices=['mps','cpu'])
+    args = p.parse_args()
+    destination = Path(args.release)
+    if destination.exists():
+        raise ValueError('Release directory exists; choose a fresh --release path')
+    audit(args.data, ROOT / 'upstream/ATTRIBUTIONS.json')
+    # Ensure the asserted parent is the pinned public checkpoint, not another run.
+    if sha(args.base) != '83c065d2a50cf086928542cf8d40dc4416b379e38b9aa61d842dc9106d4b3306':
+        raise ValueError('Expected the pinned published forma3d-tiny model.pt')
+    spec = importlib.util.spec_from_file_location('pinned_release', ROOT / 'upstream/scripts/release.py')
+    module = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(module)
+    checkpoint, meta, report = module.evaluate_release(args)
+    # Upstream gate checks completed training, validation loss, held-out loss/IoU,
+    # source separation, initialization hash and nonempty qualitative predictions.
+    source = ROOT / 'upstream'
+    destination.mkdir(parents=True)
+    for folder in ('src','licenses'):
+        shutil.copytree(source / folder, destination / folder,
+                        ignore=shutil.ignore_patterns('__pycache__','*.egg-info'))
+    for name in ('LICENSE','NOTICE','THIRD_PARTY.md','DATASETS.md','requirements-tested-macos.txt'):
+        shutil.copyfile(source / name, destination / name)
+    project = (source / 'pyproject.toml').read_text()
+    project = project.replace('name = "forma3d-tiny"','name = "forma3d-tiny-2"')
+    project = project.replace('version = "0.2.0"','version = "0.3.0"')
+    (destination / 'pyproject.toml').write_text(project)
+    (destination / 'scripts').mkdir()
+    for name in ('prepare_hf.py','release.py'):
+        shutil.copyfile(source / 'scripts' / name, destination / 'scripts' / name)
+    # This file set can reproduce the training recipe from pinned upstream.
+    for name in ('posttrain.sh','prepare_v2.py','audit_data.py','stage_v2.py','publish_v2.py','COMMANDS.md'):
+        shutil.copyfile(ROOT / name, destination / name)
+    public_meta = {k:v for k,v in meta.items() if k != 'dataset'}
+    public_meta.update({'base_model':BASE, 'base_revision':REV,
+                        'training_method':'weights-only continuation; fresh AdamW',
+                        'known_v1_assets_excluded':True})
+    torch.save({'format':1,'config':checkpoint['config'],'model':checkpoint['model'],
+                'step':checkpoint['step'],'metadata':public_meta}, destination / 'model.pt')
+    (destination / 'config.json').write_text(json.dumps(checkpoint['config'],indent=2))
+    (destination / 'training.json').write_text(json.dumps(public_meta,indent=2))
+    report.update({'base_model':BASE,'base_revision':REV,
+                   'published_model_sha256':sha(destination / 'model.pt')})
+    (destination / 'evaluation.json').write_text(json.dumps(report,indent=2))
+    for src, dst in [('sources.json','ATTRIBUTIONS.json'),('v2-audit.json','data-audit.json'),
+                     ('preparation.json','preparation.json')]:
+        # preparation.json includes user-local paths; publish only portable fields.
+        if src == 'preparation.json':
+            prepared = json.loads((Path(args.data) / src).read_text())
+            prepared['settings'] = {k:v for k,v in prepared['settings'].items() if k not in ('out','cache')}
+            (destination / dst).write_text(json.dumps(prepared,indent=2))
+        else:
+            shutil.copyfile(Path(args.data) / src,destination / dst)
+    shutil.copyfile(Path(args.run) / 'metrics.jsonl',destination / 'metrics.jsonl')
+    if (ROOT / 'runs/environment.txt').exists():
+        lines = (ROOT / 'runs/environment.txt').read_text().splitlines()
+        portable = [line for line in lines if ' @ file:' not in line and not line.startswith('-e ')]
+        portable.append('# Local forma3d-tiny 0.2.0 source: '+BASE+' @ '+REV)
+        (destination / 'environment.txt').write_text('\n'.join(portable)+'\n')
+    datasets = sorted({r['repo'] for r in json.loads((destination / 'ATTRIBUTIONS.json').read_text())})
+    dataset_yaml = '\n'.join('- '+d for d in datasets)
+    bt, ft = report['baseline_test'],report['posttrained_test']
+    card = f'''---
+license: apache-2.0
+pipeline_tag: image-to-3d
+base_model: {BASE}
+base_model_relation: finetune
+model_name: Forma3D Tiny 2
+datasets:
+{dataset_yaml}
+tags:
+- pytorch
+- gaussian-splatting
+- mesh-proxy-supervision
+- research-prototype
+---
+# Forma3D Tiny 2
+
+A {meta['parameters']:,}-parameter image-to-Gaussian research model continued from
+{BASE} at revision `{REV}`. The optimizer starts fresh. It uses a
+{checkpoint['config']['grid']} cubed grid and width {checkpoint['config']['width']}.
+Selected checkpoint step {checkpoint['step']} from {meta['steps_requested']} completed steps.
+
+## Training
+
+See training.json and metrics.jsonl for actual optimizer settings and validation
+history. Inputs are orthographic renders of centered mesh-derived Gaussian proxy
+clouds on black. Targets are isotropic surface samples compressed to one Gaussian
+per occupied grid cell. No pretrained 3D teacher was run. No natural-photo training
+or differentiable rendering is claimed. Asset IDs, known source groups, and exact
+mesh hashes from all 96 known v1 assets were excluded. Near duplicates can remain.
+The separate 15 percent object-group test split does not enter checkpoint selection;
+20 percent of development groups supply validation. Counts are realized counts in
+preparation.json and data-audit.json, not assumed independent asset counts.
+
+## Evaluation
+
+Both checkpoints were evaluated on the same new held-out proxy data.
+
+| Metric | Starting Forma3D Tiny | Selected Forma3D Tiny 2 |
+|---|---:|---:|
+| Mean test loss | {bt['loss']:.6f} | {ft['loss']:.6f} |
+| Mean view occupancy IoU at threshold 0.5 | {bt['occupancy_iou']:.6f} | {ft['occupancy_iou']:.6f} |
+
+Test groups: {report['test_objects']}; views: {report['test_samples']}.
+See evaluation.json for hashes and release gates. Metrics are view-averaged over
+proxy renders. They do not establish photo realism, novel-view image quality,
+mesh quality, texture fidelity, gameplay, or general-purpose 3D reconstruction.
+
+## Use
+
+Install this source with Python 3.11 and `uv pip install ".[data]"` in a virtual
+environment, then run:
+
+```bash
+image3d generate --checkpoint model.pt --image your-centered-cutout.png \\
+  --out results/object.ply --device mps
+image3d preview --ply results/object.ply --out results/preview.png
+```
+
+Output is Gaussian PLY. Inputs should match centered objects on black. See
+COMMANDS.md for the complete continuation recipe. This model retains the same
+architecture; no text-prompt conditioning or new mesh decoder was added.
+
+## License
+
+Publisher source and weights are offered under Apache 2.0. Retain NOTICE,
+THIRD_PARTY.md and ATTRIBUTIONS.json. CC BY Scenario assets and CC0 Objaverse
+assets have their own attribution and license records in DATASETS.md.
+'''
+    (destination / 'README.md').write_text(card)
+    sums = [sha(f)+'  '+str(f.relative_to(destination)) for f in sorted(destination.rglob('*')) if f.is_file()]
+    (destination / 'SHA256SUMS').write_text('\n'.join(sums)+'\n')
+    print('Staged evaluated release at',destination)
+    print('Inspect PNG files under',Path(args.run)/'inspection','before optional publication.')
+
+if __name__ == '__main__':
+    main()

training.json

@@ -0,0 +1,914 @@
+{
+  "synthetic_only": false,
+  "contains_synthetic": false,
+  "device": "mps",
+  "torch": "2.15.0",
+  "seed": 43,
+  "train_ids": [
+    "35d930c154dd6808d06a-v0",
+    "35d930c154dd6808d06a-v1",
+    "35d930c154dd6808d06a-v2",
+    "35d930c154dd6808d06a-v3",
+    "58da43454d31f401a82a-v0",
+    "58da43454d31f401a82a-v1",
+    "58da43454d31f401a82a-v2",
+    "58da43454d31f401a82a-v3",
+    "d4453f35dd55b9fdbe77-v0",
+    "d4453f35dd55b9fdbe77-v1",
+    "d4453f35dd55b9fdbe77-v2",
+    "d4453f35dd55b9fdbe77-v3",
+    "53abbbe27d8cae248360-v0",
+    "53abbbe27d8cae248360-v1",
+    "53abbbe27d8cae248360-v2",
+    "53abbbe27d8cae248360-v3",
+    "083ef10612b14e4fd91f-v0",
+    "083ef10612b14e4fd91f-v1",
+    "083ef10612b14e4fd91f-v2",
+    "083ef10612b14e4fd91f-v3",
+    "dcd7b3ffd85049cfe762-v0",
+    "dcd7b3ffd85049cfe762-v1",
+    "dcd7b3ffd85049cfe762-v2",
+    "dcd7b3ffd85049cfe762-v3",
+    "89f2af1771b298088496-v0",
+    "89f2af1771b298088496-v1",
+    "89f2af1771b298088496-v2",
+    "89f2af1771b298088496-v3",
+    "aa87bf05321d963c3de9-v0",
+    "aa87bf05321d963c3de9-v1",
+    "aa87bf05321d963c3de9-v2",
+    "aa87bf05321d963c3de9-v3",
+    "8b5e78df6cc3bc96ca2a-v0",
+    "8b5e78df6cc3bc96ca2a-v1",
+    "8b5e78df6cc3bc96ca2a-v2",
+    "8b5e78df6cc3bc96ca2a-v3",
+    "d186a120c94371ef7a9d-v0",
+    "d186a120c94371ef7a9d-v1",
+    "d186a120c94371ef7a9d-v2",
+    "d186a120c94371ef7a9d-v3",
+    "13fc4338908a8073ab71-v0",
+    "13fc4338908a8073ab71-v1",
+    "13fc4338908a8073ab71-v2",
+    "13fc4338908a8073ab71-v3",
+    "95b87385ad6d55cb43a9-v0",
+    "95b87385ad6d55cb43a9-v1",
+    "95b87385ad6d55cb43a9-v2",
+    "95b87385ad6d55cb43a9-v3",
+    "a9324f8dc45d1616a80a-v0",
+    "a9324f8dc45d1616a80a-v1",
+    "a9324f8dc45d1616a80a-v2",
+    "a9324f8dc45d1616a80a-v3",
+    "3b24fd8b39813b859983-v0",
+    "3b24fd8b39813b859983-v1",
+    "3b24fd8b39813b859983-v2",
+    "3b24fd8b39813b859983-v3",
+    "4f6ac99f7fd499a7d43c-v0",
+    "4f6ac99f7fd499a7d43c-v1",
+    "4f6ac99f7fd499a7d43c-v2",
+    "4f6ac99f7fd499a7d43c-v3",
+    "42d2395a94668a58c4ad-v0",
+    "42d2395a94668a58c4ad-v1",
+    "42d2395a94668a58c4ad-v2",
+    "42d2395a94668a58c4ad-v3",
+    "b1deb9d963a2cd12e16c-v0",
+    "b1deb9d963a2cd12e16c-v1",
+    "b1deb9d963a2cd12e16c-v2",
+    "b1deb9d963a2cd12e16c-v3",
+    "b4afe853eaef7b154d1f-v0",
+    "b4afe853eaef7b154d1f-v1",
+    "b4afe853eaef7b154d1f-v2",
+    "b4afe853eaef7b154d1f-v3",
+    "12e6fa6b9b3fde9b0daf-v0",
+    "12e6fa6b9b3fde9b0daf-v1",
+    "12e6fa6b9b3fde9b0daf-v2",
+    "12e6fa6b9b3fde9b0daf-v3",
+    "8b2af62279572f1c348d-v0",
+    "8b2af62279572f1c348d-v1",
+    "8b2af62279572f1c348d-v2",
+    "8b2af62279572f1c348d-v3",
+    "9b2928d8e9b6e432b208-v0",
+    "9b2928d8e9b6e432b208-v1",
+    "9b2928d8e9b6e432b208-v2",
+    "9b2928d8e9b6e432b208-v3",
+    "0b603cd8889a5a16f625-v0",
+    "0b603cd8889a5a16f625-v1",
+    "0b603cd8889a5a16f625-v2",
+    "0b603cd8889a5a16f625-v3",
+    "aa7a5a2f97543fcc8c24-v0",
+    "aa7a5a2f97543fcc8c24-v1",
+    "aa7a5a2f97543fcc8c24-v2",
+    "aa7a5a2f97543fcc8c24-v3",
+    "d4547a44652027eec362-v0",
+    "d4547a44652027eec362-v1",
+    "d4547a44652027eec362-v2",
+    "d4547a44652027eec362-v3",
+    "09eda16a9ffee9043ad8-v0",
+    "09eda16a9ffee9043ad8-v1",
+    "09eda16a9ffee9043ad8-v2",
+    "09eda16a9ffee9043ad8-v3",
+    "149bc550a730196bfb3e-v0",
+    "149bc550a730196bfb3e-v1",
+    "149bc550a730196bfb3e-v2",
+    "149bc550a730196bfb3e-v3",
+    "ba456d938777d3d97c7a-v0",
+    "ba456d938777d3d97c7a-v1",
+    "ba456d938777d3d97c7a-v2",
+    "ba456d938777d3d97c7a-v3",
+    "b1d9ca1078489bcc8b59-v0",
+    "b1d9ca1078489bcc8b59-v1",
+    "b1d9ca1078489bcc8b59-v2",
+    "b1d9ca1078489bcc8b59-v3",
+    "e2774da2d6fdbf320005-v0",
+    "e2774da2d6fdbf320005-v1",
+    "e2774da2d6fdbf320005-v2",
+    "e2774da2d6fdbf320005-v3",
+    "9accb35147475a98151b-v0",
+    "9accb35147475a98151b-v1",
+    "9accb35147475a98151b-v2",
+    "9accb35147475a98151b-v3",
+    "9154f51711aa5cad741c-v0",
+    "9154f51711aa5cad741c-v1",
+    "9154f51711aa5cad741c-v2",
+    "9154f51711aa5cad741c-v3",
+    "714a6ef2a9b86176887e-v0",
+    "714a6ef2a9b86176887e-v1",
+    "714a6ef2a9b86176887e-v2",
+    "714a6ef2a9b86176887e-v3",
+    "f475d0b020f840a08da6-v0",
+    "f475d0b020f840a08da6-v1",
+    "f475d0b020f840a08da6-v2",
+    "f475d0b020f840a08da6-v3",
+    "b4becf168c3c3e72d1a1-v0",
+    "b4becf168c3c3e72d1a1-v1",
+    "b4becf168c3c3e72d1a1-v2",
+    "b4becf168c3c3e72d1a1-v3",
+    "a93c298b61fac88b7815-v0",
+    "a93c298b61fac88b7815-v1",
+    "a93c298b61fac88b7815-v2",
+    "a93c298b61fac88b7815-v3",
+    "f098047bad1f2c42e522-v0",
+    "f098047bad1f2c42e522-v1",
+    "f098047bad1f2c42e522-v2",
+    "f098047bad1f2c42e522-v3",
+    "6f5650ce949ed44855db-v0",
+    "6f5650ce949ed44855db-v1",
+    "6f5650ce949ed44855db-v2",
+    "6f5650ce949ed44855db-v3",
+    "d835f0e933e6a5401e5f-v0",
+    "d835f0e933e6a5401e5f-v1",
+    "d835f0e933e6a5401e5f-v2",
+    "d835f0e933e6a5401e5f-v3",
+    "e141279821ff0cd00133-v0",
+    "e141279821ff0cd00133-v1",
+    "e141279821ff0cd00133-v2",
+    "e141279821ff0cd00133-v3",
+    "8a833c632913fb94bcfc-v0",
+    "8a833c632913fb94bcfc-v1",
+    "8a833c632913fb94bcfc-v2",
+    "8a833c632913fb94bcfc-v3",
+    "d588a44a75ac91946615-v0",
+    "d588a44a75ac91946615-v1",
+    "d588a44a75ac91946615-v2",
+    "d588a44a75ac91946615-v3",
+    "161a50c2c6a490dba3b4-v0",
+    "161a50c2c6a490dba3b4-v1",
+    "161a50c2c6a490dba3b4-v2",
+    "161a50c2c6a490dba3b4-v3",
+    "f7ad3a2b9911e7f6ea52-v0",
+    "f7ad3a2b9911e7f6ea52-v1",
+    "f7ad3a2b9911e7f6ea52-v2",
+    "f7ad3a2b9911e7f6ea52-v3",
+    "e44219edeb2584e028c7-v0",
+    "e44219edeb2584e028c7-v1",
+    "e44219edeb2584e028c7-v2",
+    "e44219edeb2584e028c7-v3",
+    "a47cb57e5c8f24e11587-v0",
+    "a47cb57e5c8f24e11587-v1",
+    "a47cb57e5c8f24e11587-v2",
+    "a47cb57e5c8f24e11587-v3",
+    "0975f7262f09261c93cf-v0",
+    "0975f7262f09261c93cf-v1",
+    "0975f7262f09261c93cf-v2",
+    "0975f7262f09261c93cf-v3",
+    "b48ccce5d32e4c140de6-v0",
+    "b48ccce5d32e4c140de6-v1",
+    "b48ccce5d32e4c140de6-v2",
+    "b48ccce5d32e4c140de6-v3",
+    "d5b8361860cb4c246db4-v0",
+    "d5b8361860cb4c246db4-v1",
+    "d5b8361860cb4c246db4-v2",
+    "d5b8361860cb4c246db4-v3",
+    "0ab373eff89b242a8264-v0",
+    "0ab373eff89b242a8264-v1",
+    "0ab373eff89b242a8264-v2",
+    "0ab373eff89b242a8264-v3",
+    "5008f631374851f24ee1-v0",
+    "5008f631374851f24ee1-v1",
+    "5008f631374851f24ee1-v2",
+    "5008f631374851f24ee1-v3",
+    "20cc4d37f55fbf3ed7ee-v0",
+    "20cc4d37f55fbf3ed7ee-v1",
+    "20cc4d37f55fbf3ed7ee-v2",
+    "20cc4d37f55fbf3ed7ee-v3",
+    "01cdf02ead8b5e865381-v0",
+    "01cdf02ead8b5e865381-v1",
+    "01cdf02ead8b5e865381-v2",
+    "01cdf02ead8b5e865381-v3",
+    "2375d060b093b622ced0-v0",
+    "2375d060b093b622ced0-v1",
+    "2375d060b093b622ced0-v2",
+    "2375d060b093b622ced0-v3",
+    "b01c4cf0c7f7066d1630-v0",
+    "b01c4cf0c7f7066d1630-v1",
+    "b01c4cf0c7f7066d1630-v2",
+    "b01c4cf0c7f7066d1630-v3",
+    "6ff55fc61e7e5ee7e5cf-v0",
+    "6ff55fc61e7e5ee7e5cf-v1",
+    "6ff55fc61e7e5ee7e5cf-v2",
+    "6ff55fc61e7e5ee7e5cf-v3",
+    "01f73f72cedfa86e7b47-v0",
+    "01f73f72cedfa86e7b47-v1",
+    "01f73f72cedfa86e7b47-v2",
+    "01f73f72cedfa86e7b47-v3",
+    "b3d18f648ac9bb9154ec-v0",
+    "b3d18f648ac9bb9154ec-v1",
+    "b3d18f648ac9bb9154ec-v2",
+    "b3d18f648ac9bb9154ec-v3",
+    "a0ffe8c7cab33d01d46d-v0",
+    "a0ffe8c7cab33d01d46d-v1",
+    "a0ffe8c7cab33d01d46d-v2",
+    "a0ffe8c7cab33d01d46d-v3",
+    "abd072738608ed0853e0-v0",
+    "abd072738608ed0853e0-v1",
+    "abd072738608ed0853e0-v2",
+    "abd072738608ed0853e0-v3",
+    "854fdbac422e240a3bc0-v0",
+    "854fdbac422e240a3bc0-v1",
+    "854fdbac422e240a3bc0-v2",
+    "854fdbac422e240a3bc0-v3",
+    "c2827f8915f273e8b2bf-v0",
+    "c2827f8915f273e8b2bf-v1",
+    "c2827f8915f273e8b2bf-v2",
+    "c2827f8915f273e8b2bf-v3",
+    "1e4bee54e046daa3432e-v0",
+    "1e4bee54e046daa3432e-v1",
+    "1e4bee54e046daa3432e-v2",
+    "1e4bee54e046daa3432e-v3",
+    "df771458eda4d068489b-v0",
+    "df771458eda4d068489b-v1",
+    "df771458eda4d068489b-v2",
+    "df771458eda4d068489b-v3",
+    "9fd36b6629dbe456d618-v0",
+    "9fd36b6629dbe456d618-v1",
+    "9fd36b6629dbe456d618-v2",
+    "9fd36b6629dbe456d618-v3",
+    "54f1a71cfdb946aa1e22-v0",
+    "54f1a71cfdb946aa1e22-v1",
+    "54f1a71cfdb946aa1e22-v2",
+    "54f1a71cfdb946aa1e22-v3",
+    "8a49ade0408a3d33df2e-v0",
+    "8a49ade0408a3d33df2e-v1",
+    "8a49ade0408a3d33df2e-v2",
+    "8a49ade0408a3d33df2e-v3",
+    "aedd94f4737e2811b74f-v0",
+    "aedd94f4737e2811b74f-v1",
+    "aedd94f4737e2811b74f-v2",
+    "aedd94f4737e2811b74f-v3",
+    "7a6e5de02d94d4572241-v0",
+    "7a6e5de02d94d4572241-v1",
+    "7a6e5de02d94d4572241-v2",
+    "7a6e5de02d94d4572241-v3",
+    "fa70e030c60cf1584945-v0",
+    "fa70e030c60cf1584945-v1",
+    "fa70e030c60cf1584945-v2",
+    "fa70e030c60cf1584945-v3",
+    "9b364740f8d8b0b03982-v0",
+    "9b364740f8d8b0b03982-v1",
+    "9b364740f8d8b0b03982-v2",
+    "9b364740f8d8b0b03982-v3",
+    "d7c93bae8d9c53fd14bf-v0",
+    "d7c93bae8d9c53fd14bf-v1",
+    "d7c93bae8d9c53fd14bf-v2",
+    "d7c93bae8d9c53fd14bf-v3",
+    "236674029e7f3e236f31-v0",
+    "236674029e7f3e236f31-v1",
+    "236674029e7f3e236f31-v2",
+    "236674029e7f3e236f31-v3",
+    "5d5948fab5ea82417500-v0",
+    "5d5948fab5ea82417500-v1",
+    "5d5948fab5ea82417500-v2",
+    "5d5948fab5ea82417500-v3",
+    "20889edc9ef2a3944b36-v0",
+    "20889edc9ef2a3944b36-v1",
+    "20889edc9ef2a3944b36-v2",
+    "20889edc9ef2a3944b36-v3",
+    "e5754be7adb3f9a3c2d9-v0",
+    "e5754be7adb3f9a3c2d9-v1",
+    "e5754be7adb3f9a3c2d9-v2",
+    "e5754be7adb3f9a3c2d9-v3",
+    "95e77c467bddee4df460-v0",
+    "95e77c467bddee4df460-v1",
+    "95e77c467bddee4df460-v2",
+    "95e77c467bddee4df460-v3",
+    "63cd92c97338def9a9d2-v0",
+    "63cd92c97338def9a9d2-v1",
+    "63cd92c97338def9a9d2-v2",
+    "63cd92c97338def9a9d2-v3",
+    "aa8df97e47fd90c64457-v0",
+    "aa8df97e47fd90c64457-v1",
+    "aa8df97e47fd90c64457-v2",
+    "aa8df97e47fd90c64457-v3",
+    "aa5d1de39fbae4d7ad9e-v0",
+    "aa5d1de39fbae4d7ad9e-v1",
+    "aa5d1de39fbae4d7ad9e-v2",
+    "aa5d1de39fbae4d7ad9e-v3",
+    "cf5ce7483ba098f616f3-v0",
+    "cf5ce7483ba098f616f3-v1",
+    "cf5ce7483ba098f616f3-v2",
+    "cf5ce7483ba098f616f3-v3",
+    "3e7a80a6c89def99af8d-v0",
+    "3e7a80a6c89def99af8d-v1",
+    "3e7a80a6c89def99af8d-v2",
+    "3e7a80a6c89def99af8d-v3",
+    "bea94a0a0d57de031265-v0",
+    "bea94a0a0d57de031265-v1",
+    "bea94a0a0d57de031265-v2",
+    "bea94a0a0d57de031265-v3",
+    "e6f919123c1a9798050c-v0",
+    "e6f919123c1a9798050c-v1",
+    "e6f919123c1a9798050c-v2",
+    "e6f919123c1a9798050c-v3",
+    "9431e4b8c8fecb8af197-v0",
+    "9431e4b8c8fecb8af197-v1",
+    "9431e4b8c8fecb8af197-v2",
+    "9431e4b8c8fecb8af197-v3",
+    "8a5e2d5ee8a33fba9703-v0",
+    "8a5e2d5ee8a33fba9703-v1",
+    "8a5e2d5ee8a33fba9703-v2",
+    "8a5e2d5ee8a33fba9703-v3",
+    "6d71535d904c466c1bd4-v0",
+    "6d71535d904c466c1bd4-v1",
+    "6d71535d904c466c1bd4-v2",
+    "6d71535d904c466c1bd4-v3",
+    "08c8562106e171463cfa-v0",
+    "08c8562106e171463cfa-v1",
+    "08c8562106e171463cfa-v2",
+    "08c8562106e171463cfa-v3",
+    "5c925cef90b86cca85e7-v0",
+    "5c925cef90b86cca85e7-v1",
+    "5c925cef90b86cca85e7-v2",
+    "5c925cef90b86cca85e7-v3",
+    "dde147e8e1b1f215ab74-v0",
+    "dde147e8e1b1f215ab74-v1",
+    "dde147e8e1b1f215ab74-v2",
+    "dde147e8e1b1f215ab74-v3",
+    "23209c52d6f1e68bc1c4-v0",
+    "23209c52d6f1e68bc1c4-v1",
+    "23209c52d6f1e68bc1c4-v2",
+    "23209c52d6f1e68bc1c4-v3",
+    "72a88cda4d3320bc0b87-v0",
+    "72a88cda4d3320bc0b87-v1",
+    "72a88cda4d3320bc0b87-v2",
+    "72a88cda4d3320bc0b87-v3",
+    "91d6685f4c348b8aae5f-v0",
+    "91d6685f4c348b8aae5f-v1",
+    "91d6685f4c348b8aae5f-v2",
+    "91d6685f4c348b8aae5f-v3",
+    "f3df6b37e1b67fe2c3b0-v0",
+    "f3df6b37e1b67fe2c3b0-v1",
+    "f3df6b37e1b67fe2c3b0-v2",
+    "f3df6b37e1b67fe2c3b0-v3",
+    "bb204ad65ec97e0c1441-v0",
+    "bb204ad65ec97e0c1441-v1",
+    "bb204ad65ec97e0c1441-v2",
+    "bb204ad65ec97e0c1441-v3",
+    "42ca4d64703cfce58aab-v0",
+    "42ca4d64703cfce58aab-v1",
+    "42ca4d64703cfce58aab-v2",
+    "42ca4d64703cfce58aab-v3",
+    "1dbe996e85d24680ea52-v0",
+    "1dbe996e85d24680ea52-v1",
+    "1dbe996e85d24680ea52-v2",
+    "1dbe996e85d24680ea52-v3",
+    "7ae1ecae9954505ec431-v0",
+    "7ae1ecae9954505ec431-v1",
+    "7ae1ecae9954505ec431-v2",
+    "7ae1ecae9954505ec431-v3",
+    "e2739774f499722fab3c-v0",
+    "e2739774f499722fab3c-v1",
+    "e2739774f499722fab3c-v2",
+    "e2739774f499722fab3c-v3",
+    "455a3889e74a63dc4a7f-v0",
+    "455a3889e74a63dc4a7f-v1",
+    "455a3889e74a63dc4a7f-v2",
+    "455a3889e74a63dc4a7f-v3",
+    "266a4542856f979dc406-v0",
+    "266a4542856f979dc406-v1",
+    "266a4542856f979dc406-v2",
+    "266a4542856f979dc406-v3",
+    "bc5c99462af23c1ded8b-v0",
+    "bc5c99462af23c1ded8b-v1",
+    "bc5c99462af23c1ded8b-v2",
+    "bc5c99462af23c1ded8b-v3",
+    "e4747f32b34ac89e93bf-v0",
+    "e4747f32b34ac89e93bf-v1",
+    "e4747f32b34ac89e93bf-v2",
+    "e4747f32b34ac89e93bf-v3",
+    "d60a8e624048386e3094-v0",
+    "d60a8e624048386e3094-v1",
+    "d60a8e624048386e3094-v2",
+    "d60a8e624048386e3094-v3",
+    "3843fa0250d312b4f97c-v0",
+    "3843fa0250d312b4f97c-v1",
+    "3843fa0250d312b4f97c-v2",
+    "3843fa0250d312b4f97c-v3",
+    "422ece43bb9141c25714-v0",
+    "422ece43bb9141c25714-v1",
+    "422ece43bb9141c25714-v2",
+    "422ece43bb9141c25714-v3",
+    "d23622dd4eba6939a1f6-v0",
+    "d23622dd4eba6939a1f6-v1",
+    "d23622dd4eba6939a1f6-v2",
+    "d23622dd4eba6939a1f6-v3",
+    "b569a59ac13185b2c8ad-v0",
+    "b569a59ac13185b2c8ad-v1",
+    "b569a59ac13185b2c8ad-v2",
+    "b569a59ac13185b2c8ad-v3",
+    "2d820b7c3ee95f80d3f4-v0",
+    "2d820b7c3ee95f80d3f4-v1",
+    "2d820b7c3ee95f80d3f4-v2",
+    "2d820b7c3ee95f80d3f4-v3",
+    "5126b25a9bd271eb70c8-v0",
+    "5126b25a9bd271eb70c8-v1",
+    "5126b25a9bd271eb70c8-v2",
+    "5126b25a9bd271eb70c8-v3",
+    "4423c37b9342c83342e6-v0",
+    "4423c37b9342c83342e6-v1",
+    "4423c37b9342c83342e6-v2",
+    "4423c37b9342c83342e6-v3",
+    "a63c2eada3f5f7aa022e-v0",
+    "a63c2eada3f5f7aa022e-v1",
+    "a63c2eada3f5f7aa022e-v2",
+    "a63c2eada3f5f7aa022e-v3",
+    "3f562c2ba5dce1c08966-v0",
+    "3f562c2ba5dce1c08966-v1",
+    "3f562c2ba5dce1c08966-v2",
+    "3f562c2ba5dce1c08966-v3",
+    "0822237a043a73c1a4bc-v0",
+    "0822237a043a73c1a4bc-v1",
+    "0822237a043a73c1a4bc-v2",
+    "0822237a043a73c1a4bc-v3",
+    "3c22586a840d670b5e6c-v0",
+    "3c22586a840d670b5e6c-v1",
+    "3c22586a840d670b5e6c-v2",
+    "3c22586a840d670b5e6c-v3",
+    "c92a387d2882db431f65-v0",
+    "c92a387d2882db431f65-v1",
+    "c92a387d2882db431f65-v2",
+    "c92a387d2882db431f65-v3",
+    "d0afc9296f83fad5b52d-v0",
+    "d0afc9296f83fad5b52d-v1",
+    "d0afc9296f83fad5b52d-v2",
+    "d0afc9296f83fad5b52d-v3",
+    "d7ca171473b12143fdb4-v0",
+    "d7ca171473b12143fdb4-v1",
+    "d7ca171473b12143fdb4-v2",
+    "d7ca171473b12143fdb4-v3",
+    "92aa644c30a82c8729f0-v0",
+    "92aa644c30a82c8729f0-v1",
+    "92aa644c30a82c8729f0-v2",
+    "92aa644c30a82c8729f0-v3",
+    "917941dc4b82780cad3c-v0",
+    "917941dc4b82780cad3c-v1",
+    "917941dc4b82780cad3c-v2",
+    "917941dc4b82780cad3c-v3",
+    "76c5d77420d0adddfa9a-v0",
+    "76c5d77420d0adddfa9a-v1",
+    "76c5d77420d0adddfa9a-v2",
+    "76c5d77420d0adddfa9a-v3",
+    "26888c09438ca17387f8-v0",
+    "26888c09438ca17387f8-v1",
+    "26888c09438ca17387f8-v2",
+    "26888c09438ca17387f8-v3",
+    "db50fbd5e0fdb5ce3379-v0",
+    "db50fbd5e0fdb5ce3379-v1",
+    "db50fbd5e0fdb5ce3379-v2",
+    "db50fbd5e0fdb5ce3379-v3",
+    "6a5aef795e625c1fb2a9-v0",
+    "6a5aef795e625c1fb2a9-v1",
+    "6a5aef795e625c1fb2a9-v2",
+    "6a5aef795e625c1fb2a9-v3",
+    "7ff8979556221a260ce0-v0",
+    "7ff8979556221a260ce0-v1",
+    "7ff8979556221a260ce0-v2",
+    "7ff8979556221a260ce0-v3",
+    "b4b0d309012ca95a2c4a-v0",
+    "b4b0d309012ca95a2c4a-v1",
+    "b4b0d309012ca95a2c4a-v2",
+    "b4b0d309012ca95a2c4a-v3",
+    "8d1c41e250d29d3bd13c-v0",
+    "8d1c41e250d29d3bd13c-v1",
+    "8d1c41e250d29d3bd13c-v2",
+    "8d1c41e250d29d3bd13c-v3",
+    "fd8ee32090590934a302-v0",
+    "fd8ee32090590934a302-v1",
+    "fd8ee32090590934a302-v2",
+    "fd8ee32090590934a302-v3",
+    "e94bfdac64dd4fd538e8-v0",
+    "e94bfdac64dd4fd538e8-v1",
+    "e94bfdac64dd4fd538e8-v2",
+    "e94bfdac64dd4fd538e8-v3",
+    "0c08cc218664cf71d7a4-v0",
+    "0c08cc218664cf71d7a4-v1",
+    "0c08cc218664cf71d7a4-v2",
+    "0c08cc218664cf71d7a4-v3",
+    "d0327acf7b451f652464-v0",
+    "d0327acf7b451f652464-v1",
+    "d0327acf7b451f652464-v2",
+    "d0327acf7b451f652464-v3",
+    "67ce375b4b7a7236f8c4-v0",
+    "67ce375b4b7a7236f8c4-v1",
+    "67ce375b4b7a7236f8c4-v2",
+    "67ce375b4b7a7236f8c4-v3",
+    "cfce2cfcf8317763dd44-v0",
+    "cfce2cfcf8317763dd44-v1",
+    "cfce2cfcf8317763dd44-v2",
+    "cfce2cfcf8317763dd44-v3",
+    "7918b36c98ee56019646-v0",
+    "7918b36c98ee56019646-v1",
+    "7918b36c98ee56019646-v2",
+    "7918b36c98ee56019646-v3",
+    "5763f942e73f616782ad-v0",
+    "5763f942e73f616782ad-v1",
+    "5763f942e73f616782ad-v2",
+    "5763f942e73f616782ad-v3",
+    "4ce0b2318a0b65abd68b-v0",
+    "4ce0b2318a0b65abd68b-v1",
+    "4ce0b2318a0b65abd68b-v2",
+    "4ce0b2318a0b65abd68b-v3",
+    "9f0d8b1ae1f1330141d3-v0",
+    "9f0d8b1ae1f1330141d3-v1",
+    "9f0d8b1ae1f1330141d3-v2",
+    "9f0d8b1ae1f1330141d3-v3",
+    "bb8116ecf2320e27daa5-v0",
+    "bb8116ecf2320e27daa5-v1",
+    "bb8116ecf2320e27daa5-v2",
+    "bb8116ecf2320e27daa5-v3",
+    "03c02d7470d5a1fab0e5-v0",
+    "03c02d7470d5a1fab0e5-v1",
+    "03c02d7470d5a1fab0e5-v2",
+    "03c02d7470d5a1fab0e5-v3",
+    "8a77346173b288a90775-v0",
+    "8a77346173b288a90775-v1",
+    "8a77346173b288a90775-v2",
+    "8a77346173b288a90775-v3",
+    "d3c48fb9f017b94b8508-v0",
+    "d3c48fb9f017b94b8508-v1",
+    "d3c48fb9f017b94b8508-v2",
+    "d3c48fb9f017b94b8508-v3",
+    "32cd7da01c4e542ad376-v0",
+    "32cd7da01c4e542ad376-v1",
+    "32cd7da01c4e542ad376-v2",
+    "32cd7da01c4e542ad376-v3",
+    "5116a7c03161b9a8e33e-v0",
+    "5116a7c03161b9a8e33e-v1",
+    "5116a7c03161b9a8e33e-v2",
+    "5116a7c03161b9a8e33e-v3",
+    "3707f2f19bd7ee197669-v0",
+    "3707f2f19bd7ee197669-v1",
+    "3707f2f19bd7ee197669-v2",
+    "3707f2f19bd7ee197669-v3",
+    "e6c8b873036ef3cff206-v0",
+    "e6c8b873036ef3cff206-v1",
+    "e6c8b873036ef3cff206-v2",
+    "e6c8b873036ef3cff206-v3",
+    "55c986292a19ad365d72-v0",
+    "55c986292a19ad365d72-v1",
+    "55c986292a19ad365d72-v2",
+    "55c986292a19ad365d72-v3",
+    "032a127f294a9ccc4046-v0",
+    "032a127f294a9ccc4046-v1",
+    "032a127f294a9ccc4046-v2",
+    "032a127f294a9ccc4046-v3",
+    "2d03806613e95eda2c5d-v0",
+    "2d03806613e95eda2c5d-v1",
+    "2d03806613e95eda2c5d-v2",
+    "2d03806613e95eda2c5d-v3",
+    "1e0b5a590c8169b226d1-v0",
+    "1e0b5a590c8169b226d1-v1",
+    "1e0b5a590c8169b226d1-v2",
+    "1e0b5a590c8169b226d1-v3",
+    "899bb8c3073520a2d786-v0",
+    "899bb8c3073520a2d786-v1",
+    "899bb8c3073520a2d786-v2",
+    "899bb8c3073520a2d786-v3",
+    "45a047f3468ca0abbfd6-v0",
+    "45a047f3468ca0abbfd6-v1",
+    "45a047f3468ca0abbfd6-v2",
+    "45a047f3468ca0abbfd6-v3",
+    "cce70d8f1cf989863f09-v0",
+    "cce70d8f1cf989863f09-v1",
+    "cce70d8f1cf989863f09-v2",
+    "cce70d8f1cf989863f09-v3",
+    "02214738c17052c83f0d-v0",
+    "02214738c17052c83f0d-v1",
+    "02214738c17052c83f0d-v2",
+    "02214738c17052c83f0d-v3",
+    "093fad17e65696cf48e2-v0",
+    "093fad17e65696cf48e2-v1",
+    "093fad17e65696cf48e2-v2",
+    "093fad17e65696cf48e2-v3",
+    "60942606bb00f6896d04-v0",
+    "60942606bb00f6896d04-v1",
+    "60942606bb00f6896d04-v2",
+    "60942606bb00f6896d04-v3",
+    "53a4c2377d09fa43c136-v0",
+    "53a4c2377d09fa43c136-v1",
+    "53a4c2377d09fa43c136-v2",
+    "53a4c2377d09fa43c136-v3",
+    "38822653da041f7b0bcc-v0",
+    "38822653da041f7b0bcc-v1",
+    "38822653da041f7b0bcc-v2",
+    "38822653da041f7b0bcc-v3",
+    "83331db654f927bba7db-v0",
+    "83331db654f927bba7db-v1",
+    "83331db654f927bba7db-v2",
+    "83331db654f927bba7db-v3",
+    "0d6b8870f9f8fbecd06a-v0",
+    "0d6b8870f9f8fbecd06a-v1",
+    "0d6b8870f9f8fbecd06a-v2",
+    "0d6b8870f9f8fbecd06a-v3",
+    "efd33140ce57a557e922-v0",
+    "efd33140ce57a557e922-v1",
+    "efd33140ce57a557e922-v2",
+    "efd33140ce57a557e922-v3",
+    "e6c9829ce1dcf43fd8e6-v0",
+    "e6c9829ce1dcf43fd8e6-v1",
+    "e6c9829ce1dcf43fd8e6-v2",
+    "e6c9829ce1dcf43fd8e6-v3",
+    "d6180603ae0451879c14-v0",
+    "d6180603ae0451879c14-v1",
+    "d6180603ae0451879c14-v2",
+    "d6180603ae0451879c14-v3",
+    "08742aac51091be0a9c6-v0",
+    "08742aac51091be0a9c6-v1",
+    "08742aac51091be0a9c6-v2",
+    "08742aac51091be0a9c6-v3",
+    "170540b624f3109b3fd0-v0",
+    "170540b624f3109b3fd0-v1",
+    "170540b624f3109b3fd0-v2",
+    "170540b624f3109b3fd0-v3",
+    "ef66425f8d0214644d8d-v0",
+    "ef66425f8d0214644d8d-v1",
+    "ef66425f8d0214644d8d-v2",
+    "ef66425f8d0214644d8d-v3",
+    "a764131510993a8e2ca2-v0",
+    "a764131510993a8e2ca2-v1",
+    "a764131510993a8e2ca2-v2",
+    "a764131510993a8e2ca2-v3",
+    "1555d7f97f52214e121d-v0",
+    "1555d7f97f52214e121d-v1",
+    "1555d7f97f52214e121d-v2",
+    "1555d7f97f52214e121d-v3",
+    "57833fdb2b7db066c37f-v0",
+    "57833fdb2b7db066c37f-v1",
+    "57833fdb2b7db066c37f-v2",
+    "57833fdb2b7db066c37f-v3",
+    "f8834e3399d85f499155-v0",
+    "f8834e3399d85f499155-v1",
+    "f8834e3399d85f499155-v2",
+    "f8834e3399d85f499155-v3",
+    "0ab36e04e97c91000199-v0",
+    "0ab36e04e97c91000199-v1",
+    "0ab36e04e97c91000199-v2",
+    "0ab36e04e97c91000199-v3",
+    "18424f2430fb7a69602d-v0",
+    "18424f2430fb7a69602d-v1",
+    "18424f2430fb7a69602d-v2",
+    "18424f2430fb7a69602d-v3",
+    "178675742d6486f51bc4-v0",
+    "178675742d6486f51bc4-v1",
+    "178675742d6486f51bc4-v2",
+    "178675742d6486f51bc4-v3",
+    "01c0b332d3789803ba65-v0",
+    "01c0b332d3789803ba65-v1",
+    "01c0b332d3789803ba65-v2",
+    "01c0b332d3789803ba65-v3"
+  ],
+  "val_ids": [
+    "490d93c0b080175b8a66-v0",
+    "490d93c0b080175b8a66-v1",
+    "490d93c0b080175b8a66-v2",
+    "490d93c0b080175b8a66-v3",
+    "eb03c5c9f2711fe9b9ec-v0",
+    "eb03c5c9f2711fe9b9ec-v1",
+    "eb03c5c9f2711fe9b9ec-v2",
+    "eb03c5c9f2711fe9b9ec-v3",
+    "c42cdd597515d930619f-v0",
+    "c42cdd597515d930619f-v1",
+    "c42cdd597515d930619f-v2",
+    "c42cdd597515d930619f-v3",
+    "9834d7b46708c5f3141a-v0",
+    "9834d7b46708c5f3141a-v1",
+    "9834d7b46708c5f3141a-v2",
+    "9834d7b46708c5f3141a-v3",
+    "4a1770b349d1696431dd-v0",
+    "4a1770b349d1696431dd-v1",
+    "4a1770b349d1696431dd-v2",
+    "4a1770b349d1696431dd-v3",
+    "a79a0ab110691491fed2-v0",
+    "a79a0ab110691491fed2-v1",
+    "a79a0ab110691491fed2-v2",
+    "a79a0ab110691491fed2-v3",
+    "e29f72f0f7fa3b880741-v0",
+    "e29f72f0f7fa3b880741-v1",
+    "e29f72f0f7fa3b880741-v2",
+    "e29f72f0f7fa3b880741-v3",
+    "a19bf682317a9d72d332-v0",
+    "a19bf682317a9d72d332-v1",
+    "a19bf682317a9d72d332-v2",
+    "a19bf682317a9d72d332-v3",
+    "8cde9d38a1e42442f821-v0",
+    "8cde9d38a1e42442f821-v1",
+    "8cde9d38a1e42442f821-v2",
+    "8cde9d38a1e42442f821-v3",
+    "fe9c7b60406ed4fd1983-v0",
+    "fe9c7b60406ed4fd1983-v1",
+    "fe9c7b60406ed4fd1983-v2",
+    "fe9c7b60406ed4fd1983-v3",
+    "e4dbd8299958bb3b0b9e-v0",
+    "e4dbd8299958bb3b0b9e-v1",
+    "e4dbd8299958bb3b0b9e-v2",
+    "e4dbd8299958bb3b0b9e-v3",
+    "48bbd01188ea983a5b2f-v0",
+    "48bbd01188ea983a5b2f-v1",
+    "48bbd01188ea983a5b2f-v2",
+    "48bbd01188ea983a5b2f-v3",
+    "3228102524c244aa3d59-v0",
+    "3228102524c244aa3d59-v1",
+    "3228102524c244aa3d59-v2",
+    "3228102524c244aa3d59-v3",
+    "5896b3c215ed8167d0cc-v0",
+    "5896b3c215ed8167d0cc-v1",
+    "5896b3c215ed8167d0cc-v2",
+    "5896b3c215ed8167d0cc-v3",
+    "8d36fc4f31a77b9eab9f-v0",
+    "8d36fc4f31a77b9eab9f-v1",
+    "8d36fc4f31a77b9eab9f-v2",
+    "8d36fc4f31a77b9eab9f-v3",
+    "dcdf4504811d49eed613-v0",
+    "dcdf4504811d49eed613-v1",
+    "dcdf4504811d49eed613-v2",
+    "dcdf4504811d49eed613-v3",
+    "f4bebfef2755063c3327-v0",
+    "f4bebfef2755063c3327-v1",
+    "f4bebfef2755063c3327-v2",
+    "f4bebfef2755063c3327-v3",
+    "421edd1b4af56929a114-v0",
+    "421edd1b4af56929a114-v1",
+    "421edd1b4af56929a114-v2",
+    "421edd1b4af56929a114-v3",
+    "0c351b2db97c91e18d91-v0",
+    "0c351b2db97c91e18d91-v1",
+    "0c351b2db97c91e18d91-v2",
+    "0c351b2db97c91e18d91-v3",
+    "178d10126082a9678b0f-v0",
+    "178d10126082a9678b0f-v1",
+    "178d10126082a9678b0f-v2",
+    "178d10126082a9678b0f-v3",
+    "28fd97ba3f683c2a99c5-v0",
+    "28fd97ba3f683c2a99c5-v1",
+    "28fd97ba3f683c2a99c5-v2",
+    "28fd97ba3f683c2a99c5-v3",
+    "226b1903a8c86d5f49a8-v0",
+    "226b1903a8c86d5f49a8-v1",
+    "226b1903a8c86d5f49a8-v2",
+    "226b1903a8c86d5f49a8-v3",
+    "8d343b01a4d96fce0c93-v0",
+    "8d343b01a4d96fce0c93-v1",
+    "8d343b01a4d96fce0c93-v2",
+    "8d343b01a4d96fce0c93-v3",
+    "81b217a8060cb30b40ae-v0",
+    "81b217a8060cb30b40ae-v1",
+    "81b217a8060cb30b40ae-v2",
+    "81b217a8060cb30b40ae-v3",
+    "2fac0c5475e8e927f3f8-v0",
+    "2fac0c5475e8e927f3f8-v1",
+    "2fac0c5475e8e927f3f8-v2",
+    "2fac0c5475e8e927f3f8-v3",
+    "81ad71ac6fd6f8101cec-v0",
+    "81ad71ac6fd6f8101cec-v1",
+    "81ad71ac6fd6f8101cec-v2",
+    "81ad71ac6fd6f8101cec-v3",
+    "0ba4d03f17809d59a303-v0",
+    "0ba4d03f17809d59a303-v1",
+    "0ba4d03f17809d59a303-v2",
+    "0ba4d03f17809d59a303-v3",
+    "33391b3c51b93088937f-v0",
+    "33391b3c51b93088937f-v1",
+    "33391b3c51b93088937f-v2",
+    "33391b3c51b93088937f-v3",
+    "02b0826239e05c2c97d4-v0",
+    "02b0826239e05c2c97d4-v1",
+    "02b0826239e05c2c97d4-v2",
+    "02b0826239e05c2c97d4-v3",
+    "59b5ec716c803703ea5d-v0",
+    "59b5ec716c803703ea5d-v1",
+    "59b5ec716c803703ea5d-v2",
+    "59b5ec716c803703ea5d-v3",
+    "f6b970010bc3833bd256-v0",
+    "f6b970010bc3833bd256-v1",
+    "f6b970010bc3833bd256-v2",
+    "f6b970010bc3833bd256-v3",
+    "3577c750b03d138cb1c3-v0",
+    "3577c750b03d138cb1c3-v1",
+    "3577c750b03d138cb1c3-v2",
+    "3577c750b03d138cb1c3-v3",
+    "1ad605ceb804ef551c30-v0",
+    "1ad605ceb804ef551c30-v1",
+    "1ad605ceb804ef551c30-v2",
+    "1ad605ceb804ef551c30-v3",
+    "90df3e622026c10b2314-v0",
+    "90df3e622026c10b2314-v1",
+    "90df3e622026c10b2314-v2",
+    "90df3e622026c10b2314-v3",
+    "80b7421276b7b7aa42d2-v0",
+    "80b7421276b7b7aa42d2-v1",
+    "80b7421276b7b7aa42d2-v2",
+    "80b7421276b7b7aa42d2-v3",
+    "e892cd1da4e97cbb3156-v0",
+    "e892cd1da4e97cbb3156-v1",
+    "e892cd1da4e97cbb3156-v2",
+    "e892cd1da4e97cbb3156-v3",
+    "08316a144698ca3c94fd-v0",
+    "08316a144698ca3c94fd-v1",
+    "08316a144698ca3c94fd-v2",
+    "08316a144698ca3c94fd-v3",
+    "ca8462cb5c9b32b9a8d5-v0",
+    "ca8462cb5c9b32b9a8d5-v1",
+    "ca8462cb5c9b32b9a8d5-v2",
+    "ca8462cb5c9b32b9a8d5-v3",
+    "89e5abe091880bdda1eb-v0",
+    "89e5abe091880bdda1eb-v1",
+    "89e5abe091880bdda1eb-v2",
+    "89e5abe091880bdda1eb-v3",
+    "de83ba5f5f6e234b2cf5-v0",
+    "de83ba5f5f6e234b2cf5-v1",
+    "de83ba5f5f6e234b2cf5-v2",
+    "de83ba5f5f6e234b2cf5-v3",
+    "8e5b9b5a46d3351bf52c-v0",
+    "8e5b9b5a46d3351bf52c-v1",
+    "8e5b9b5a46d3351bf52c-v2",
+    "8e5b9b5a46d3351bf52c-v3",
+    "60222ffa34fbeaf3487f-v0",
+    "60222ffa34fbeaf3487f-v1",
+    "60222ffa34fbeaf3487f-v2",
+    "60222ffa34fbeaf3487f-v3",
+    "460e87ec477c804638b3-v0",
+    "460e87ec477c804638b3-v1",
+    "460e87ec477c804638b3-v2",
+    "460e87ec477c804638b3-v3",
+    "07275900f72e95c1f69c-v0",
+    "07275900f72e95c1f69c-v1",
+    "07275900f72e95c1f69c-v2",
+    "07275900f72e95c1f69c-v3",
+    "bb5377db3c418476576d-v0",
+    "bb5377db3c418476576d-v1",
+    "bb5377db3c418476576d-v2",
+    "bb5377db3c418476576d-v3"
+  ],
+  "parameters": 306321,
+  "teachers": [
+    "mesh-proxy:allenai/objaverse",
+    "mesh-proxy:scenario-labs/3d-collection"
+  ],
+  "validation": "held-out objects",
+  "manifest_sha256": "47c6cb23929321cfc5b21a16807f6a460d18d0231f11c6afd7136fb4b6bea945",
+  "initialization": {
+    "sha256": "83c065d2a50cf086928542cf8d40dc4416b379e38b9aa61d842dc9106d4b3306",
+    "config": {
+      "grid": 16,
+      "width": 64
+    },
+    "step": 4800,
+    "optimizer": "fresh AdamW; weights-only post-training"
+  },
+  "steps_requested": 8000,
+  "learning_rate": 5e-05,
+  "batch_size": 2,
+  "validation_fraction": 0.2,
+  "baseline_validation": {
+    "occupancy": 0.45328883288635147,
+    "position": 0.0943834915343258,
+    "colour": 0.03328401494266776,
+    "scale": 0.002456185630742564,
+    "rotation": 0.00010184630525853007,
+    "opacity": 0.00022721136727644383,
+    "geometry": 0.0,
+    "loss": 0.6147233684857686,
+    "occupancy_iou": 0.2426499036554661
+  },
+  "base_model": "Lucasgitguy-co/forma3d-tiny",
+  "base_revision": "e80b8d895cc2e405894473abe4ce40b3472eaca7",
+  "training_method": "weights-only continuation; fresh AdamW",
+  "known_v1_assets_excluded": true
+}