docs/ORIENTATION-AND-PUBLICATION.md

Orientation and publication correction — 2026-10-31

Root cause and minimal fix

The unchanged IDOL exporter (idol/gaussian.py, pinned upstream Space 2fd68f6aaa69df7c178503a788ad8deb4c7d3117) maps latent (x,y,z) to PLY (x,-z,y), including quaternion rotation. Latent +Z therefore becomes PLY -Y. Its comment “y-up” does not mean positive Y. Our earlier camera assumed +Y and opened the opposite Z hemisphere. The resulting preview and interactive view were both upside down. Earlier WebGL checks proved visibility, not correct semantic orientation; the user’s axolotl exposed it.

Gradio’s Canvas3DGS.svelte delegates to gsplat 1.2.9. Its default orbit yaw/pitch are .5 radians; position relative to target is proportional to [sin(.5)*cos(.5), -sin(.5), -cos(.5)*cos(.5)], with a negative vertical projection coefficient. The new explicit Three.js camera uses that position direction and up=[0,-1,0], preserving handedness. Sources inspected in the installed Gradio wheel’s source maps; remote guessed GitHub paths returned 404 and were not used as evidence.

Only backend/rendering.py and the default camera in splat-core.ts need changes. Both transparent PNGs and interactive splats use the exact saved camera. PLY positions, covariance/quaternions, colors and bytes are untouched. Scenario’s GLB engine, spatial layout and navigation are untouched. The renderer profile remains the same algorithm; orientation is already explicit in the canonical framing.camera fields. Published historical records retain their own saved camera. The live dataset has no assets.

On startup, a private ready result carrying the old +Y camera is changed to preview_failed. Its owner retains the original PLY download and can rerender on CPU via the existing authenticated preview-retry route. Its old PNG cannot be served or published as a ready result. This does not promise to restore files lost from ephemeral storage.

Label & share

A signed-in contributor can now open Review contribution when public sharing is unavailable. The title, description, controlled category, tags, rights basis, source credits and two explicit consents remain available. The final public-submit action stays disabled, and a visible message explains why on touchscreens. When publication is configured, the entry action is Publish to collection. The server still verifies each write independently; no client control enables publication. Nothing is automatically published.

Live configuration audit: dataset fffiloni/idol-community-assets exists, but DATASET_WRITE_TOKEN, ENABLE_PUBLICATION, DURABLE_STATE_ACK and a private persistent volume are absent. Secrets observed by name only: SESSION_SECRET, TOKEN_ENCRYPTION_KEY, DINO_TKN. No values were read. The model reader must never be reused as the dataset writer.

Operator action for the writer: create a fine-grained token with only read and content-write access to fffiloni/idol-community-assets, with no global permissions, then add it as DATASET_WRITE_TOKEN in the development Space’s Secrets. Do not paste the token in chat. This is an operator secret, never a credential requested from contributors.

Persistence still needs provisioning and restart/concurrency verification before setting PRIVATE_STATE_DIR, DURABLE_STATE_ACK=yes and finally ENABLE_PUBLICATION=1. Hugging Face now recommends attached Storage Buckets; a mount alone does not establish correct SQLite WAL/locking/fsync semantics. The current SQLite journal uses a single instance. Do not point it at a bucket and assert durability without testing, or use periodic unverified copies as a substitute for durable publication reservations/consent/withdrawal records. No storage plan, bucket or broad credential was silently substituted.

References:

• https://huggingface.co/docs/hub/spaces-storage
• https://huggingface.co/docs/hub/security-tokens
• https://github.com/huggingface/hf-mount/issues/103

Verification scope

Local: 85 Python tests, 39 subtests, 12 JavaScript tests, strict TypeScript and production build pass. Tests cover coordinate projection/handedness, off-center framing, old-preview recovery, PLY integrity and server-side publication refusal (anonymous 401, authenticated disabled service 503). Browser/native evidence is recorded separately after the bounded Job. Publication and live contributor OAuth are not certified by API fixtures.

Bounded CPU Job 6ae656cdc78863f9c62f4ae1 generated a real private axolotl via native ZeroGPU in 33.84 seconds, then exercised the corrected production preview renderer on it and the pinned upstream backpack. Visual inspection confirms upright results, matching interactive appearance, and upright exploration. SHA-256 of both PLY files remained unchanged. Real Chromium WebGL2 ran through SwiftShader (software), at 390×844, 820×1000 and 1000×820 with the same canvas surviving resizing; the explorer factory was exercised at desktop width. API transport/auth/catalogue in the browser were fixtures. No real contributor OAuth or public dataset write occurred. Publication form fixtures cover inaccessible-service messaging, review fields, both consents, failed network retry, idempotency key reuse and duplicate links. Detailed results: reports/orientation-publication.json.