Engine 1.2.0: the photographs projected onto the texture; ANTLR licence text

Model card for engine 1.2.0 (photo projection, no new weights), and the BSD-3 licence text of antlr4-python3-runtime 4.9.3, which its dist-info did not carry.

README.md

@@ -15,30 +15,73 @@ base_model_relation: quantized
 
 ![LocalMesh Engine](https://raw.githubusercontent.com/Quentincls/localmesh-engine/main/assets/banner.png)
 
-# LocalMesh Engine, multi-view weights
+# LocalMesh Engine weights
 
 LocalMesh Engine turns one photo, or four sides of the same subject, into a
 textured `.glb`. It runs on an 8 GB NVIDIA card. The code is Apache-2.0 and
 lives on [GitHub](https://github.com/Quentincls/localmesh-engine). The project
 page is [local-mesh.com/localmesh-engine](https://local-mesh.com/localmesh-engine/).
 
-TRELLIS.2 works from a single image. This repository holds the weights of the
-four view path: the three fp8 conversions of the Pixal3D multi-view models,
-and the field network that recovers detail between image tokens. The three
-conversions exist nowhere else. Everything else the engine needs comes from
-upstream repositories and is listed below.
+TRELLIS.2 works from a single image. This engine adds a four view path and,
+since version 1.2, puts the photographs' own pixels on the texture. This
+repository holds every weight the engine needs, except DINOv3 and the cutout
+model, laid out like the folder the engine reads. Most of it is rehosted
+unchanged; the three fp8 conversions of the Pixal3D multi-view models exist
+nowhere else.
+
+## New in engine 1.2: the photographs on the texture
+
+![The photograph, the texture drawn by the model, and the photograph projected onto it: printed text stays readable](https://raw.githubusercontent.com/Quentincls/localmesh-engine/main/assets/photo-projection.webp)
+
+**No new weights.** Engine [v1.2.0](https://github.com/Quentincls/localmesh-engine/releases/tag/v1.2.0)
+reads exactly the files in this repository. A folder downloaded for an earlier
+version works as it is: there is nothing to download again.
+
+The change is in the texture. The texture TRELLIS.2 returns is drawn by the
+model: close to the photograph in colour and shape, wrong in the detail, so
+printed text comes back as glyphs that read as nothing. After texturing, the
+engine now projects the photographs back onto the mesh. Every texel a
+photograph sees squarely takes that photograph's pixel, so a printed label, a
+logo or a fine pattern reads as it does on the photograph. Where no photograph
+sees the surface, underneath or on the back of a single photograph, the drawn
+texture stays, its colour pulled towards the photographed surface next to it.
+The photographs themselves are never retouched.
+
+The cameras are fitted to the images. With four photographs, the engine reuses
+the angles DA3-BASE (`multivue/cameras/`, listed below) measured for the shape;
+when the shape was made without that measurement, on the `max` tier or without
+DA3-BASE, it starts from quarter turns and checks whether the two profiles are
+swapped. With one photograph, it searches the whole turn for the angle that
+matches the silhouette and straightens a tilt of up to 20 degrees; nothing
+under `multivue/` is needed, so the single photo download gets the projection
+too. One elevation is shared by all views, and the mesh is never mirrored to
+fit. Each texel takes the one photograph that sees it most squarely, so
+nothing is averaged into a blur. On a cassette generated from four
+photographs, 59 % of the surface takes a photograph pixel, and its printed
+label reads as it does on the photographs.
+
+Beside `model_<seed>.glb`, the engine writes `model_<seed>.ai.glb`: the same
+mesh with the drawn texture alone, to compare or to fall back on. Expect about
+twice the disk per job. On an RTX 4060 Laptop 8 GB the projection adds 29 to 73
+seconds per job, most of it spent fitting the cameras, and its memory peak,
+3.3 GB, stays below that of the texture stage.
+
+What it cannot do is correct a shape. Where the reconstructed mesh departs from
+the photograph, a correct pixel lands on the wrong surface and that part shows
+twice. For such a subject, `--no-projection` keeps the drawn texture alone. A
+failure of this step never fails the job: the drawn texture is kept, and the
+result says why.
 
 ## What is in this repository
 
-This repository holds **the whole LocalMesh engine**, except one set Meta
-gates. It is laid out exactly like the folder the engine reads, so one command
-places all of it:
+Everything here is laid out exactly like the folder the engine reads, so one
+command places all of it:
 
 | Folder | Size | What it is | Whose |
 |---|---|---|---|
-| `TRELLIS.2-4B/` | 8.1 GB | the single photo path, in fp8 | [visualbruno](https://huggingface.co/visualbruno/TRELLIS.2-4B-FP8), MIT — rehosted unchanged |
-| `microsoft/` | 148 MB | the sparse structure decoder | [Microsoft](https://huggingface.co/microsoft/TRELLIS-image-large), MIT — rehosted unchanged |
-| `multivue/` | 4.8 GB | the four view path | ours, from Pixal3D — see below |
+| `TRELLIS.2-4B/` | 8.1 GB | the single photo path, in fp8 | [visualbruno](https://huggingface.co/visualbruno/TRELLIS.2-4B-FP8), MIT, rehosted unchanged |
+| `microsoft/` | 148 MB | the sparse structure decoder | [Microsoft](https://huggingface.co/microsoft/TRELLIS-image-large), MIT, rehosted unchanged |
+| `multivue/` | 4.8 GB | the four view path | ours, from Pixal3D, see below |
 
 Rehosted so that one `hf download` replaces six. Taking those two from their
 own repositories works exactly as well; nothing here is modified.
@@ -63,11 +106,13 @@ decoder turns its latent into the mesh.
 fills in the detail the token map loses: the token map is sixteen times coarser
 than the photo.
 
-4.28 GB, seven files, plus `multivue/cameras/` — DA3-BASE and the code that
-reads it, 544 MB, Apache-2.0, unchanged. Keep the three `.json` descriptors
-next to their `.safetensors`: the engine builds each flow model on the `meta` device from that
-descriptor, then loads the tensors in place, so the weights are never held
-twice. The descriptors declare `dtype: float8_e4m3fn`.
+4.28 GB, seven files, plus `multivue/cameras/`, 544 MB, rehosted unchanged:
+DA3-BASE and the code that reads it (Apache-2.0), and the three small Python
+packages that code needs, each under its own licence (omegaconf and
+antlr4-python3-runtime BSD-3-Clause, addict MIT). Keep the three `.json`
+descriptors next to their `.safetensors`: the engine builds each flow model on
+the `meta` device from that descriptor, then loads the tensors in place, so the
+weights are never held twice. The descriptors declare `dtype: float8_e4m3fn`.
 
 The four view path serves the `draft`, `standard` and `high` tiers. The
 multi-view weights exist at 512 and 1024 only, so `max` falls back to the
@@ -76,13 +121,20 @@ another name.
 
 ## What is not in this repository
 
+Two sets. The engine needs both.
+
 | Weights | Where | Licence | Note |
 |---|---|---|---|
-| TRELLIS.2-4B, fp8 | https://huggingface.co/visualbruno/TRELLIS.2-4B-FP8 | MIT | 8.1 GB. Texture on both paths, the single photo path, and the shape decoder the four view path ends on. Required either way. |
-| TRELLIS-image-large, structure decoder | https://huggingface.co/microsoft/TRELLIS-image-large | MIT | Two files, `ss_dec_conv3d_16l8_fp16.json` and `.safetensors`. |
 | DINOv3 ViT-L/16 | https://huggingface.co/facebook/dinov3-vitl16-pretrain-lvd1689m | DINOv3 License, Meta | Image encoder, required on both paths. Access is gated and approved by hand, so ask for it first. |
-| BiRefNet_HR | https://huggingface.co/ZhengPeng7/BiRefNet_HR | MIT | Cutout. The engine fetches this one from the Hub on the first generation if the cache is empty, and loads it with `trust_remote_code=True`, so that first run executes code from the Hub. |
-| DA3-BASE | https://huggingface.co/depth-anything/DA3-BASE | Apache-2.0 | `model.safetensors` (541 MB) and `config.json`, plus the `depth_anything_3` source tree beside them: 544 MB in place. Measures the azimuth of each shot and which side each profile shows. The engine runs without it, but it then guesses which side each profile is on, and says so in its result. A wrong guess puts a face at the front and at the back. |
+| BiRefNet_HR | https://huggingface.co/ZhengPeng7/BiRefNet_HR | MIT | Cutout, and the mask that tells the projection which pixels belong to the subject. The engine fetches it from the Hub on the first generation if the cache is empty, and loads it with `trust_remote_code=True`, so that first run executes code from the Hub. |
+
+TRELLIS.2-4B in fp8, the structure decoder and DA3-BASE are in this
+repository, rehosted unchanged. Their own repositories work just as well:
+[visualbruno/TRELLIS.2-4B-FP8](https://huggingface.co/visualbruno/TRELLIS.2-4B-FP8),
+[microsoft/TRELLIS-image-large](https://huggingface.co/microsoft/TRELLIS-image-large),
+[depth-anything/DA3-BASE](https://huggingface.co/depth-anything/DA3-BASE).
+Without DA3-BASE the engine guesses which side each profile is on, and says so
+in its result; a wrong guess puts a face at the front and at the back.
 
 ## Using them
 
@@ -97,9 +149,9 @@ hf download Qtn-Cls/LocalMeshEngine --local-dir "$LOCALMESH_ROOT/models"
 nothing to move afterwards. For the single photo path alone, 8.3 GB, add
 `--exclude "multivue/*"`.
 
-**Then ask Meta for DINOv3**, the one set that is not here and cannot be: it is
+**Then ask Meta for DINOv3**, the one set you have to fetch yourself: it is
 gated, and a human grants access. Nothing generates without it, and approval is
-not instant, so send the request before anything else —
+not instant, so send the request before anything else:
 [facebook/dinov3-vitl16-pretrain-lvd1689m](https://huggingface.co/facebook/dinov3-vitl16-pretrain-lvd1689m).
 
 The layout the engine reads:
@@ -127,6 +179,15 @@ The four view path also needs `natten`. Installation, including the three CUDA
 extensions that are not on PyPI, is written up in `docs/INSTALL.md` in the
 GitHub repository; the four tiers, frozen, are in `docs/RECIPES.md`.
 
+The photographs are projected onto the texture unless you ask otherwise:
+
+```bash
+python -m localmesh_engine photo.png --no-projection --to out/
+```
+
+`--no-projection` keeps the drawn texture alone; `--sans-projection` is the
+same flag under its French name.
+
 ## Results
 
 ![Four views to one .glb](https://raw.githubusercontent.com/Quentincls/localmesh-engine/main/assets/four-views.png)
@@ -146,7 +207,9 @@ shell, traffic light.
 | Standard, `standard` | 6 min 30 to 8 min 30 |
 | Detailed, `high` | 9 min 20 to 13 min |
 
-Texture accounts for about 60 % of that time.
+Texture accounts for about 60 % of that time. These times were measured with
+engine 1.1, before the projection, which adds 51 to 67 seconds with four
+photographs.
 
 ## The conversion
 
@@ -177,6 +240,11 @@ their own source:
   weights: https://huggingface.co/TencentARC/Pixal3D
 - `champ.safetensors` comes from **valeoai/NAF**, Apache-2.0,
   https://github.com/valeoai/NAF
+- `multivue/cameras/` holds **DA3-BASE** and its source, Apache-2.0,
+  https://huggingface.co/depth-anything/DA3-BASE, and under `deps/` three
+  Python packages, unchanged: **omegaconf** 2.3.0 (BSD-3-Clause, Omry Yadan),
+  **antlr4-python3-runtime** 4.9.3 (BSD-3-Clause, The ANTLR Project) and
+  **addict** 2.4.0 (MIT, Mats Julian Olsen)
 
 The engine also builds on:
 
@@ -199,7 +267,7 @@ License Agreement with any redistribution of your own.
   author  = {Colus, Quentin},
   title   = {LocalMesh Engine},
   year    = {2026},
-  version = {1.0.0},
+  version = {1.2.0},
   license = {Apache-2.0},
   url     = {https://github.com/Quentincls/localmesh-engine}
 }

multivue/cameras/deps/antlr4_python3_runtime-4.9.3.dist-info/LICENSE.txt

@@ -0,0 +1,52 @@
+[The "BSD 3-clause license"]
+Copyright (c) 2012-2017 The ANTLR Project. All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions
+are met:
+
+ 1. Redistributions of source code must retain the above copyright
+    notice, this list of conditions and the following disclaimer.
+ 2. Redistributions in binary form must reproduce the above copyright
+    notice, this list of conditions and the following disclaimer in the
+    documentation and/or other materials provided with the distribution.
+ 3. Neither the name of the copyright holder nor the names of its contributors
+    may be used to endorse or promote products derived from this software
+    without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
+IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
+OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
+IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
+INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
+NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
+THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+
+=====
+
+MIT License for codepointat.js from https://git.io/codepointat
+MIT License for fromcodepoint.js from https://git.io/vDW1m
+
+Copyright Mathias Bynens <https://mathiasbynens.be/>
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.