Initial Hi3D v1.0 demo

.gitattributes

@@ -33,3 +33,8 @@ saved_model/**/* filter=lfs diff=lfs merge=lfs -text
 *.zip filter=lfs diff=lfs merge=lfs -text
 *.zst filter=lfs diff=lfs merge=lfs -text
 *tfevents* filter=lfs diff=lfs merge=lfs -text
+examples/typical_building_castle.png filter=lfs diff=lfs merge=lfs -text
+examples/typical_creature_robot_dinosour.png filter=lfs diff=lfs merge=lfs -text
+examples/typical_humanoid_mech.png filter=lfs diff=lfs merge=lfs -text
+examples/typical_misc_phonograph.png filter=lfs diff=lfs merge=lfs -text
+examples/typical_vehicle_excavator.png filter=lfs diff=lfs merge=lfs -text

AUTHORS

@@ -0,0 +1,26 @@
+SPARC3D authors and contributors
+================================
+
+Sparc3D: Sparse Representation and Construction for High-Resolution 3D Shapes
+Modeling — https://arxiv.org/abs/2505.14521
+
+Paper authors
+-------------
+
+  Zhihao Li
+  Yufei Wang
+  Heliang Zheng
+  Yihao Luo
+  Bihan Wen
+
+Component credits
+-----------------
+
+Named here because the credit belongs with the code, not only with the paper.
+
+  Zhihao Li     GPU surface voxelization in sparc3d/ops, originally written as
+                the pytorch-voxelization extension and implemented as Triton
+                kernels for this release.
+
+Third-party code redistributed with this package is credited separately in
+NOTICE and THIRD_PARTY_LICENSES.md.

LICENSE

@@ -0,0 +1,223 @@
+# Hi3D Open License Agreement Version 1.0
+
+| Item | Details |
+| --- | --- |
+| Licensor | OCEANO HK HOLDING LIMITED |
+| Licensed Project | Hi3D V1.0 |
+| Version | Version 1.0 |
+| Date | October 22, 2026 |
+
+
+
+IMPORTANT NOTICE: By downloading, accessing, using, reproducing, modifying, distributing, displaying or otherwise exercising any rights in the Hi3D Materials, you acknowledge that you have read, understood and agreed to this Agreement. If you do not agree to this Agreement, do not use the Hi3D Materials.
+
+# 1 Definitions
+
+For purposes of this Agreement, the following terms have the meanings set out below.
+
+## 1.1 Agreement
+
+"Agreement" means this Hi3D Open License Agreement Version 1.0 issued with the applicable version of the Hi3D Materials, including Schedule 1, Acceptable Use Policy, and Schedule 2, Licensed Asset Schedule.
+
+## 1.2 Licensor
+
+"Licensor," "we," "us" or "our" means OCEANO HK HOLDING LIMITED, solely to the extent that it owns or is authorized to license the relevant rights in the Hi3D Materials.
+
+## 1.3 You
+
+"You" means the individual or legal entity exercising rights under this Agreement. A "legal entity" includes the entity acting hereunder and any entity that controls, is controlled by, or is under common control with it. "Control" means direct or indirect ownership of more than fifty percent of the voting interests, or the power to direct management.
+
+## 1.4 Hi3D Materials
+
+"Hi3D Materials" means the source code, model architecture, model weights and parameters, inference code, documentation and other materials that are owned by or licensable by the Licensor and expressly identified in the specific release listed in Schedule 2 as being subject to this Agreement. An asset is not automatically included in this Agreement merely because it has a similar name or purpose or is stored in the same repository, unless it has actually been released and is listed in Schedule 2.
+
+## 1.5 Excluded Materials
+
+"Excluded Materials" means third-party software, models, weights and their outputs; training, validation and test datasets; sample media, fonts and other third-party assets; first-stage systems or server-side code not listed in Schedule 2; trademarks and brand assets except as expressly permitted under Section 8; and any other items expressly subject to separate terms. Excluded Materials are not licensed under this Agreement. Sample code calling a third-party model does not alter the licensing status of that third-party model or its outputs.
+
+## 1.6 Model Derivative
+
+"Model Derivative" means another machine-learning model created by modifying, fine-tuning, adapting or quantizing all or a substantial part of the Hi3D model weights or parameters, or otherwise based on or incorporating the foregoing. Standalone Outputs, including generated 3D meshes and model files and finished works created by editing, converting or combining such files, do not become Model Derivatives merely because they were generated or post-processed; however, any portion of a finished work that actually contains Hi3D code, weights or parameters remains subject to this Agreement according to its nature.
+
+## 1.7 Output
+
+"Output" means content or information generated by running the Hi3D Materials or a Model Derivative, including generated 3D geometry, meshes and exported 3D files. Any third-party asset actually contained in an Output remains subject to the applicable third-party rights or separate license.
+
+## 1.8 Commercial Product or Service
+
+"Commercial Product or Service" means any product, service or hosted functionality that uses or contains the Hi3D Materials or a Model Derivative and is offered for commercial advantage, monetary consideration, revenue generation or other material commercial benefit.
+
+## 1.9 Related Product or Service
+
+"Related Product or Service" means a product or service that uses or contains the Hi3D Materials or a Model Derivative. Substantially similar services split among different brands, applications, interfaces, domain names or affiliated entities to evade the Scale Threshold must be aggregated.
+
+## 1.10 Monthly Active Users
+
+"Monthly Active Users" or "MAU" means the number of unique natural persons who actively use a Related Product or Service during a calendar month.
+
+## 1.11 First Stage
+
+"First Stage" means coarse-mesh generation that generates the basic three-dimensional shape of an object from a reference image, determines its principal structure and approximate contours, and outputs a coarse mesh for subsequent processing.
+
+## 1.12 Second Stage
+
+"Second Stage" means geometry refinement that takes a reference image and the coarse mesh produced by the First Stage as inputs, progressively refines the three-dimensional shape, and generates higher-resolution three-dimensional geometry and mesh files.
+
+# 2 License Grant
+
+Subject to your continuing compliance with this Agreement, and solely with respect to rights in the Hi3D Materials that the Licensor owns or is authorized to license, the Licensor grants you a worldwide, non-exclusive, royalty-free license to use, reproduce, modify, fine-tune and adapt the Hi3D Materials in source-code, object-code, weight or other applicable form; create Model Derivatives and other derivative works; publicly display and publicly perform them; and distribute, sublicense and sell the Hi3D Materials. You may also deploy the Hi3D Materials on servers, cloud platforms or other computing environments that you control or lawfully use, and provide third parties with hosted services based on the Hi3D Materials through websites, applications, application programming interfaces (APIs), software as a service (SaaS) or other remote-access methods. This license may be transferred only through sublicensing or distribution that complies with this Agreement.
+
+## 2.1 Commercial Use
+
+Commercial use is permitted subject to Sections 5, 6, 7 and 8. No revenue threshold applies separately from Section 5.
+
+## 2.2 Training Other AI Models
+
+To the extent the Licensor has the right to grant such permission, you may use the Hi3D Materials and their Outputs to train, evaluate, improve or develop other artificial-intelligence or machine-learning models, subject to applicable law, third-party rights and Schedule 1. This permission does not extend to coarse models, outputs or other third-party materials generated through third-party models, and does not replace their separate license terms. Another model is a Model Derivative only if it satisfies the definition in Section 1.6.
+
+# 3 Patent License
+
+Subject to your compliance with this Agreement, and solely with respect to patent claims that the Licensor owns or is authorized to license and that are necessarily infringed by implementation of the Hi3D Materials, the Licensor grants you a perpetual, worldwide, non-exclusive, royalty-free patent license to make, have made, use, offer for sale, sell, import and otherwise transfer the Hi3D Materials. A patent license from any other contributor arises only if that contributor has the right to grant it and expressly agrees to provide it under this Agreement.
+
+## 3.1 Patent Litigation
+
+If you institute patent litigation against the Licensor or any contributor alleging that the Hi3D Materials or a contribution directly or contributorily infringes a patent, all patent licenses granted to you under this Agreement for the Hi3D Materials terminate as of the date the claim is filed.
+
+# 4 Distribution and Sublicensing Conditions
+
+You may distribute the Hi3D Materials and Model Derivatives, including as part of a proprietary or closed-source product, only if you comply with all of the following conditions. Merely reproducing, editing, displaying, selling or distributing Outputs that do not contain Hi3D Materials or Model Derivatives is not distribution under this Section, and does not by itself require those Outputs to be accompanied by this Agreement, a NOTICE file or a modification notice.
+
+- Provide each recipient of files containing the Hi3D Materials or a Model Derivative with the full text of this Agreement upon delivery, or a link that provides continuous, free access to the full text of the corresponding version of this Agreement.
+- Retain all applicable copyright, patent and attribution notices contained in the Hi3D Materials.
+- Prominently identify the files, weights or materials that you modified.
+- When distributing files containing the Hi3D Materials or a Model Derivative, include a readable NOTICE file containing the notice specified in Section 8.2 and all applicable original third-party notices and license requirements.
+- Ensure that your terms do not restrict recipients from exercising the rights granted under this Agreement in unmodified portions of the Hi3D Materials, and pass the Acceptable Use Policy downstream as an enforceable condition.
+
+## 4.1 Licensing of Model Derivatives
+
+You may apply different terms, including proprietary terms, to your own modifications and to a Model Derivative as a whole; however, the portions that actually reproduce or embed Hi3D code, weights or parameters remain subject to this Agreement, and the applicable attribution, branding, scale and use conditions continue to apply. A finished 3D work containing only Outputs and not the foregoing Hi3D Materials is not subject to this subsection's conditions for Model Derivatives merely because it was generated using Hi3D.
+
+# 5 Scale Threshold and Separate License
+
+The Scale Threshold is triggered if one or more Related Products or Services exceed 200,000 Monthly Active Users in the most recent complete calendar month or generate monthly revenue of at least USD 1,000,000. Except for the anti-circumvention aggregation rule in Section 1.9, only Related Products or Services are counted.
+
+## 5.1 Application
+
+Within sixty days after first triggering the Scale Threshold, you must notify OCEANO HK HOLDING LIMITED and apply for a separate written license. The application must truthfully disclose the applicant, the affected products and services, the MAU calculation methodology, use cases, deployment regions, security measures and any other information reasonably requested by us.
+
+## 5.2 Transition Period
+
+If you submit a complete, truthful and timely application and remain compliant, you may continue your existing use during the sixty-day application period and while both parties are actively negotiating in good faith; however, without our written consent, you may not materially expand the affected use beyond its scale and scope when the Scale Threshold was first exceeded.
+
+## 5.3 Decision on Separate License
+
+A separate license may include fees, branding, reporting, audit, security, service-level or other commercial terms. We may decide, in our sole discretion, whether to grant or deny a separate license. No separate license is effective unless signed by an authorized representative of OCEANO HK HOLDING LIMITED or otherwise expressly confirmed by it in writing.
+
+## 5.4 Failure to Obtain a License
+
+If you fail to apply within the required period, make a materially false statement in an application, or continue the affected use after written denial or after good-faith negotiations end without agreement, your right to continue above-threshold use terminates. Any continuing above-threshold use is unauthorized and constitutes a material breach.
+
+# 6 Acceptable Use Policy
+
+Your use of the Hi3D Materials and Model Derivatives, and your conduct in generating Outputs with them, must comply with Schedule 1, applicable law and third-party rights. This Agreement does not otherwise restrict the ordinary reproduction, editing, display, sale or distribution of Outputs that have been generated and do not contain Hi3D Materials or Model Derivatives; you remain responsible for complying with applicable law and any third-party rights contained in the Outputs. You may not knowingly assist another person in circumventing restrictions on the use of the Hi3D Materials or Model Derivatives.
+
+## 6.1 Policy Version
+
+The version of Schedule 1 accompanying the Hi3D version you receive applies to that version. We may issue a revised policy for later versions. Material revisions do not apply retroactively to prior versions unless you expressly accept them.
+
+# 7 Commercial Branding Display
+
+Any entity integrating the Hi3D Materials or a Model Derivative into a Commercial Product or Service must display "Powered by Hi3D 1.0" clearly and with reasonable prominence. A product with a user interface must display it in the interface, on an About page or in product acknowledgements. An API, SDK, backend or embedded product without a conventional user interface must display it in primary customer-accessible technical documentation, a service description or a legal notice. Where the display location supports a clickable link, the text must link to the official Hi3D website listed in Schedule 2; if a link cannot be provided, the official website address must be stated in the same location or related documentation. Merely obtaining or using a generated 3D Output file does not, by itself, create the branding-display obligation under this Section.
+
+You may use the Licensor's commercial marks only to comply with the branding-display obligation under this Section. This permission may be revoked at any time and does not transfer any rights or constitute the Licensor's endorsement of you or any related product or service. The Licensor may require you in writing to cease using or remove the relevant marks, and you must do so within five (5) business days after receiving the notice. Once the marks have been removed, you will no longer be subject to the corresponding branding-display obligation.
+
+## 7.1 No Endorsement
+
+Unless we expressly agree in writing, you may not state or imply that your product, service, Model Derivative or Output was created, certified, endorsed or supported by OCEANO HK HOLDING LIMITED, or is an official Hi3D product.
+
+# 8 Trademarks and Notices
+
+Except for the limited license below, this Agreement grants no right to use the names, logos, trade dress, domain names or trademarks of OCEANO HK HOLDING LIMITED, Hi3D or their affiliates. Reasonable descriptive use to identify the source of the Hi3D Materials is permitted.
+
+## 8.1 Limited Mark License
+
+While you remain in compliance with this Agreement, we grant you a limited, non-exclusive, non-transferable and non-sublicensable license to use the "Hi3D" word mark only to the extent necessary to comply with Sections 4 and 7. This license terminates when your right to use the relevant Hi3D Materials terminates under Section 14. It does not include use of any logo or any use that implies endorsement, sponsorship or official status. All goodwill belongs to the applicable trademark owner.
+
+## 8.2 Required Notice
+
+The NOTICE file must state: "Hi3D is licensed under the Hi3D Open License Agreement Version 1.0. Copyright © 2026 OCEANO HK HOLDING LIMITED. All rights not expressly granted are reserved. The Hi3D trademarks are owned by OCEANO HK HOLDING LIMITED or its applicable affiliate(s)."
+
+# 9 Outputs
+
+As between you and us, we claim no ownership of Outputs generated by you. So long as an Output itself does not contain Hi3D Materials or a Model Derivative, you and downstream users who obtain that Output may reproduce, edit, display, sell and distribute it without being required, solely because of that use, to display "Powered by Hi3D 1.0," include this Agreement or a NOTICE file, or apply for a scale-based license under Section 5. This Section does not transfer rights and does not guarantee that an Output is copyrightable, original or non-infringing. Any applicable terms governing third-party models, inputs, materials or services must still be observed.
+
+# 10 Third-Party Materials
+
+Third-party software, models, weights and their outputs remain subject to their respective licenses and terms of use, and you are responsible for independently obtaining and complying with the relevant rights. Sample code included with this release may call Hunyuan3D-2mini to generate a first-stage coarse model, but Hi3D does not license that model's software, weights or outputs under this Agreement; the model version, source and license used by the sample must be identified in the release documentation. Other external models loaded for second-stage inference, and their actual versions, must also be listed in the third-party dependency schedule. Unless expressly stated otherwise, this Agreement does not license training data, sample media, fonts, datasets or other Excluded Materials.
+
+# 11 Disclaimer
+
+TO THE MAXIMUM EXTENT PERMITTED BY LAW, THE HI3D MATERIALS, MODEL DERIVATIVES, OUTPUTS AND ALL RELATED RIGHTS ARE PROVIDED "AS IS" AND "AS AVAILABLE," WITHOUT WARRANTIES OF ANY KIND, WHETHER EXPRESS, IMPLIED OR STATUTORY, INCLUDING WARRANTIES OF TITLE, NON-INFRINGEMENT, MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, ACCURACY, SECURITY, RELIABILITY OR UNINTERRUPTED OPERATION. YOU ARE RESPONSIBLE FOR DETERMINING WHETHER YOUR USE IS APPROPRIATE AND LAWFUL.
+
+# 12 Limitation of Liability
+
+TO THE MAXIMUM EXTENT PERMITTED BY LAW, OCEANO HK HOLDING LIMITED, ITS AFFILIATES AND CONTRIBUTORS WILL NOT BE LIABLE FOR ANY INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, PUNITIVE OR CONSEQUENTIAL DAMAGES, OR FOR ANY LOSS OF PROFITS, REVENUE, DATA OR GOODWILL, OR BUSINESS INTERRUPTION, ARISING FROM THIS AGREEMENT OR THE HI3D MATERIALS, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH LOSS. LIABILITY THAT CANNOT LAWFULLY BE EXCLUDED IS NOT EXCLUDED BY THIS SECTION.
+
+# 13 Indemnification
+
+You will, to the applicable extent, defend, indemnify and hold harmless OCEANO HK HOLDING LIMITED, its affiliates, officers, employees and contributors from and against third-party claims, losses, liabilities, damages, judgments, costs and reasonable legal fees arising from your breach of this Agreement; unlawful use; inputs; Outputs; modifications; Model Derivatives; products; services; or distribution. We will promptly notify you of a claim and, at your expense, provide reasonable assistance and permit you to control the defense and settlement; however, without the indemnified party's prior written consent, you may not admit liability on its behalf, impose obligations on it or agree to non-monetary relief against it.
+
+# 14 Term and Termination
+
+This Agreement takes effect when you first access the Hi3D Materials or exercise the relevant rights, and continues until terminated. Upon a material breach, your rights terminate immediately following our written notice. For any other breach, your rights terminate if you fail to cure within thirty days after our written notice. Patent termination under Section 3.1 and scale-based termination under Section 5.4 operate according to their respective terms.
+
+## 14.1 Effect of Termination
+
+Upon termination, you must cease any use no longer authorized under this Agreement and delete any Hi3D model weights and other Hi3D Materials in your possession or control that are required to be deleted. Records required by law and routine backups that cannot be immediately purged must not be used and must be deleted in accordance with the applicable retention period. Termination does not automatically terminate licenses lawfully granted before termination where downstream recipients remain compliant, but you may make no new distributions. Sections 1 and 7 through 16, and accrued rights, survive to the extent applicable.
+
+# 15 Governing Law and Arbitration
+
+This Agreement and any non-contractual obligations arising from it are governed by the laws of the Hong Kong Special Administrative Region, without regard to conflict-of-laws rules. Any dispute arising out of or relating to this Agreement will be finally resolved by arbitration administered by the Hong Kong International Arbitration Centre under the HKIAC Administered Arbitration Rules in force when the Notice of Arbitration is submitted. The seat of arbitration is Hong Kong, the tribunal will consist of one arbitrator, and the language of arbitration is English. Either party may seek urgent interim or injunctive relief from a court of competent jurisdiction.
+
+# 16 General
+
+This Agreement constitutes the entire agreement concerning this public license. To the extent a separate written commercial license expressly addresses a matter and conflicts with this Agreement, the commercial license controls. If any provision is unenforceable, it will be adjusted only to the minimum extent necessary and the remainder will remain in effect. Failure to enforce a right is not a waiver. Headings and translations do not affect the meaning of the terms. Except for a permitted transfer with a related product or business where the transferee accepts this Agreement, you may not assign this Agreement.
+
+## 16.1 Non-Retroactive Updates
+
+The license text accompanying the version of the Hi3D Materials you receive continues to apply to that version. We may license later versions under revised terms, but revisions do not retroactively alter rights already granted for earlier versions.
+
+## 16.2 Contact
+
+Applications for scale-based licenses and legal notices must be submitted using the contact details published on the official Hi3D release page, or sent to another address formally designated by OCEANO HK HOLDING LIMITED.
+
+# Schedule 1  Acceptable Use Policy
+
+You may not use the Hi3D Materials or Model Derivatives for any of the following activities, or generate or disseminate the prohibited content listed below through such use. This Schedule does not impose model-use obligations on a person merely because that person obtains or ordinarily uses a generated 3D finished work that does not contain Hi3D Materials or a Model Derivative; subsequent use of such a finished work remains subject to applicable law and third-party rights.
+
+- Violate applicable law, sanctions, export controls, court orders or binding regulatory requirements;
+- Infringe or misappropriate copyright, patent rights, trademark rights, trade secrets, privacy, data protection, publicity rights, image rights or other rights;
+- Exploit, sexualize, groom or traffic minors, or otherwise harm minors;
+- Create, distribute or facilitate malware, ransomware, unauthorized access, credential theft, destructive code or material network abuse;
+- Deceptively impersonate another person, commit fraud, manipulate identity, or generate deceptive synthetic media without disclosure where disclosure is required by law;
+- Intentionally facilitate violence, terrorism, self-harm, unlawful discrimination, stalking, harassment or targeted abuse;
+- Unlawfully collect, infer, disclose or use personal or sensitive information, or undertake any of those activities for the purpose of harming another person;
+- Circumvent technical safeguards or access controls in the Hi3D Materials, except for authorized good-faith security research conducted with appropriate safeguards;
+- Make fully automated decisions in healthcare, employment, credit, housing, education, insurance, law enforcement or essential services that have legal or similarly significant effects, without legally required human oversight, testing, notice and appeal mechanisms; or
+- Falsely represent a Model Derivative or product as an official Hi3D version or as endorsed by OCEANO HK HOLDING LIMITED.
+
+This Policy does not prohibit lawful research, testing, auditing, red-teaming or development conducted with reasonable safeguards and not deployed for a prohibited purpose.
+
+# Schedule 2  Licensed Asset Schedule
+
+This Schedule identifies the assets in this release that are subject to the Hi3D Open License Agreement Version 1.0. The second-stage inference code, documentation and configuration listed below as "Included," together with the eight second-stage model files identified below for distribution under the name Hi3D v1.0 in the Hugging Face model repository at https://huggingface.co/hi3d-official/Hi3Dv1.0, are included under this Agreement to the extent the Licensor owns or is authorized to license them. Inclusion is not affected by the code and weights being stored separately on GitHub and Hugging Face. No third-party model, external dependency, unreleased first-stage material or file listed as "Excluded" is licensed under this Agreement.
+
+| Item | Details |
+| --- | --- |
+| Code Release (Basis of Included Scope) | The Hi3D v1.0 source release at https://github.com/hi3d-official/Hi3Dv1.0 containing this Agreement. The included code, documentation and configuration are identified by the paths below. This Schedule applies to the files accompanying this version of the Agreement, not automatically to later repository versions. |
+| Second-Stage Inference Code and Architecture (Included) | Under sparc3d/: models/, nn/, ops/, pipelines/, schedulers/, sparcubes/, structures/, utils/ and package initialization files; demo/refine_mesh.py, demo/image_to_mesh.py and demo/coarse_stage.py. Coverage is limited to implementations and modifications that the Licensor is authorized to license. coarse_stage.py is sample adapter code that calls an external Hunyuan model and does not include the Hunyuan code or weights. |
+| Second-Stage Model Weights and Configuration (Included) | The following eight Hi3D v1.0 files are included under this Agreement at paths relative to the root of the Hugging Face model repository: model_index.json; scheduler/scheduler_config.json; transformer_512/config.json; transformer_512/model.safetensors (3,675,679,280 bytes); transformer_1024/config.json; transformer_1024/model.safetensors (3,675,679,280 bytes); vae/config.json; and vae/model.safetensors (376,629,712 bytes). transformer_1024/model.safetensors is used for both the 1024³ and 1536³ settings; there is no separate transformer_1536 weight in this release. The designated release location for these files is https://huggingface.co/hi3d-official/Hi3Dv1.0. This item excludes all other files in that repository and also excludes external models and weights such as Hunyuan3D-2mini, DINOv2 and CLIP. |
+| Documentation and Configuration (Included to the Extent Licensable) | README.md, README.zh-CN.md, docs/installation.md, docs/pipeline.md and docs/reproduction.md, together with content in pyproject.toml, MANIFEST.in, docker/Dockerfile and docker/constraints.txt that the Licensor is authorized to license. Original notices in AUTHORS, NOTICE, THIRD_PARTY_LICENSES.md and third-party license files must be preserved unchanged. |
+| Sample Media (Excluded) | assets/example.png, assets/framework.png, assets/global-comparison-1.jpg, assets/global-comparison-2.jpg and assets/local-detail-comparison.jpg are excluded. Their presence in this release does not grant any license to use them under this Agreement. Any use is subject to the applicable rights and separate permissions. |
+| Unreleased and Third-Party Materials (Excluded) | Unreleased proprietary Hi3D first-stage materials, training code and datasets; original third-party rights in TRELLIS, Pointcept, O-CNN and FlexiCubes; Hunyuan3D-2mini code, weights and outputs called externally by the sample; and the facebook/dinov2-large and openai/clip-vit-large-patch14 weights separately obtained at runtime are not sublicensed under this Hi3D Agreement. Original third-party notices and their respective terms continue to apply. |
+| Official Hi3D Websites | The link target for "Powered by Hi3D 1.0" under Section 7 is http://hi3d.ai/. The China website is https://www.hi3d.cn/. |

NOTICE

@@ -0,0 +1,49 @@
+SPARC3D
+Copyright 2026 The SPARC3D Authors
+
+This product includes software developed by third parties. The following
+components are redistributed under their own licenses, reproduced in full in
+THIRD_PARTY_LICENSES.md:
+
+  * Microsoft TRELLIS (MIT License)
+    Copyright (c) Microsoft Corporation.
+    https://github.com/microsoft/TRELLIS
+
+  * Pointcept / Point Transformer V3 (MIT License)
+    Copyright (c) 2023 Pointcept
+    https://github.com/Pointcept/Pointcept
+
+  * O-CNN, ocnn-pytorch (MIT License)
+    Copyright (c) 2022 Peng-Shuai Wang <wangps@hotmail.com>
+    https://github.com/octree-nn/ocnn-pytorch
+
+  * NVIDIA FlexiCubes (Apache License 2.0)
+    Copyright (c) 2025 NVIDIA CORPORATION & AFFILIATES
+    https://github.com/nv-tlabs/FlexiCubes
+    License also included at sparc3d/ops/flexicubes/LICENSE.txt
+
+GPU surface voxelization in sparc3d/ops descends from the PyTorch extension
+written by Zhihao Li; see AUTHORS.
+
+
+Hi3D v1.0
+---------
+Hi3D v1.0 includes the SPARC3D inference implementation. Original copyright,
+attribution, license texts, and per-file modification notices are retained.
+The Python package and API names are sparc3d / Sparc3DPipeline.
+
+Hunyuan3D is referenced only by an optional coarse-mesh example adapter. Tencent's
+Hunyuan3D implementation and weights are not bundled with or relicensed by this
+distribution. External image encoders and any separately obtained model weights
+retain their own terms. See THIRD_PARTY_LICENSES.md for the source and model
+license index.
+
+
+Hi3D Open License Agreement Version 1.0 notice
+--------------------------------------------
+The following notice applies to the Hi3D Materials identified in Schedule 2 of
+LICENSE, only to the extent OCEANO HK HOLDING LIMITED owns or is authorized to
+license them. It does not replace the original third-party notices above or
+extend the Agreement to Excluded Materials. See THIRD_PARTY_LICENSES.md.
+
+Hi3D is licensed under the Hi3D Open License Agreement Version 1.0. Copyright © 2026 OCEANO HK HOLDING LIMITED. All rights not expressly granted are reserved. The Hi3D trademarks are owned by OCEANO HK HOLDING LIMITED or its applicable affiliate(s).

README.md

@@ -1,13 +1,34 @@
 ---
-title: Hi3d Official Hi3dv1 0
-emoji: 💻
-colorFrom: pink
-colorTo: blue
+title: Hi3D v1.0
+emoji: 🗿
+colorFrom: gray
+colorTo: purple
 sdk: gradio
 sdk_version: 6.30.0
-python_version: '3.12'
 app_file: app.py
-pinned: false
+python_version: "3.10"
+short_description: Image to high-res 3D mesh with Hi3D v1.0 refinement
+startup_duration_timeout: 1h
+license: other
+license_name: hi3d-open-license-agreement-1.0
+license_link: LICENSE
+models:
+  - hi3d-official/Hi3Dv1.0
+  - tencent/Hunyuan3D-2mini
+  - facebook/dinov2-large
+  - openai/clip-vit-large-patch14
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# Hi3D v1.0 demo
+
+Image → coarse mesh ([Hunyuan3D-2mini-Turbo](https://huggingface.co/tencent/Hunyuan3D-2mini), or upload your own) →
+high-resolution geometry refinement with [hi3d-official/Hi3Dv1.0](https://huggingface.co/hi3d-official/Hi3Dv1.0).
+
+*Powered by Hi3D 1.0* — <http://hi3d.ai/>
+
+- The `sparc3d/` package is the official inference code from <https://github.com/hi3d-official/Hi3Dv1.0>
+  (Hi3D Open License Agreement 1.0, plus retained Apache-2.0/MIT terms — see `LICENSE`, `NOTICE`,
+  `THIRD_PARTY_LICENSES.md`, `AUTHORS`). One patch: sparse convolutions use spconv's Native algorithm
+  (`SPCONV_ALGO=native`) so they run on ZeroGPU's Blackwell GPUs.
+- Hunyuan3D-2mini is a third-party model under the Tencent Hunyuan Community License.
+- Example images come from [microsoft/TRELLIS](https://github.com/microsoft/TRELLIS) (MIT License, © Microsoft Corporation).

THIRD_PARTY_LICENSES.md

@@ -0,0 +1,474 @@
+# Third-party licenses
+
+This license index adapts the SPARC3D third-party notices for Hi3D v1.0. The
+original license texts and attributions are retained, with additional references
+for separately obtained models and optional examples.
+
+The original SPARC3D license is retained in [Original Apache license](#original-apache-license).
+Hi3D-owned or otherwise licensable materials identified in Schedule 2 are governed
+by the Hi3D Agreement in [LICENSE](LICENSE). See [License scope](#license-scope)
+for the component boundaries; the new Agreement does not replace original
+third-party licenses or previously granted rights.
+
+Parts of this package are derived from other open-source projects. Each is listed
+below with the files it covers and the full text of its license, as those licenses
+require. Every file named here also carries a provenance header pointing back to
+this document.
+
+| Upstream | License | Covers |
+| --- | --- | --- |
+| [Microsoft TRELLIS](https://github.com/microsoft/TRELLIS) | MIT | the sparse transformer and its building blocks |
+| [Pointcept / Point Transformer V3](https://github.com/Pointcept/Pointcept) | MIT | the `Point` structure and the sparse PTv3 decoder |
+| [O-CNN (ocnn-pytorch)](https://github.com/octree-nn/ocnn-pytorch) | MIT | Z-order (Morton) encoding |
+| [NVIDIA FlexiCubes](https://github.com/nv-tlabs/FlexiCubes) | Apache-2.0 | dual-marching-cubes surface extraction |
+
+---
+
+## License scope
+
+This index explains the component boundaries in Schedule 2 of the
+[Hi3D Open License Agreement Version 1.0](LICENSE). It does not amend the
+Agreement or grant additional rights. The Agreement and each applicable
+third-party license govern their respective materials.
+
+| Component | Applicable terms |
+| --- | --- |
+| Second-stage implementation and modifications in `sparc3d/`, including package initialization | The Hi3D Agreement applies only to content OCEANO HK HOLDING LIMITED owns or is authorized to license; original third-party rights in the same files remain under their original terms |
+| `demo/refine_mesh.py`, `demo/image_to_mesh.py`, `demo/coarse_stage.py` | The Hi3D Agreement applies to licensable example code; Hunyuan's separate implementation, weights and outputs are excluded |
+| The README, documentation and configuration paths listed in Schedule 2 | The Hi3D Agreement applies to licensable content; original notices and third-party terms remain in effect |
+| The eight refinement artifacts listed in Schedule 2 | Distributed separately from the source code and Python packages under the Hi3D Agreement; other files or versions are not included merely by sharing a repository |
+| Original SPARC3D, TRELLIS, Pointcept, O-CNN and FlexiCubes rights | Retained Apache-2.0 or MIT terms, as detailed in this file and the original source headers |
+| Hunyuan3D-2mini, DINOv2, CLIP and other external dependencies | Their own upstream licenses; not relicensed by Hi3D |
+| The five files listed as Sample Media in Schedule 2 | Excluded from the Hi3D Agreement; their presence or display does not grant reuse rights |
+| Unreleased first-stage materials, training code, datasets, and brand assets | Excluded, subject to the limited trademark permissions expressly granted in the Agreement |
+
+`LicenseRef-Hi3D-1.0` denotes the custom Agreement in [LICENSE](LICENSE), not a
+blanket license for every file. Previously granted rights under applicable
+Apache-2.0 or MIT licenses are not withdrawn or replaced by the Hi3D Agreement.
+
+The source archive contains media expressly excluded by Schedule 2. Therefore
+its package metadata does not assert a single SPDX license expression for the
+whole archive. The complete applicable agreements and notices are included with
+the Python distributions.
+
+---
+
+## Microsoft TRELLIS
+
+Covers:
+
+- `sparc3d/models/transformers/sparc3d_transformer.py`
+- `sparc3d/nn/norm.py`
+- `sparc3d/nn/rope.py`
+- `sparc3d/nn/utils.py`
+- `sparc3d/nn/sparse/basic.py`
+- `sparc3d/nn/sparse/conv.py`
+- `sparc3d/nn/sparse/linear.py`
+- `sparc3d/nn/sparse/nonlinearity.py`
+- `sparc3d/nn/sparse/spatial.py`
+- `sparc3d/nn/sparse/attention/full_attn.py`
+- `sparc3d/nn/sparse/attention/modules.py`
+- `sparc3d/nn/sparse/transformer/blocks.py`
+- `sparc3d/nn/sparse/transformer/modulated.py`
+
+Each of these files states the specific SPARC3D modification in its header. In
+general the training paths, the alternative attention backends, and the dense
+variants were removed, leaving the released inference architecture.
+
+```
+MIT License
+
+Copyright (c) Microsoft Corporation.
+
+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
+```
+
+---
+
+## Pointcept / Point Transformer V3
+
+Point Transformer V3 (Xiaoyang Wu et al.) is released as part of Pointcept.
+
+Covers:
+
+- `sparc3d/models/autoencoders/blocks.py`
+- `sparc3d/models/autoencoders/ptv3.py`
+- `sparc3d/structures/point.py`
+- `sparc3d/structures/point_modules.py`
+- `sparc3d/utils/misc.py`
+- `sparc3d/utils/precision.py`
+- `sparc3d/utils/serialization/default.py`
+
+The decoder half was specialized for the sparse mesh autoencoder; the encoder,
+the training paths, and the Hilbert serialization order were removed.
+
+```
+MIT License
+
+Copyright (c) 2023 Pointcept
+
+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.
+```
+
+---
+
+## O-CNN (ocnn-pytorch)
+
+Covers:
+
+- `sparc3d/utils/serialization/z_order.py`
+
+The Morton decode tables and the batch-index field of the key were removed; only
+`xyz2key` encoding is retained.
+
+```
+MIT License
+
+Copyright (c) 2022 Peng-Shuai Wang <wangps@hotmail.com>
+
+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.
+```
+
+---
+
+## NVIDIA FlexiCubes
+
+Covers:
+
+- `sparc3d/ops/flexicubes/`
+
+FlexiCubes retains its Apache-2.0 license. Its copy of the
+license ships in the package at `sparc3d/ops/flexicubes/LICENSE.txt`, satisfying
+Apache-2.0 section 4(a); the NVIDIA copyright notices are retained in the source
+files, satisfying 4(c); and `sparc3d/ops/flexicubes/flexicubes.py` carries a
+header enumerating every SPARC3D modification, satisfying 4(b). Upstream ships no
+`NOTICE` file, so 4(d) does not apply.
+
+The vendored copy is inference-only: the tetrahedral output, the learned
+interpolation weights, the developability regularizer, and the gradient hooks
+were removed.
+
+
+---
+
+## External models and optional examples
+
+This section indexes components obtained separately at runtime or by the user.
+It does not add their code or weights to this distribution, grant a license to
+them, or replace their upstream terms. Neither the Hi3D Agreement nor a retained
+source-code license automatically applies to external model weights or
+third-party outputs.
+
+### Required external image encoders
+
+The default image conditioner loads the following models separately. Neither is
+included in the Hi3D refinement checkpoint or in this source tree.
+
+| Component | Role | Official model source | Upstream license reference |
+| --- | --- | --- | --- |
+| DINOv2-large | Spatial image features | [facebook/dinov2-large](https://huggingface.co/facebook/dinov2-large) | [Apache-2.0, DINOv2 LICENSE](https://github.com/facebookresearch/dinov2/blob/main/LICENSE) |
+| CLIP ViT-L/14 | Global image conditioning | [openai/clip-vit-large-patch14](https://huggingface.co/openai/clip-vit-large-patch14) | [MIT, CLIP LICENSE](https://github.com/openai/CLIP/blob/main/LICENSE) |
+
+Consult each model's own model card and the terms supplied with the version you
+obtain. Background-removal models used by the optional `rembg` integration are
+also obtained separately and retain their own terms.
+
+### Optional Hunyuan3D coarse-mesh example
+
+`demo/coarse_stage.py` is a Hi3D / SPARC3D example adapter. It imports
+`hy3dgen.shapegen.Hunyuan3DDiTFlowMatchingPipeline` only when that example is used.
+Its default model is `tencent/Hunyuan3D-2mini`, subfolder
+`hunyuan3d-dit-v2-mini-turbo`.
+
+**Hunyuan3D is only an optional example of coarse-mesh generation.** It is not a
+mandatory dependency of the Hi3D refinement library or a required product
+integration. `demo/refine_mesh.py` and the core `sparc3d` package accept a supplied
+coarse mesh without using Hunyuan3D. Other suitable coarse-mesh generators can be
+used instead. Installing the `[inference]` or `[demo]` extras does not install
+Hunyuan3D.
+
+**Tencent's Hunyuan3D implementation and pretrained weights are third-party
+releases, not open-source content released by Hi3D.** They are not bundled with
+this repository and are not relicensed under the Hi3D Agreement or any
+retained source-code license. Users who
+choose this example obtain them separately and comply with their upstream terms.
+
+| Component used by the example | Official source | Applicable upstream agreement |
+| --- | --- | --- |
+| Hunyuan3D-2 implementation (`hy3dgen`) | [Tencent-Hunyuan/Hunyuan3D-2](https://github.com/Tencent-Hunyuan/Hunyuan3D-2) | [Tencent Hunyuan 3D 2.0 Community License Agreement — source LICENSE](https://github.com/Tencent-Hunyuan/Hunyuan3D-2/blob/main/LICENSE) |
+| Hunyuan3D-2mini weights, mini-turbo variant | [tencent/Hunyuan3D-2mini](https://huggingface.co/tencent/Hunyuan3D-2mini) | [Tencent Hunyuan 3D 2.0 Community License Agreement — model LICENSE](https://huggingface.co/tencent/Hunyuan3D-2mini/blob/main/LICENSE) |
+
+Upstream license terms are version-specific. If you select a different model,
+subfolder, or source version, consult its matching license and model card.
+Example-only use does not waive applicable restrictions, attribution,
+redistribution, or hosted-service obligations in those agreements.
+
+### Hi3D refinement weights
+
+The eight Hi3D refinement artifacts identified and released under Schedule 2
+are governed by the Hi3D Agreement in [LICENSE](LICENSE). They are distributed
+separately from this source repository; see [License scope](#license-scope).
+Other model files are not covered merely because they share the repository or
+use a similar name.
+
+
+---
+
+## Original Apache license
+
+The following is the original SPARC3D Apache-2.0 text, retained without changes.
+It continues to govern the materials and rights to which it originally applied;
+the Hi3D Agreement does not revoke those grants.
+
+```text
+
+                                 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 2026 The SPARC3D Authors
+
+   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.
+```

app.py

@@ -0,0 +1,240 @@
+import os
+
+os.environ.setdefault("SPCONV_ALGO", "native")
+os.environ.setdefault("PYTORCH_CUDA_ALLOC_CONF", "expandable_segments:True")
+
+import spaces  # noqa: E402  (must precede torch)
+
+import random  # noqa: E402
+import tempfile  # noqa: E402
+import time  # noqa: E402
+
+import gradio as gr  # noqa: E402
+import numpy as np  # noqa: E402
+import torch  # noqa: E402
+import trimesh  # noqa: E402
+from PIL import Image  # noqa: E402
+
+from sparc3d import Sparc3DPipeline  # noqa: E402
+
+MODEL_ID = "hi3d-official/Hi3Dv1.0"
+COARSE_REPO = "tencent/Hunyuan3D-2mini"
+COARSE_SUBFOLDER = "hunyuan3d-dit-v2-mini-turbo"
+COARSE_STEPS = 30  # matches demo/coarse_stage.py
+COARSE_OCTREE_RESOLUTION = 256  # matches demo/coarse_stage.py
+MAX_SEED = 2**31 - 1
+
+# ---------------------------------------------------------------- models
+print("Loading Hi3D v1.0 refinement pipeline...")
+pipe = Sparc3DPipeline.from_pretrained(MODEL_ID)
+_ = pipe.transformer_1024  # materialize the deferred high-res transformer now
+pipe.to("cuda")
+
+print("Loading Hunyuan3D-2mini (turbo) coarse generator...")
+from hy3dgen.shapegen import Hunyuan3DDiTFlowMatchingPipeline  # noqa: E402
+
+coarse_pipe = Hunyuan3DDiTFlowMatchingPipeline.from_pretrained(
+    COARSE_REPO,
+    subfolder=COARSE_SUBFOLDER,
+    use_safetensors=True,
+    device="cuda",
+)
+
+print("Loading background remover...")
+from rembg import new_session, remove  # noqa: E402
+
+rembg_session = new_session()
+print("All models loaded.")
+
+
+# ---------------------------------------------------------------- helpers
+def _has_transparency(image: Image.Image) -> bool:
+    if image.mode not in ("RGBA", "LA") and "transparency" not in image.info:
+        return False
+    alpha = np.asarray(image.convert("RGBA").getchannel("A"))
+    return bool((alpha < 250).any())
+
+
+def _prepare_input(image: Image.Image, remove_background: bool) -> Image.Image:
+    if remove_background and not _has_transparency(image):
+        image = remove(image.convert("RGB"), session=rembg_session, bgcolor=[255, 255, 255, 0])
+    return image.convert("RGBA")
+
+
+def _export(mesh: trimesh.Trimesh, suffix: str = ".glb") -> str:
+    path = tempfile.NamedTemporaryFile(suffix=suffix, delete=False).name
+    mesh.export(path)
+    return path
+
+
+def _duration(image, coarse_mesh=None, resolution=1024, num_inference_steps=25, *args, **kwargs):
+    passes = {512: 1, 1024: 2, 1536: 3}.get(int(resolution), 2)
+    return int(40 + passes * (30 + 2.4 * int(num_inference_steps)))
+
+
+# ---------------------------------------------------------------- inference
+@spaces.GPU(duration=_duration)
+def refine(
+    image: Image.Image,
+    coarse_mesh: str | None = None,
+    resolution: int = 1024,
+    num_inference_steps: int = 25,
+    seed: int = 0,
+    randomize_seed: bool = False,
+    remove_background: bool = True,
+    progress=gr.Progress(),
+):
+    """Generate a high-resolution 3D mesh from a single image with Hi3D v1.0.
+
+    A coarse mesh is generated with Hunyuan3D-2mini-Turbo (or taken from the
+    optional upload), then refined by the Hi3D v1.0 sparse flow model
+    conditioned on the reference image.
+
+    Args:
+        image: Reference image of a single object (a cut-out with alpha works best).
+        coarse_mesh: Optional path to your own coarse mesh (.glb/.obj/.ply). When
+            omitted, Hunyuan3D-2mini-Turbo produces it from the image.
+        resolution: Target sparse extraction grid: 512 (1 pass), 1024 (2 passes)
+            or 1536 (3 passes).
+        num_inference_steps: Scheduler updates per refinement pass.
+        seed: Random seed.
+        randomize_seed: Pick a random seed instead of `seed`.
+        remove_background: Remove the background with rembg when the image has
+            no transparency.
+
+    Returns:
+        Paths to the coarse mesh GLB, the refined mesh GLB, the refined GLB
+        as a downloadable file, the seed used and a status string.
+    """
+    if image is None:
+        raise gr.Error("Please upload an image.")
+    if randomize_seed:
+        seed = random.randint(0, MAX_SEED)
+    seed = int(seed)
+    resolution = int(resolution)
+    num_inference_steps = int(num_inference_steps)
+    t0 = time.perf_counter()
+
+    progress(0.0, desc="Preparing image")
+    image = _prepare_input(image, remove_background)
+
+    if coarse_mesh:
+        progress(0.02, desc="Loading coarse mesh")
+        coarse = trimesh.load(coarse_mesh, force="mesh", process=False)
+    else:
+        progress(0.02, desc="Generating coarse mesh (Hunyuan3D-2mini-Turbo)")
+        coarse = coarse_pipe(
+            image=image,
+            num_inference_steps=COARSE_STEPS,
+            octree_resolution=COARSE_OCTREE_RESOLUTION,
+            generator=torch.manual_seed(seed),
+            output_type="trimesh",
+        )[0]
+    t_coarse = time.perf_counter() - t0
+    coarse_path = _export(coarse)
+
+    def _report(event):
+        frac = (event.pass_index + event.step / event.num_inference_steps) / event.num_passes
+        progress(
+            0.1 + 0.8 * frac,
+            desc=f"Hi3D pass {event.pass_index + 1}/{event.num_passes} "
+            f"(grid {event.structure_resolution}³) step {event.step}/{event.num_inference_steps}",
+        )
+
+    pipe.progress_callback = _report
+    try:
+        result = pipe(
+            image,
+            coarse,
+            resolution=resolution,
+            num_inference_steps=num_inference_steps,
+            seed=seed,
+        )
+    finally:
+        pipe.progress_callback = None
+    progress(0.95, desc="Exporting mesh")
+    refined_path = _export(result.mesh)
+    total = time.perf_counter() - t0
+    status = (
+        f"Done in {total:.1f}s (coarse {t_coarse:.1f}s) — resolution {result.resolution}, "
+        f"{len(result.mesh.faces):,} faces, seed {seed}"
+    )
+    print(status)
+    return coarse_path, refined_path, refined_path, seed, status
+
+
+# ---------------------------------------------------------------- UI
+CSS = """
+#col-container { max-width: 1200px; margin: 0 auto; }
+.dark .gradio-container { color: var(--body-text-color); }
+"""
+
+EXAMPLES_DIR = os.path.join(os.path.dirname(os.path.abspath(__file__)), "examples")
+EXAMPLES = [
+    [os.path.join(EXAMPLES_DIR, name)]
+    for name in (
+        "typical_creature_robot_dinosour.png",
+        "typical_humanoid_mech.png",
+        "typical_building_castle.png",
+        "typical_misc_phonograph.png",
+        "typical_vehicle_excavator.png",
+    )
+]
+
+with gr.Blocks(theme=gr.themes.Citrus(), css=CSS, title="Hi3D v1.0") as demo:
+    with gr.Column(elem_id="col-container"):
+        gr.Markdown(
+            """
+# Hi3D v1.0 — high-resolution 3D geometry refinement
+Upload an image of an object. A coarse mesh is generated with
+[Hunyuan3D-2mini-Turbo](https://huggingface.co/tencent/Hunyuan3D-2mini) (or upload your own),
+then [**Hi3D v1.0**](https://huggingface.co/hi3d-official/Hi3Dv1.0) — built on Sparc3D — refines
+it into high-resolution geometry conditioned on the image. Geometry only (no textures).
+[Model](https://huggingface.co/hi3d-official/Hi3Dv1.0) · [Code](https://github.com/hi3d-official/Hi3Dv1.0) · [Website](http://hi3d.ai/) — *Powered by Hi3D 1.0*
+"""
+        )
+        with gr.Row():
+            with gr.Column(scale=1):
+                image_in = gr.Image(label="Reference image", type="pil", image_mode="RGBA", height=360)
+                coarse_in = gr.File(
+                    label="Optional: your own coarse mesh (.glb / .obj / .ply) — leave empty to auto-generate",
+                    file_types=[".glb", ".gltf", ".obj", ".ply", ".stl", ".off"],
+                    type="filepath",
+                )
+                resolution = gr.Radio(
+                    [512, 1024, 1536],
+                    value=1024,
+                    label="Resolution (refinement passes: 1 / 2 / 3)",
+                )
+                run_btn = gr.Button("Generate", variant="primary")
+                with gr.Accordion("Advanced settings", open=False):
+                    steps = gr.Slider(5, 50, value=25, step=1, label="Inference steps per pass")
+                    seed = gr.Slider(0, MAX_SEED, value=0, step=1, label="Seed")
+                    randomize_seed = gr.Checkbox(value=False, label="Randomize seed")
+                    remove_bg = gr.Checkbox(
+                        value=True,
+                        label="Remove background (only applied if the image has no transparency)",
+                    )
+            with gr.Column(scale=2):
+                with gr.Row():
+                    coarse_out = gr.Model3D(label="Coarse mesh", height=420, clear_color=[1, 1, 1, 1])
+                    refined_out = gr.Model3D(label="Hi3D refined mesh", height=420, clear_color=[1, 1, 1, 1])
+                refined_file = gr.File(label="Download refined GLB")
+                status = gr.Markdown()
+
+        inputs = [image_in, coarse_in, resolution, steps, seed, randomize_seed, remove_bg]
+        outputs = [coarse_out, refined_out, refined_file, seed, status]
+        run_btn.click(refine, inputs=inputs, outputs=outputs, api_name="refine")
+
+        gr.Examples(
+            examples=EXAMPLES,
+            inputs=[image_in],
+            outputs=outputs,
+            fn=refine,
+            cache_examples=True,
+            cache_mode="lazy",
+            label="Examples (images from the MIT-licensed TRELLIS repo)",
+        )
+
+if __name__ == "__main__":
+    demo.launch(mcp_server=True)

requirements.txt

@@ -0,0 +1,24 @@
+torch==2.8.0
+torchvision==0.23.0
+numpy<2
+transformers>=5
+diffusers
+accelerate
+safetensors
+einops
+omegaconf
+pyyaml
+tqdm
+trimesh>=4.4.0,<5
+pyfqmr
+scikit-image
+pymeshlab
+pygltflib
+xatlas
+opencv-python==4.11.0.86
+opencv-python-headless==4.11.0.86
+rembg
+onnxruntime
+spconv-cu120==2.3.6
+https://huggingface.co/datasets/multimodalart/zerogpu-blackwell-wheels/resolve/main/wheels/pt28-cu128-cp310/flash_attn-2.7.4.post1-cp310-cp310-linux_x86_64.whl
+hy3dgen @ git+https://github.com/Tencent-Hunyuan/Hunyuan3D-2@f8db63096c8282cb27354314d896feba5ba6ff8a

sparc3d/__init__.py

@@ -0,0 +1,31 @@
+"""Lazy public package for the SPARC3D pipeline, output, and progress types."""
+
+from __future__ import annotations
+
+from typing import Any
+
+__version__ = "0.1.0"
+
+__all__ = ["Sparc3DPipeline", "Sparc3DPipelineOutput", "Sparc3DProgressEvent"]
+
+
+def __getattr__(name: str) -> Any:
+    """Load one of the public symbols on first access."""
+    if name == "Sparc3DPipeline":
+        from sparc3d.pipelines.sparc3d_pipeline import Sparc3DPipeline
+
+        return Sparc3DPipeline
+    if name == "Sparc3DPipelineOutput":
+        from sparc3d.pipelines.output import Sparc3DPipelineOutput
+
+        return Sparc3DPipelineOutput
+    if name == "Sparc3DProgressEvent":
+        from sparc3d.pipelines.progress import Sparc3DProgressEvent
+
+        return Sparc3DProgressEvent
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+
+
+def __dir__() -> list[str]:
+    """Return module names including the lazy public symbols."""
+    return sorted({*globals(), *__all__})

sparc3d/models/__init__.py

@@ -0,0 +1 @@
+"""Neural network models (sparse mesh autoencoder)."""

sparc3d/models/autoencoders/__init__.py

@@ -0,0 +1,11 @@
+"""Sparse mesh autoencoder: the PTv3 decoder and its JSON loader."""
+
+from sparc3d.models.autoencoders.config import load_sparconv_vae
+from sparc3d.models.autoencoders.ptv3 import PTv3MeshDecoder
+from sparc3d.models.autoencoders.sparconv_vae import SparconvVAE
+
+__all__ = [
+    "SparconvVAE",
+    "PTv3MeshDecoder",
+    "load_sparconv_vae",
+]

sparc3d/models/autoencoders/blocks.py

@@ -0,0 +1,575 @@
+"""Sparse PTv3 building blocks: norms, residual blocks, serialized attention, resampling.
+
+Module and parameter names are load-bearing: they define the checkpoint key layout.
+"""
+
+# Adapted from Pointcept / Point Transformer V3 (Xiaoyang Wu et al.) under the
+# MIT License. Modified for SPARC3D: specialized for the sparse mesh
+# autoencoder, with the training paths and drop-path removed.
+
+from __future__ import annotations
+
+import warnings
+
+import torch
+from torch import nn
+
+from sparc3d.ops import sparse_backend
+from sparc3d.structures.point import Point
+from sparc3d.structures.point_modules import PointModule, PointSequential
+from sparc3d.utils.misc import batch2offset, offset2bincount
+from sparc3d.utils.precision import force_fp32
+
+
+def _flash_attn():
+    """Import flash-attn when serialized attention is first constructed."""
+    try:
+        import flash_attn
+    except ImportError as exc:
+        raise ImportError(
+            "SparconvVAE serialized attention requires flash-attn; "
+            "install sparc3d[inference]"
+        ) from exc
+    return flash_attn
+
+
+_RESNET_SKIP_POINTS = 12_000_000
+"""Default ``SparseResnetBlock.skip_points``: above this token count the residual
+blocks pass the point through untouched and warn. The 1024 path can exceed what a
+full residual pass fits in memory, and the released weights were measured with this
+guard active, so it is reproduced behavior rather than a tuning knob.
+
+Deliberately the same number as ``pipelines.sparc3d_pipeline.DECODE_FEATURE_CEILING``,
+but a different policy: this one degrades a single block, while the pipeline raises
+when a *completed* decode is too large to feed another pass."""
+
+_GROUP_NORM_SPLIT = 8
+"""Groups normalized per iteration. Group statistics are independent, so this only
+bounds the temporaries, not the result."""
+
+
+class Swish(nn.Module):
+    """``x * sigmoid(x)``."""
+
+    def forward(self, x: torch.Tensor) -> torch.Tensor:
+        """Apply the Swish activation elementwise."""
+        return x * torch.sigmoid(x)
+
+
+class PointGroupNorm(PointModule):
+    """Group normalization over the points of each batch element of a sparse point cloud."""
+
+    def __init__(
+        self,
+        channels: int,
+        group: int = 32,
+        min_group_channels: int = 4,
+        eps: float = 1e-6,
+    ):
+        """
+        Args:
+            channels: Feature channels.
+            group: Requested number of groups; reduced when ``channels`` is too small
+                to give every group ``min_group_channels`` channels.
+            min_group_channels: Minimum channels per group.
+            eps: Variance floor.
+
+        Raises:
+            ValueError: ``channels`` is not divisible by the resolved group count.
+        """
+        super().__init__()
+        self.eps = eps
+        self.group = group
+        self.channels = channels
+        self.min_group_channels = min_group_channels
+
+        if self.min_group_channels * self.group > channels:
+            self.group = channels // self.min_group_channels
+        if self.group < 1 or channels % self.group != 0:
+            raise ValueError(
+                f"channels {channels} must be divisible by group {self.group}"
+            )
+        self.channels_per_group = channels // self.group
+
+        self.weights = nn.Parameter(torch.ones(1, channels))
+        self.bias = nn.Parameter(torch.zeros(1, channels))
+
+    @force_fp32(mode="convert_back")
+    def forward(self, point: Point) -> Point:
+        """Normalize ``point.feat`` per batch element and group, in float32."""
+        feat = point.feat
+        batch = point.batch.detach().clone()
+        N, C = feat.shape
+        B = int(batch[-1] + 1)
+
+        G = self.group
+        CP = self.channels_per_group
+        feat_group = feat.view(N, G, CP)
+        feat_norm_all = feat.new_zeros((N, G, CP))
+
+        for start in range(0, G, _GROUP_NORM_SPLIT):
+            end = min(start + _GROUP_NORM_SPLIT, G)
+
+            feat_slice = feat_group[:, start:end, :]
+            sum_feat = feat_slice.sum(dim=2)
+            sum_feat_sq = feat_slice.square().sum(dim=2)
+
+            # Per-(batch, group) moments, accumulated over the points of each element.
+            batch_idx = batch.view(-1, 1).expand(-1, end - start).long()
+            sums = feat.new_zeros((B, end - start)).scatter_add(0, batch_idx, sum_feat)
+            sums_sq = feat.new_zeros((B, end - start)).scatter_add(
+                0, batch_idx, sum_feat_sq
+            )
+
+            counts = torch.bincount(batch, minlength=B).float().view(B, 1) * CP
+            mean = sums.div_(counts + self.eps)
+            var = sums_sq.div_(counts + self.eps).sub_(mean.square())
+            inv_std = torch.rsqrt(var + self.eps)
+
+            mean_exp = mean.index_select(0, batch).unsqueeze(2)
+            inv_std_exp = inv_std.index_select(0, batch).unsqueeze(2)
+            feat_norm_all[:, start:end, :] = feat_slice.sub(mean_exp).mul_(inv_std_exp)
+
+            del feat_slice, sum_feat, sum_feat_sq, sums, sums_sq
+            del mean, var, inv_std, mean_exp, inv_std_exp
+
+        feat_norm_all = feat_norm_all.view(N, C)
+        feat_norm_all.mul_(self.weights).add_(self.bias)
+
+        point.update_feat(feat_norm_all)
+        return point
+
+
+class LayerNormFP32(nn.LayerNorm):
+    """Layer norm that always computes in float32, then restores the input dtype."""
+
+    @force_fp32(mode="convert_back")
+    def forward(self, x: torch.Tensor) -> torch.Tensor:
+        """Normalize the last dimension of ``x`` in float32."""
+        return super().forward(x)
+
+
+class MLP(nn.Module):
+    """Two-layer feed-forward block."""
+
+    def __init__(
+        self,
+        in_channels: int,
+        hidden_channels: int | None = None,
+        out_channels: int | None = None,
+        act_layer: type[nn.Module] = nn.GELU,
+    ):
+        """
+        Args:
+            in_channels: Input channels.
+            hidden_channels: Width of the hidden layer; defaults to ``in_channels``.
+            out_channels: Output channels; defaults to ``in_channels``.
+            act_layer: Activation constructed between the two linear layers.
+        """
+        super().__init__()
+        out_channels = out_channels or in_channels
+        hidden_channels = hidden_channels or in_channels
+        self.fc1 = nn.Linear(in_channels, hidden_channels)
+        self.act = act_layer()
+        self.fc2 = nn.Linear(hidden_channels, out_channels)
+
+    def forward(self, x: torch.Tensor) -> torch.Tensor:
+        """Project ``x`` through the hidden layer and back."""
+        return self.fc2(self.act(self.fc1(x)))
+
+
+class SparseClsHead(PointModule):
+    """Per-voxel classification head, used to predict octree occupancy on upsampling."""
+
+    def __init__(self, in_channels: int, out_channels: int):
+        """
+        Args:
+            in_channels: Input feature channels.
+            out_channels: Logits emitted per voxel; eight for octree occupancy.
+        """
+        super().__init__()
+        self.fc = PointSequential(
+            PointGroupNorm(in_channels),
+            Swish(),
+            sparse_backend.Conv3d(
+                in_channels, out_channels, kernel_size=3, stride=1, padding=1, bias=True
+            ),
+        )
+
+    @force_fp32(mode="convert")
+    def forward(self, point: Point) -> Point:
+        """Return a point whose ``feat`` holds the per-voxel occupancy logits."""
+        # Wrap only the tensors the head reads; cloning the whole point here would
+        # keep every intermediate of the calling stage alive.
+        head_point = Point(
+            dict(
+                feat=point.feat,
+                sparse_conv_feat=point.sparse_conv_feat,
+                batch=point.batch,
+            )
+        )
+        head_point.is_sparsified = True
+        return self.fc(head_point)
+
+
+class ConvOut(PointModule):
+    """Output projection that splits off the eight per-corner SDF sign logits."""
+
+    def __init__(self, in_channels: int, out_channels: int):
+        """
+        Args:
+            in_channels: Input feature channels.
+            out_channels: Output channels, the first eight being the SDF sign logits.
+        """
+        super().__init__()
+        self.conv = PointSequential(
+            PointGroupNorm(in_channels),
+            Swish(),
+            sparse_backend.Conv3d(
+                in_channels,
+                out_channels,
+                kernel_size=3,
+                stride=1,
+                padding=1,
+                bias=True,
+            ),
+        )
+
+    @force_fp32(mode="convert")
+    def forward(self, point: Point) -> Point:
+        """Split the projection into ``point["sdf_sign"]`` and the remaining features."""
+        point = self.conv(point)
+        point["sdf_sign"] = point.feat[:, :8]
+        point.update_feat(point.feat[:, 8:])
+        return point
+
+
+class SparseZToF(PointModule):
+    """Project latent channels back to decoder features."""
+
+    def __init__(self, in_channels: int, out_channels: int):
+        """
+        Args:
+            in_channels: Latent channels arriving from the transformer.
+            out_channels: Decoder feature channels at the coarsest stage.
+        """
+        super().__init__()
+        self.conv = PointSequential(
+            sparse_backend.Conv3d(
+                in_channels, out_channels, kernel_size=3, stride=1, padding=1, bias=True
+            )
+        )
+
+    @force_fp32(mode="enforce")
+    def forward(self, point: Point) -> Point:
+        """Project latent channels up to the decoder's feature width."""
+        return self.conv(point)
+
+
+class SparseResnetBlock(PointModule):
+    """Pre-norm residual block of two sparse 3x3x3 convolutions."""
+
+    def __init__(
+        self,
+        in_channels: int,
+        out_channels: int,
+        skip_points: int = _RESNET_SKIP_POINTS,
+    ):
+        """
+        Args:
+            in_channels: Input channels.
+            out_channels: Output channels.
+            skip_points: Token count above which the block passes its input through
+                unchanged. Defaults to the product's own guard.
+        """
+        super().__init__()
+        self.skip_points = skip_points
+        self.block = PointSequential(
+            PointGroupNorm(in_channels),
+            Swish(),
+            sparse_backend.Conv3d(
+                in_channels, out_channels, kernel_size=3, stride=1, padding=1, bias=True
+            ),
+            PointGroupNorm(out_channels),
+            Swish(),
+            sparse_backend.Conv3d(
+                out_channels, out_channels, kernel_size=3, stride=1, padding=1, bias=True
+            ),
+        )
+
+        # A PointSequential shortcut would alias and then overwrite point.feat.
+        if in_channels != out_channels:
+            self.res_conv = nn.Linear(in_channels, out_channels)
+        else:
+            self.res_conv = None
+
+    def forward(self, point: Point) -> Point:
+        """Add the residual branch to ``point``, or pass it through when oversized."""
+        if point.feat.shape[0] > self.skip_points:
+            warnings.warn(
+                f"SparseResnetBlock skipped: {point.feat.shape[0]} points exceeds the "
+                f"skip_points budget of {self.skip_points}. The block is a no-op, so "
+                "the output is the input; raise skip_points to run it.",
+                stacklevel=2,
+            )
+            return point
+        if self.res_conv is not None:
+            shortcut = self.res_conv(point.feat)
+        else:
+            shortcut = point.feat
+        point.update_feat(shortcut + self.block(point).feat)
+        return point
+
+
+class SerializedAttention(PointModule):
+    """Windowed self-attention over patches of a space-filling-curve ordering."""
+
+    def __init__(
+        self,
+        channels: int,
+        num_heads: int,
+        patch_size: int,
+        order_index: int = 0,
+    ):
+        """
+        Args:
+            channels: Feature channels; must be divisible by ``num_heads``.
+            num_heads: Attention heads.
+            patch_size: Points per attention window.
+            order_index: Which of the point's serialized orders to attend along.
+
+        Raises:
+            ValueError: ``channels`` is not divisible by ``num_heads``.
+            ImportError: flash-attn is not installed.
+        """
+        super().__init__()
+        if channels % num_heads != 0:
+            raise ValueError(
+                f"channels {channels} must be divisible by num_heads {num_heads}"
+            )
+        self._flash_attn = _flash_attn()
+        self.channels = channels
+        self.num_heads = num_heads
+        self.scale = (channels // num_heads)**-0.5
+        self.order_index = order_index
+        self.patch_size = patch_size
+
+        self.qkv = torch.nn.Linear(channels, channels * 3, bias=True)
+        self.proj = torch.nn.Linear(channels, channels)
+
+    @torch.no_grad()
+    def get_padding_and_inverse(self, point: Point):
+        """Return, and cache on ``point``, the patch padding maps and sequence bounds.
+
+        Each batch element is padded up to a whole number of patches by repeating its
+        last full patch, so attention never needs a mask.
+
+        Returns:
+            ``(pad, unpad, cu_seqlens)``: the padded gather index, its inverse, and
+            the cumulative patch boundaries flash attention expects.
+        """
+        pad_key = "pad"
+        unpad_key = "unpad"
+        cu_seqlens_key = "cu_seqlens_key"
+        if (
+            pad_key not in point.keys()
+            or unpad_key not in point.keys()
+            or cu_seqlens_key not in point.keys()
+        ):
+            offset = point.offset
+            bincount = offset2bincount(offset)
+            bincount_pad = (
+                torch.div(
+                    bincount + self.patch_size - 1,
+                    self.patch_size,
+                    rounding_mode="trunc",
+                )
+                * self.patch_size
+            )
+            # Only pad an element when it has more points than one patch.
+            mask_pad = bincount > self.patch_size
+            bincount_pad = ~mask_pad * bincount + mask_pad * bincount_pad
+            _offset = nn.functional.pad(offset, (1, 0))
+            _offset_pad = nn.functional.pad(torch.cumsum(bincount_pad, dim=0), (1, 0))
+            pad = torch.arange(_offset_pad[-1], device=offset.device)
+            unpad = torch.arange(_offset[-1], device=offset.device)
+            cu_seqlens = []
+            for i in range(len(offset)):
+                # yapf: disable
+                unpad[_offset[i] : _offset[i + 1]] += _offset_pad[i] - _offset[i]
+                if bincount[i] != bincount_pad[i]:
+                    pad[_offset_pad[i + 1] - self.patch_size + (bincount[i] % self.patch_size) : _offset_pad[i + 1]] = \
+                        pad[_offset_pad[i + 1] - 2 * self.patch_size + (bincount[i] % self.patch_size) : _offset_pad[i + 1] - self.patch_size]
+                pad[_offset_pad[i] : _offset_pad[i + 1]] -= _offset_pad[i] - _offset[i]
+                # yapf: enable
+                cu_seqlens.append(
+                    torch.arange(
+                        _offset_pad[i],
+                        _offset_pad[i + 1],
+                        step=self.patch_size,
+                        dtype=torch.int32,
+                        device=offset.device,
+                    )
+                )
+            point[pad_key] = pad
+            point[unpad_key] = unpad
+            point[cu_seqlens_key] = nn.functional.pad(
+                torch.concat(cu_seqlens), (0, 1), value=_offset_pad[-1]
+            )
+        return point[pad_key], point[unpad_key], point[cu_seqlens_key]
+
+    def forward(self, point: Point) -> Point:
+        """Attend within each patch of the serialized ordering and project the result."""
+        H = self.num_heads
+        C = self.channels
+
+        pad, unpad, cu_seqlens = self.get_padding_and_inverse(point)
+
+        order = point.serialized_order[self.order_index][pad]
+        inverse = unpad[point.serialized_inverse[self.order_index]]
+
+        qkv = self.qkv(point.feat)[order]
+
+        feat = self._flash_attn.flash_attn_varlen_qkvpacked_func(
+            qkv.half().reshape(-1, 3, H, C // H),
+            cu_seqlens,
+            max_seqlen=self.patch_size,
+            dropout_p=0,
+            softmax_scale=self.scale,
+        ).reshape(-1, C)
+        feat = feat.to(qkv.dtype)[inverse]
+
+        point.feat = self.proj(feat)
+        return point
+
+
+class SparseAttentionBlock(PointModule):
+    """Serialized attention block with a sparse conditional position encoding and MLP."""
+
+    def __init__(
+        self,
+        channels: int,
+        num_heads: int,
+        patch_size: int = 48,
+        mlp_ratio: float = 4.0,
+        order_index: int = 0,
+    ):
+        """
+        Args:
+            channels: Feature channels, preserved across the block.
+            num_heads: Attention heads.
+            patch_size: Points per attention window.
+            mlp_ratio: Hidden width of the MLP as a multiple of ``channels``.
+            order_index: Which of the point's serialized orders to attend along.
+        """
+        super().__init__()
+        self.channels = channels
+
+        norm_layer = LayerNormFP32
+        act_layer = nn.GELU
+
+        self.cpe = PointSequential(
+            sparse_backend.Conv3d(channels, channels, kernel_size=3, bias=True),
+            nn.Linear(channels, channels),
+            norm_layer(channels),
+        )
+
+        self.norm1 = PointSequential(norm_layer(channels))
+        self.attn = SerializedAttention(
+            channels=channels,
+            patch_size=patch_size,
+            num_heads=num_heads,
+            order_index=order_index,
+        )
+        self.norm2 = PointSequential(norm_layer(channels))
+        self.mlp = PointSequential(
+            MLP(
+                in_channels=channels,
+                hidden_channels=int(channels * mlp_ratio),
+                out_channels=channels,
+                act_layer=act_layer,
+            )
+        )
+
+    def forward(self, point: Point) -> Point:
+        """Apply the position encoding, attention and MLP residual branches in turn."""
+        shortcut = point.feat
+        point = self.cpe(point)
+        point.feat = shortcut + point.feat
+        shortcut = point.feat
+        point = self.norm1(point)
+        point = self.attn(point)
+        point.feat = shortcut + point.feat
+
+        shortcut = point.feat
+        point = self.norm2(point)
+        point = self.mlp(point)
+        point.feat = shortcut + point.feat
+        # Everything above touched only feat; resync the sparse view once.
+        point.sparse_conv_feat = sparse_backend.replace_feats(
+            point.sparse_conv_feat, point.feat
+        )
+        return point
+
+
+class SerializedUnpooling(PointModule):
+    """Double the grid resolution, keeping the children the occupancy head predicts."""
+
+    def __init__(self, channels: int):
+        """
+        Args:
+            channels: Feature channels, preserved across the resolution doubling.
+        """
+        super().__init__()
+        self.cls_head = SparseClsHead(channels, 8)
+        self.proj = nn.Linear(channels, channels * 8, bias=False)
+        self.inv_grid_coord = nn.Parameter(
+            torch.tensor(
+                [
+                    [0, 0, 0], [0, 0, 1], [0, 1, 0], [0, 1, 1],
+                    [1, 0, 0], [1, 0, 1], [1, 1, 0], [1, 1, 1],
+                ]
+            ),
+            requires_grad=False,
+        )
+
+    def forward(self, point: Point) -> Point:
+        """Split each voxel into eight children and keep the ones predicted occupied."""
+        feat = self.proj(point.feat)
+        pred_octree = self.cls_head(point).feat
+
+        m, c = feat.shape[0], feat.shape[1] // 8
+        mask = pred_octree.flatten() > 0
+
+        feat = feat.view(m * 8, c)[mask]
+        grid_coord = point.grid_coord.unsqueeze(1) * 2 + self.inv_grid_coord.unsqueeze(0)
+        grid_coord = grid_coord.view(-1, 3)[mask]
+        batch = point.batch.unsqueeze(1).expand(-1, 8).flatten()[mask]
+
+        point = point.clone(
+            feat=feat,
+            grid_coord=grid_coord,
+            resolution=point.resolution * 2,
+            batch=batch,
+            offset=batch2offset(batch),
+        )
+        point.sparsify()
+        return point
+
+
+class Upsample(PointModule):
+    """Stage-boundary upsampling by serialized unpooling."""
+
+    def __init__(self, channels: int):
+        """
+        Args:
+            channels: Feature channels, preserved across the upsampling.
+        """
+        super().__init__()
+        self.upsample = SerializedUnpooling(channels)
+
+    def forward(self, point: Point) -> Point:
+        """Double the grid resolution of ``point``."""
+        # The point count grows up to eightfold here; release the freed stage first.
+        torch.cuda.empty_cache()
+        return self.upsample(point)

sparc3d/models/autoencoders/config.py

@@ -0,0 +1,151 @@
+"""Explicit JSON-to-module construction for the sparse mesh autoencoder."""
+
+from __future__ import annotations
+
+import inspect
+import json
+from pathlib import Path
+from typing import Any, Mapping
+
+import torch
+
+from sparc3d.models.autoencoders.sparconv_vae import SparconvVAE
+from sparc3d.models.autoencoders.ptv3 import PTv3MeshDecoder
+from sparc3d.structures.point import Point
+
+_SUPPORTED_TYPES: dict[str, type] = {
+    "SparconvVAE": SparconvVAE,
+    "PTv3MeshDecoder": PTv3MeshDecoder,
+}
+"""The only ``type`` discriminators a runtime config may name."""
+
+_SUB_CONFIG_TYPES: dict[str, str] = {"decoder_cfg": "PTv3MeshDecoder"}
+"""The ``type`` each ``SparconvVAE`` sub-config must name."""
+
+
+def load_config(config: str | Path | Mapping[str, Any]) -> dict[str, Any]:
+    """Read a runtime config and return its model block.
+
+    Args:
+        config: Path to a JSON file, or an already-parsed mapping. Either the whole
+            document (with a ``model`` key) or the model block itself is accepted.
+
+    Returns:
+        The model block as a plain dict.
+
+    Raises:
+        ValueError: The document has no model block carrying a ``type``.
+    """
+    if isinstance(config, (str, Path)):
+        with Path(config).open("r", encoding="utf-8") as f:
+            document = json.load(f)
+    else:
+        document = dict(config)
+
+    model = document.get("model", document)
+    if not isinstance(model, Mapping) or "type" not in model:
+        raise ValueError("config has no 'model' block with a 'type' discriminator")
+    return dict(model)
+
+
+def build_sparconv_vae(config: str | Path | Mapping[str, Any]) -> SparconvVAE:
+    """Instantiate a :class:`SparconvVAE` from a runtime config, without loading weights.
+
+    Args:
+        config: Runtime config, as accepted by :func:`load_config`.
+
+    Returns:
+        Model on the CPU in eval mode.
+
+    Raises:
+        ValueError: An unsupported ``type``, a missing sub-config, or an unknown
+            constructor key.
+    """
+    model_cfg = load_config(config)
+    _resolve_type(model_cfg, "model", "SparconvVAE")
+    # Training sections (losses, optimizer, scheduler) are rejected rather than
+    # ignored, so a training config can never be mistaken for a runtime artifact.
+    extra = sorted(set(model_cfg) - set(_SUB_CONFIG_TYPES))
+    if extra:
+        raise ValueError(f"model config has non-architecture keys: {extra}")
+
+    expected_attributes = sum(
+        Point.ALL_LAYOUTS[key]["size"] for key in ("sdf", "deform")
+    )
+    if "decoder_cfg" not in model_cfg:
+        raise ValueError("model config is missing 'decoder_cfg'")
+    sub_cfg = dict(model_cfg["decoder_cfg"])
+    cls = _resolve_type(sub_cfg, "decoder_cfg", "PTv3MeshDecoder")
+    kwargs = _validated_kwargs(cls, sub_cfg, "decoder_cfg")
+    output_channels = kwargs.get(
+        "out_channels", inspect.signature(cls).parameters["out_channels"].default
+    )
+    if output_channels != expected_attributes:
+        raise ValueError(
+            f"decoder out_channels must be {expected_attributes}, "
+            f"got {output_channels}"
+        )
+
+    model = SparconvVAE(decoder=cls(**kwargs))
+    model.eval()
+    return model
+
+
+def load_sparconv_vae(
+    weights: str | Path,
+    config: str | Path | Mapping[str, Any] | None = None,
+    *,
+    device: str | torch.device = "cuda",
+) -> SparconvVAE:
+    """Build a :class:`SparconvVAE` and load its weights, requiring an exact key match.
+
+    Args:
+        weights: Path to a ``.safetensors`` file, or to a directory holding
+            ``model.safetensors`` and ``config.json``.
+        config: Runtime config; defaults to ``config.json`` beside the weights.
+        device: Device to move the model to.
+
+    Returns:
+        Model in eval mode on ``device``.
+
+    Raises:
+        FileNotFoundError: The weights, or the implied ``config.json``, are missing.
+        RuntimeError: The checkpoint keys do not match the model's parameters exactly.
+    """
+    from safetensors.torch import load_file
+
+    weights_path = Path(weights)
+    if weights_path.is_dir():
+        weights_path = weights_path / "model.safetensors"
+    if not weights_path.is_file():
+        raise FileNotFoundError(f"no weights at {weights_path}")
+
+    if config is None:
+        config = weights_path.parent / "config.json"
+        if not Path(config).is_file():
+            raise FileNotFoundError(
+                f"no config given and no config.json beside {weights_path}"
+            )
+
+    model = build_sparconv_vae(config)
+    model.load_state_dict(load_file(str(weights_path)), strict=True)
+    return model.to(device).eval()
+
+
+def _resolve_type(cfg: dict[str, Any], where: str, expected: str) -> type:
+    """Pop the ``type`` discriminator and resolve it to its class."""
+    type_name = cfg.pop("type", None)
+    if type_name != expected:
+        raise ValueError(
+            f"{where}: unsupported type {type_name!r}; expected {expected!r}"
+        )
+    return _SUPPORTED_TYPES[type_name]
+
+
+def _validated_kwargs(cls: type, cfg: dict[str, Any], where: str) -> dict[str, Any]:
+    """Reject config keys that are not constructor parameters of ``cls``."""
+    accepted = set(inspect.signature(cls).parameters)
+    unknown = sorted(set(cfg) - accepted)
+    if unknown:
+        raise ValueError(f"{where}: unknown keys for {cls.__name__}: {unknown}")
+    return cfg

sparc3d/models/autoencoders/ptv3.py

@@ -0,0 +1,118 @@
+"""Sparse PTv3 mesh decoder."""
+
+# Adapted from Pointcept / Point Transformer V3 under the MIT License.
+# Modified for SPARC3D: the decoder half only, reading a latent grid instead of
+# an encoded point cloud.
+
+from __future__ import annotations
+
+from typing import Sequence
+
+from sparc3d.models.autoencoders.blocks import (
+    ConvOut,
+    SparseAttentionBlock,
+    SparseResnetBlock,
+    SparseZToF,
+    Upsample,
+)
+from sparc3d.structures.point import Point
+from sparc3d.structures.point_modules import PointModule, PointSequential
+
+
+class PTv3MeshDecoder(PointModule):
+    """Decode a coarse latent point cloud back into per-corner SDF and deformation.
+
+    A serialized attention stack mixes globally at the coarsest level, then residual
+    stages double the resolution and prune children by predicted occupancy.
+    """
+
+    def __init__(
+        self,
+        out_channels: int = 32,
+        order: str | Sequence[str] = ("z", "z-trans"),
+        depths: Sequence[int] = (2, 2, 2, 2),
+        channels: Sequence[int] = (128, 256, 512, 512),
+        mid_depth: int = 2,
+        mid_num_head: int = 32,
+        z_channels: int = 32,
+        patch_size: int = 48,
+        mlp_ratio: float = 4,
+    ):
+        """
+        Args:
+            out_channels: Attribute channels emitted, on top of the eight sign logits.
+            order: Space-filling curve orders; attention blocks cycle through them.
+            depths: Residual blocks per stage.
+            channels: Feature width per stage.
+            mid_depth: Attention blocks at the coarsest level.
+            mid_num_head: Attention heads at the coarsest level.
+            z_channels: Latent channels consumed.
+            patch_size: Points per attention window.
+            mlp_ratio: Attention-block MLP expansion ratio.
+
+        Raises:
+            ValueError: ``depths`` and ``channels`` describe different stage counts.
+        """
+        super().__init__()
+
+        self.num_stages = len(depths)
+        self.order = [order] if isinstance(order, str) else list(order)
+
+        if len(channels) != self.num_stages:
+            raise ValueError(
+                f"channels has {len(channels)} entries but depths describes "
+                f"{self.num_stages} stages"
+            )
+
+        mid_ch = channels[-1]
+        self.z_to_f = SparseZToF(z_channels, mid_ch)
+
+        self.mid = PointSequential()
+        self.mid.add(SparseResnetBlock(mid_ch, mid_ch), name="block_in")
+        for i in range(mid_depth):
+            self.mid.add(
+                SparseAttentionBlock(
+                    channels=mid_ch,
+                    num_heads=mid_num_head,
+                    patch_size=patch_size,
+                    mlp_ratio=mlp_ratio,
+                    order_index=i % len(self.order),
+                ),
+                name=f"block{i}",
+            )
+        self.mid.add(SparseResnetBlock(mid_ch, mid_ch), name="block_out")
+
+        self.dec = PointSequential()
+        for s in reversed(range(self.num_stages)):
+            dec = PointSequential()
+            block_in = channels[s]
+            block_out = channels[s - 1] if s > 0 else channels[0]
+            for i in range(depths[s]):
+                dec.add(SparseResnetBlock(block_in, block_out), name=f"block{i}")
+                block_in = block_out
+            if s != 0:
+                dec.add(Upsample(block_out), name="up")
+            self.dec.add(module=dec, name=f"dec{s}")
+
+        # Eight extra output channels carry the per-corner SDF sign logits.
+        self.conv_out = ConvOut(block_out, 8 + out_channels)
+
+    def forward(self, point: Point) -> Point:
+        """Decode latents into per-corner SDF signs, distances and deformations.
+
+        Args:
+            point: Sparse point carrying latent ``feat`` on its grid. Sparsified and
+                serialized in place if the caller has not done so already.
+
+        Returns:
+            The same point, with ``sdf_sign`` set and ``feat`` holding the remaining
+            per-corner attributes at the final resolution.
+        """
+        if not point.is_sparsified:
+            point.sparsify()
+        point = self.z_to_f(point)
+        if not point.is_serialized:
+            point.serialization(order=self.order)
+        point = self.mid(point)
+        point = self.dec(point)
+        return self.conv_out(point)

sparc3d/models/autoencoders/sparconv_vae.py

@@ -0,0 +1,63 @@
+"""Sparse decoder over voxel-corner mesh attributes (``SparconvVAE``)."""
+
+from __future__ import annotations
+
+from typing import Mapping
+
+from torch import nn
+
+from sparc3d.models.autoencoders.ptv3 import PTv3MeshDecoder
+from sparc3d.structures.point import Point
+
+
+class SparconvVAE(nn.Module):
+    """Sparse latent decoder over per-corner mesh attributes.
+
+    Named for the autoencoder the weights were trained as, but this is the decoder
+    alone: latents arrive from the diffusion transformer, so no encoder or Gaussian
+    bottleneck is reachable at inference and neither is included here.
+    """
+
+    def __init__(self, decoder: PTv3MeshDecoder):
+        """
+        Args:
+            decoder: Latent-to-attribute decoder.
+        """
+        super().__init__()
+        self.decoder = decoder
+
+    def decode(self, z_q: Point | Mapping) -> Point:
+        """Decode a latent point cloud into activated per-corner attributes.
+
+        Args:
+            z_q: Latent point cloud, or a diffusion output mapping with ``grid_coord``, ``feat``, ``resolution``, and a
+                batch descriptor.
+
+        Returns:
+            Decoded point cloud whose ``feat`` holds activated attributes and whose
+            ``sdf_sign`` holds the per-corner sign logits.
+        """
+        if not isinstance(z_q, Point):
+            data = dict(z_q)
+            data.setdefault("sdf", None)
+            data.setdefault("deform", None)
+            z_q = Point(data)
+            z_q.initialization()
+        elif "layouts" not in z_q or "matrix" not in z_q:
+            z_q.initialization()
+
+        if not {"sdf", "deform"}.issubset(z_q.layouts):
+            start = 0
+            layouts = {}
+            for key in ("sdf", "deform"):
+                entry = Point.ALL_LAYOUTS[key]
+                layouts[key] = {
+                    **entry,
+                    "range": (start, start + entry["size"]),
+                }
+                start += entry["size"]
+            z_q["layouts"] = layouts
+
+        x_hat = self.decoder(z_q)
+        x_hat.activate()
+        return x_hat

sparc3d/models/conditioners/__init__.py

@@ -0,0 +1,5 @@
+"""Image conditioning models."""
+
+from sparc3d.models.conditioners.image import ImageConditioner
+
+__all__ = ["ImageConditioner"]

sparc3d/models/conditioners/image.py

@@ -0,0 +1,169 @@
+"""Shared DINOv2 and CLIP image conditioner."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+import numpy as np
+import torch
+import torch.nn.functional as F
+from PIL import Image
+from torch import Tensor, nn
+from transformers import AutoModel, CLIPVisionModel
+
+DINO_MODEL_ID = "facebook/dinov2-large"
+"""Moving Hugging Face repository used for DINOv2 conditioning."""
+
+CLIP_MODEL_ID = "openai/clip-vit-large-patch14"
+"""Moving Hugging Face repository used for CLIP conditioning."""
+
+_DINO_SIZE = 756
+_CLIP_SIZE = 224
+
+
+class ImageConditioner(nn.Module):
+    """Frozen fp32 image conditioner combining DINOv2 tokens and CLIP context."""
+
+    def __init__(
+        self,
+        *,
+        cache_dir: str | Path | None = None,
+        local_files_only: bool = False,
+        dino_model_id: str | Path = DINO_MODEL_ID,
+        clip_model_id: str | Path = CLIP_MODEL_ID,
+    ) -> None:
+        """Load and freeze the shared Hugging Face vision encoders.
+
+        Args:
+            cache_dir: Optional Hugging Face cache directory. This is the directory
+                that holds the ``models--*`` trees, i.e. ``$HF_HOME/hub`` rather
+                than ``$HF_HOME``.
+            local_files_only: Whether encoder loading must use cached files only.
+            dino_model_id: DINOv2 repository ID, or a local directory holding the
+                encoder. A directory needs no Hub cache layout, which is the
+                simplest way to run without network access.
+            clip_model_id: CLIP repository ID, or a local directory.
+        """
+        super().__init__()
+        load_kwargs: dict[str, Any] = {}
+        if cache_dir is not None:
+            load_kwargs["cache_dir"] = str(cache_dir)
+        if local_files_only:
+            load_kwargs["local_files_only"] = True
+        self.dino = AutoModel.from_pretrained(str(dino_model_id), **load_kwargs).float()
+        self.clip = CLIPVisionModel.from_pretrained(
+            str(clip_model_id), **load_kwargs
+        ).float()
+
+        for parameter in self.parameters():
+            parameter.requires_grad_(False)
+
+        self.register_buffer(
+            "_dino_mean",
+            torch.tensor([0.485, 0.456, 0.406], dtype=torch.float32).view(1, 3, 1, 1),
+            persistent=False,
+        )
+        self.register_buffer(
+            "_dino_std",
+            torch.tensor([0.229, 0.224, 0.225], dtype=torch.float32).view(1, 3, 1, 1),
+            persistent=False,
+        )
+        self.register_buffer(
+            "_clip_mean",
+            torch.tensor(
+                [0.48145466, 0.4578275, 0.40821073], dtype=torch.float32
+            ).view(1, 3, 1, 1),
+            persistent=False,
+        )
+        self.register_buffer(
+            "_clip_std",
+            torch.tensor(
+                [0.26862954, 0.26130258, 0.27577711], dtype=torch.float32
+            ).view(1, 3, 1, 1),
+            persistent=False,
+        )
+        self.eval()
+
+    def train(self, mode: bool = True) -> "ImageConditioner":
+        """Keep the conditioner and both frozen encoders in evaluation mode."""
+        del mode
+        return super().train(False)
+
+    @torch.no_grad()
+    def forward(self, image: Image.Image) -> Tensor:
+        """Encode one prepared PIL image into batch-1 conditioning tokens.
+
+        Args:
+            image: Prepared RGB PIL image. Only a single image is accepted.
+
+        Returns:
+            L2-normalized DINOv2 tokens concatenated with a broadcast CLIP
+            embedding, shaped ``[1, 2917, 2048]``.
+
+        Raises:
+            TypeError: ``image`` is not a PIL image.
+            ValueError: The encoders return an unexpected token or channel shape.
+        """
+        if not isinstance(image, Image.Image):
+            raise TypeError(
+                f"image must be one prepared PIL image, got {type(image).__name__}"
+            )
+
+        device = self._dino_mean.device
+        base_input = self._pil_tensor(image, device)
+        dino_input = F.interpolate(
+            base_input,
+            size=(_DINO_SIZE, _DINO_SIZE),
+            mode="bilinear",
+            align_corners=False,
+        )
+        clip_input = self._image_tensor(
+            image, _CLIP_SIZE, Image.Resampling.LANCZOS, device
+        )
+        dino_input = (dino_input - self._dino_mean) / self._dino_std
+        clip_input = (clip_input - self._clip_mean) / self._clip_std
+
+        # Disable an enclosing mixed-precision context because conditioner numerics
+        # are fixed to fp32 independently of transformer inference precision.
+        with torch.autocast(device_type=device.type, enabled=False):
+            dino_output: Any = self.dino(pixel_values=dino_input)
+            clip_output: Any = self.clip(pixel_values=clip_input)
+
+        dino_tokens = F.normalize(
+            dino_output.last_hidden_state.float(), p=2, dim=-1
+        )
+        clip_embedding = F.normalize(clip_output.pooler_output.float(), p=2, dim=-1)
+
+        if dino_tokens.shape != (1, 2917, 1024):
+            raise ValueError(
+                "DINOv2 output must have shape [1, 2917, 1024], "
+                f"got {list(dino_tokens.shape)}"
+            )
+        if clip_embedding.shape != (1, 1024):
+            raise ValueError(
+                "CLIP output must have shape [1, 1024], "
+                f"got {list(clip_embedding.shape)}"
+            )
+
+        clip_tokens = clip_embedding[:, None, :].expand(
+            -1, dino_tokens.shape[1], -1
+        )
+        return torch.cat((dino_tokens, clip_tokens), dim=-1)
+
+    @staticmethod
+    def _image_tensor(
+        image: Image.Image,
+        size: int,
+        resample: Image.Resampling,
+        device: torch.device,
+    ) -> Tensor:
+        rgb = image.convert("RGB").resize((size, size), resample=resample)
+        return ImageConditioner._pil_tensor(rgb, device)
+
+    @staticmethod
+    def _pil_tensor(image: Image.Image, device: torch.device) -> Tensor:
+        rgb = image.convert("RGB")
+        array = np.asarray(rgb, dtype=np.float32)
+        tensor = torch.from_numpy(array.copy()).permute(2, 0, 1).unsqueeze(0)
+        return tensor.to(device=device, dtype=torch.float32).div_(255.0)

sparc3d/models/transformers/__init__.py

@@ -0,0 +1,6 @@
+"""Sparse latent transformer and its validated runtime configuration."""
+
+from .config import Sparc3DTransformerConfig
+from .sparc3d_transformer import Sparc3DTransformer
+
+__all__ = ["Sparc3DTransformer", "Sparc3DTransformerConfig"]

sparc3d/models/transformers/config.py

@@ -0,0 +1,195 @@
+"""Validated configuration for the released sparse latent transformer."""
+
+from __future__ import annotations
+
+from dataclasses import asdict, dataclass, fields
+from typing import Any, Mapping
+
+
+_LATENT_MEAN = (
+    -0.00155994,
+    0.03314649,
+    -0.00307796,
+    0.00630751,
+    -0.00835457,
+    -0.03860179,
+    0.02528263,
+    0.03740620,
+    -0.06209833,
+    -0.00539356,
+    -0.02110271,
+    0.05126001,
+    0.00753371,
+    0.02866821,
+    0.02772475,
+    -0.02131735,
+    -0.02799912,
+    0.01084617,
+    0.03433723,
+    -0.00903100,
+    -0.00121899,
+    -0.01944244,
+    0.01641873,
+    -0.01063657,
+    -0.01990618,
+    0.04856062,
+    0.01747232,
+    -0.02387775,
+    0.03216169,
+    -0.03732105,
+    -0.03730354,
+    -0.01948937,
+)
+"""Per-channel mean of the released structured latent."""
+
+_LATENT_STD = (
+    0.61686146,
+    0.80115320,
+    0.85489200,
+    0.96384716,
+    0.77005910,
+    0.62859850,
+    0.61541015,
+    0.74368310,
+    0.62762610,
+    1.01842280,
+    0.77113867,
+    0.62627990,
+    0.68749195,
+    0.62698966,
+    0.75491240,
+    0.61577400,
+    0.63780660,
+    0.80406000,
+    0.83846325,
+    0.69120390,
+    0.69227580,
+    0.79321617,
+    0.63475930,
+    0.63848300,
+    0.67194235,
+    0.73519380,
+    0.84781533,
+    0.93012910,
+    0.62691440,
+    0.67906080,
+    0.65198770,
+    0.77692040,
+)
+"""Per-channel standard deviation of the released structured latent."""
+
+
+@dataclass(frozen=True)
+class Sparc3DTransformerConfig:
+    """Narrow architecture configuration for :class:`Sparc3DTransformer`.
+
+    Only the dimensions that actually vary between the two released checkpoints are
+    configurable. The architecture choices the weights were trained under -- rotary
+    position encoding, full flash attention, self-attention QK RMS normalization,
+    shared timestep modulation, and I/O skip connections -- are fixed in the model.
+    """
+
+    resolution: int = 64
+    """Structure-grid resolution represented by input coordinates."""
+
+    in_channels: int = 32
+    """Input latent feature channels."""
+
+    out_channels: int = 32
+    """Predicted latent feature channels."""
+
+    model_channels: int = 2112
+    """Transformer hidden width."""
+
+    cond_channels: int = 2048
+    """Image-conditioning width."""
+
+    num_blocks: int = 24
+    """Number of shared-modulation transformer blocks."""
+
+    num_heads: int = 22
+    """Number of attention heads."""
+
+    mlp_ratio: float = 4.0
+    """Expansion ratio of each feed-forward layer."""
+
+    patch_size: int = 2
+    """Sparse I/O downsampling factor."""
+
+    num_io_res_blocks: int = 2
+    """Residual blocks in each I/O stage."""
+
+    io_block_channels: tuple[int, ...] = (256,)
+    """Channels in each sparse I/O stage."""
+
+    use_fp16: bool = True
+    """Whether the transformer torso uses float16 parameters."""
+
+    latent_mean: tuple[float, ...] = _LATENT_MEAN
+    """Per-channel latent mean used by pipeline normalization."""
+
+    latent_std: tuple[float, ...] = _LATENT_STD
+    """Per-channel latent standard deviation used by pipeline normalization."""
+
+    def __post_init__(self) -> None:
+        positive = {
+            "resolution": self.resolution,
+            "in_channels": self.in_channels,
+            "out_channels": self.out_channels,
+            "model_channels": self.model_channels,
+            "cond_channels": self.cond_channels,
+            "num_blocks": self.num_blocks,
+            "num_heads": self.num_heads,
+            "patch_size": self.patch_size,
+            "num_io_res_blocks": self.num_io_res_blocks,
+        }
+        invalid = [name for name, value in positive.items() if value <= 0]
+        if invalid:
+            raise ValueError(f"positive dimensions required for {invalid}")
+        if self.model_channels % self.num_heads:
+            raise ValueError("model_channels must be divisible by num_heads")
+        head_dim = self.model_channels // self.num_heads
+        if head_dim % 2 or head_dim < 6:
+            raise ValueError("attention head dimension must be even and at least 6")
+        if self.patch_size & (self.patch_size - 1):
+            raise ValueError("patch_size must be a power of two")
+        if self.patch_size != 2 ** len(self.io_block_channels):
+            raise ValueError("I/O stage count must equal log2(patch_size)")
+        if any(channels <= 1 for channels in self.io_block_channels):
+            raise ValueError("I/O stage channels must be greater than one")
+        if len(self.latent_mean) != self.in_channels:
+            raise ValueError("latent_mean length must match in_channels")
+        if len(self.latent_std) != self.in_channels:
+            raise ValueError("latent_std length must match in_channels")
+        if any(value <= 0 for value in self.latent_std):
+            raise ValueError("latent_std values must be positive")
+
+    @classmethod
+    def from_dict(cls, values: Mapping[str, Any]) -> "Sparc3DTransformerConfig":
+        """Build a config from an allowlisted mapping.
+
+        Args:
+            values: Parsed transformer configuration.
+
+        Returns:
+            Validated config.
+
+        Raises:
+            ValueError: Unknown keys are present.
+        """
+        values = dict(values)
+        allowed = {item.name for item in fields(cls)}
+        unknown = sorted(set(values) - allowed)
+        if unknown:
+            raise ValueError(f"unknown transformer config keys: {unknown}")
+        for key in ("io_block_channels", "latent_mean", "latent_std"):
+            if key in values:
+                values[key] = tuple(values[key])
+        return cls(**values)
+
+    def to_dict(self) -> dict[str, Any]:
+        """Return a JSON-compatible configuration mapping."""
+        values = asdict(self)
+        for key in ("io_block_channels", "latent_mean", "latent_std"):
+            values[key] = list(values[key])
+        return values

sparc3d/models/transformers/sparc3d_transformer.py

@@ -0,0 +1,280 @@
+"""Sparse latent flow transformer for image-conditioned mesh refinement."""
+
+# Adapted from Microsoft TRELLIS under the MIT License.
+# Modified for SPARC3D: the released sparse inference architecture.
+
+from __future__ import annotations
+
+import math
+from typing import Any
+
+import torch
+import torch.nn.functional as F
+from torch import nn
+
+from sparc3d.nn import LayerNorm32
+from sparc3d.nn.sparse import (
+    SparseConv3d,
+    SparseDownsample,
+    SparseLinear,
+    SparseTensor,
+    SparseUpsample,
+)
+from sparc3d.nn.sparse.transformer import ModulatedSparseTransformerCrossBlock
+from sparc3d.nn.utils import convert_module_to_f16, zero_module
+
+from .config import Sparc3DTransformerConfig
+
+
+class TimestepEmbedder(nn.Module):
+    """Sinusoidal scalar timestep embedding followed by a two-layer MLP."""
+
+    def __init__(self, hidden_size: int, frequency_embedding_size: int = 256):
+        """
+        Args:
+            hidden_size: Width of the embedding the MLP produces.
+            frequency_embedding_size: Sinusoidal features formed before the MLP.
+        """
+        super().__init__()
+        self.mlp = nn.Sequential(
+            nn.Linear(frequency_embedding_size, hidden_size, bias=True),
+            nn.SiLU(),
+            nn.Linear(hidden_size, hidden_size, bias=True),
+        )
+        self.frequency_embedding_size = frequency_embedding_size
+
+    @staticmethod
+    def timestep_embedding(
+        timestep: torch.Tensor, dim: int, max_period: int = 10000
+    ) -> torch.Tensor:
+        """Create sinusoidal embeddings for scalar timesteps.
+
+        Args:
+            timestep: Fractional or integral timesteps ``[B]``.
+            dim: Embedding width.
+            max_period: Minimum-frequency denominator.
+
+        Returns:
+            Embeddings ``[B, dim]``.
+        """
+        half = dim // 2
+        frequencies = torch.exp(
+            -math.log(max_period) * torch.arange(half, dtype=torch.float32) / half
+        ).to(timestep.device)
+        arguments = timestep[:, None].float() * frequencies[None]
+        embedding = torch.cat((torch.cos(arguments), torch.sin(arguments)), dim=-1)
+        if dim % 2:
+            embedding = torch.cat(
+                (embedding, torch.zeros_like(embedding[:, :1])), dim=-1
+            )
+        return embedding
+
+    def forward(self, timestep: torch.Tensor) -> torch.Tensor:
+        """Embed ``timestep`` into the transformer hidden width."""
+        frequencies = self.timestep_embedding(timestep, self.frequency_embedding_size)
+        return self.mlp(frequencies)
+
+
+class SparseResBlock3d(nn.Module):
+    """Timestep-modulated sparse residual block with optional paired resampling."""
+
+    def __init__(
+        self,
+        channels: int,
+        emb_channels: int,
+        out_channels: int | None = None,
+        *,
+        downsample: bool = False,
+        upsample: bool = False,
+    ):
+        """
+        Args:
+            channels: Input feature channels.
+            emb_channels: Timestep embedding channels consumed by the modulation.
+            out_channels: Output channels; defaults to ``channels``.
+            downsample: Halve the spatial resolution across the block.
+            upsample: Double the spatial resolution across the block.
+
+        Raises:
+            ValueError: Both ``downsample`` and ``upsample`` are set.
+        """
+        super().__init__()
+        if downsample and upsample:
+            raise ValueError("cannot downsample and upsample in one block")
+        self.channels = channels
+        self.emb_channels = emb_channels
+        self.out_channels = out_channels or channels
+        self.hidden_channels = self.out_channels // 2
+        self.downsample = downsample
+        self.upsample = upsample
+        self.norm1 = LayerNorm32(channels, elementwise_affine=True, eps=1e-6)
+        self.norm2 = LayerNorm32(
+            self.hidden_channels, elementwise_affine=False, eps=1e-6
+        )
+        self.conv1 = SparseConv3d(channels, self.hidden_channels, 3)
+        self.conv2 = SparseConv3d(self.hidden_channels, self.hidden_channels, 3)
+        self.linear = zero_module(SparseLinear(self.hidden_channels, self.out_channels))
+        self.emb_layers = nn.Sequential(
+            nn.SiLU(),
+            nn.Linear(emb_channels, 2 * self.hidden_channels, bias=True),
+        )
+        self.skip_connection = (
+            SparseLinear(channels, self.out_channels)
+            if channels != self.out_channels
+            else nn.Identity()
+        )
+        self.updown: nn.Module | None = None
+        if downsample:
+            self.updown = SparseDownsample(2)
+        elif upsample:
+            self.updown = SparseUpsample(2)
+
+    def forward(self, x: SparseTensor, embedding: torch.Tensor) -> SparseTensor:
+        """Apply residual convolution and optional paired resampling."""
+        scale, shift = self.emb_layers(embedding).to(x.dtype).chunk(2, dim=1)
+        if self.updown is not None:
+            x = self.updown(x)
+        h = x.replace(self.norm1(x.feats))
+        h = h.replace(F.silu(h.feats))
+        h = self.conv1(h)
+        h = h.replace(self.norm2(h.feats)) * (1 + scale) + shift
+        h = h.replace(F.silu(h.feats))
+        h = self.conv2(h)
+        h = h.replace(F.silu(h.feats))
+        return self.linear(h) + self.skip_connection(x)
+
+
+class Sparc3DTransformer(nn.Module):
+    """Released sparse latent flow transformer with a validated narrow config."""
+
+    def __init__(
+        self,
+        config: Sparc3DTransformerConfig | None = None,
+        **config_values: Any,
+    ):
+        """
+        Args:
+            config: Validated configuration. Mutually exclusive with ``config_values``.
+            **config_values: Configuration fields to validate into a config instead.
+
+        Raises:
+            ValueError: Both a config and configuration values were given, or a value
+                fails validation.
+        """
+        super().__init__()
+        if config is not None and config_values:
+            raise ValueError("pass either config or configuration keyword values")
+        self.config = config or Sparc3DTransformerConfig.from_dict(config_values)
+        config = self.config
+        self.dtype = torch.float16 if config.use_fp16 else torch.float32
+
+        channels = list(config.io_block_channels)
+        self.t_embedder = TimestepEmbedder(config.model_channels)
+        self.adaLN_modulation = nn.Sequential(
+            nn.SiLU(),
+            nn.Linear(config.model_channels, 6 * config.model_channels, bias=True),
+        )
+        self.input_layer = SparseLinear(config.in_channels, channels[0])
+        self.input_blocks = nn.ModuleList()
+        for current, following in zip(channels, channels[1:] + [config.model_channels]):
+            self.input_blocks.extend(
+                SparseResBlock3d(current, config.model_channels)
+                for _ in range(config.num_io_res_blocks - 1)
+            )
+            self.input_blocks.append(
+                SparseResBlock3d(
+                    current,
+                    config.model_channels,
+                    out_channels=following,
+                    downsample=True,
+                )
+            )
+
+        self.blocks = nn.ModuleList(
+            ModulatedSparseTransformerCrossBlock(
+                config.model_channels,
+                config.cond_channels,
+                config.num_heads,
+                mlp_ratio=config.mlp_ratio,
+            )
+            for _ in range(config.num_blocks)
+        )
+
+        self.out_blocks = nn.ModuleList()
+        previous_channels = [config.model_channels] + list(reversed(channels[1:]))
+        for current, previous in zip(reversed(channels), previous_channels):
+            self.out_blocks.append(
+                SparseResBlock3d(
+                    previous * 2,
+                    config.model_channels,
+                    out_channels=current,
+                    upsample=True,
+                )
+            )
+            self.out_blocks.extend(
+                SparseResBlock3d(
+                    current * 2,
+                    config.model_channels,
+                    out_channels=current,
+                )
+                for _ in range(config.num_io_res_blocks - 1)
+            )
+        self.out_layer = SparseLinear(channels[0], config.out_channels)
+
+        self.initialize_weights()
+        if config.use_fp16:
+            self.convert_to_fp16()
+
+    def initialize_weights(self) -> None:
+        """Initialize linear, timestep, modulation, and output projections."""
+
+        def initialize_linear(module: nn.Module) -> None:
+            if isinstance(module, nn.Linear):
+                nn.init.xavier_uniform_(module.weight)
+                if module.bias is not None:
+                    nn.init.constant_(module.bias, 0)
+
+        self.apply(initialize_linear)
+        nn.init.normal_(self.t_embedder.mlp[0].weight, std=0.02)
+        nn.init.normal_(self.t_embedder.mlp[2].weight, std=0.02)
+        nn.init.constant_(self.adaLN_modulation[-1].weight, 0)
+        nn.init.constant_(self.adaLN_modulation[-1].bias, 0)
+        nn.init.constant_(self.out_layer.weight, 0)
+        nn.init.constant_(self.out_layer.bias, 0)
+
+    def convert_to_fp16(self) -> None:
+        """Convert the I/O and transformer torso to float16."""
+        self.input_blocks.apply(convert_module_to_f16)
+        self.blocks.apply(convert_module_to_f16)
+        self.out_blocks.apply(convert_module_to_f16)
+        self.dtype = torch.float16
+
+    def forward(
+        self, x: SparseTensor, timestep: torch.Tensor, cond: torch.Tensor
+    ) -> SparseTensor:
+        """Predict latent flow for sparse ``x`` under image ``cond``."""
+        if x.shape[0] != timestep.shape[0] or x.shape[0] != cond.shape[0]:
+            raise ValueError("sparse input, timestep, and condition batches must match")
+        if x.feats.shape[1] != self.config.in_channels:
+            raise ValueError(
+                f"expected {self.config.in_channels} input channels, "
+                f"got {x.feats.shape[1]}"
+            )
+        h = self.input_layer(x).type(self.dtype)
+        timestep_embedding = self.t_embedder(timestep)
+        convolution_embedding = timestep_embedding.to(self.dtype)
+        skips = []
+        for block in self.input_blocks:
+            h = block(h, convolution_embedding)
+            skips.append(h.feats)
+
+        modulation = self.adaLN_modulation(timestep_embedding).to(self.dtype)
+        context = cond.to(self.dtype)
+        for block in self.blocks:
+            h = block(h, modulation, context)
+
+        for block, skip in zip(self.out_blocks, reversed(skips)):
+            h = h.replace(torch.cat((h.feats, skip), dim=1))
+            h = block(h, convolution_embedding)
+        h = h.replace(F.layer_norm(h.feats, h.feats.shape[-1:]))
+        return self.out_layer(h.type(x.dtype))

sparc3d/nn/__init__.py

@@ -0,0 +1,5 @@
+"""Private neural network primitives for the sparse latent transformer."""
+
+from .norm import LayerNorm32
+
+__all__ = ["LayerNorm32"]

sparc3d/nn/norm.py

@@ -0,0 +1,17 @@
+"""Numerically stable normalization layers for the sparse transformer."""
+
+# Adapted from Microsoft TRELLIS under the MIT License.
+# Modified for SPARC3D to retain float32 layer normalization only.
+
+from __future__ import annotations
+
+import torch
+from torch import nn
+
+
+class LayerNorm32(nn.LayerNorm):
+    """Layer normalization with float32 statistics and input-dtype output."""
+
+    def forward(self, x: torch.Tensor) -> torch.Tensor:
+        """Normalize ``x`` in float32 and restore its dtype."""
+        return super().forward(x.float()).to(x.dtype)

sparc3d/nn/rope.py

@@ -0,0 +1,93 @@
+"""Spatial rotary position embedding shared by the sparse attention blocks."""
+
+# Adapted from Microsoft TRELLIS under the MIT License.
+# Modified for SPARC3D to retain long-grid frequency scaling only.
+
+from __future__ import annotations
+
+import math
+
+import torch
+from torch import nn
+
+
+class RotaryPositionEmbedder(nn.Module):
+    """Spatial rotary embedding with frequency scaling for long coordinate grids."""
+
+    def __init__(self, hidden_size: int, in_channels: int = 3):
+        """
+        Args:
+            hidden_size: Head dimension the rotation is applied over; must be even.
+            in_channels: Spatial coordinate axes sharing that dimension.
+
+        Raises:
+            ValueError: ``hidden_size`` is odd or too small to split across axes.
+        """
+        super().__init__()
+        if hidden_size % 2:
+            raise ValueError("hidden_size must be divisible by 2")
+        if hidden_size // in_channels // 2 == 0:
+            raise ValueError("hidden_size is too small for spatial RoPE")
+        self.hidden_size = hidden_size
+        self.in_channels = in_channels
+        self.freq_dim = hidden_size // in_channels // 2
+        freqs = torch.arange(self.freq_dim, dtype=torch.float32) / self.freq_dim
+        self.register_buffer("freqs", 1.0 / (10000**freqs), persistent=False)
+
+    @staticmethod
+    def _update_freqs(
+        freqs: torch.Tensor, train_length: int, infer_length: int
+    ) -> torch.Tensor:
+        wavelengths = freqs * train_length / (2 * math.pi)
+        threshold = 24
+        ratio = (wavelengths - 1) / (threshold - 1)
+        ratio = ratio + (1 - ratio) * train_length / infer_length
+        ratio = torch.where(wavelengths > threshold, 1.0, ratio)
+        ratio = torch.where(wavelengths < 1, train_length / infer_length, ratio)
+        return freqs * ratio
+
+    def _get_phases(self, indices: torch.Tensor) -> torch.Tensor:
+        max_length = int(indices.max().item())
+        if max_length < 64:
+            freqs = self.freqs
+        else:
+            freqs = self._update_freqs(
+                self.freqs, train_length=64, infer_length=(64 + max_length) // 2
+            )
+        phases = torch.outer(indices, freqs.to(indices.device))
+        return torch.polar(torch.ones_like(phases), phases)
+
+    @staticmethod
+    def _rotary_embedding(x: torch.Tensor, phases: torch.Tensor) -> torch.Tensor:
+        x_complex = torch.view_as_complex(x.float().reshape(*x.shape[:-1], -1, 2))
+        rotated = x_complex * phases.unsqueeze(1)
+        return torch.view_as_real(rotated).reshape(*rotated.shape[:-1], -1).to(x.dtype)
+
+    def forward(
+        self,
+        q: torch.Tensor,
+        k: torch.Tensor,
+        indices: torch.Tensor,
+    ) -> tuple[torch.Tensor, torch.Tensor]:
+        """Rotate queries and keys at ``indices``.
+
+        Args:
+            q: Queries ending in ``[H, D]``.
+            k: Keys with the same shape as ``q``.
+            indices: Spatial positions ending in three coordinates.
+
+        Returns:
+            Rotated queries and keys.
+        """
+        phases = self._get_phases(indices.reshape(-1)).reshape(*indices.shape[:-1], -1)
+        missing = self.hidden_size // 2 - phases.shape[-1]
+        if missing > 0:
+            padding = torch.polar(
+                torch.ones(*phases.shape[:-1], missing, device=phases.device),
+                torch.zeros(*phases.shape[:-1], missing, device=phases.device),
+            )
+            phases = torch.cat((phases, padding), dim=-1)
+        return (
+            self._rotary_embedding(q, phases),
+            self._rotary_embedding(k, phases),
+        )

sparc3d/nn/sparse/__init__.py

@@ -0,0 +1,14 @@
+"""Private sparse tensor and neural network operations."""
+
+from .basic import SparseTensor
+from .conv import SparseConv3d
+from .linear import SparseLinear
+from .spatial import SparseDownsample, SparseUpsample
+
+__all__ = [
+    "SparseConv3d",
+    "SparseDownsample",
+    "SparseLinear",
+    "SparseTensor",
+    "SparseUpsample",
+]

sparc3d/nn/sparse/attention/__init__.py

@@ -0,0 +1,5 @@
+"""Full flash attention over sparse variable-length sequences."""
+
+from .modules import SparseMultiHeadAttention
+
+__all__ = ["SparseMultiHeadAttention"]

sparc3d/nn/sparse/attention/full_attn.py

@@ -0,0 +1,77 @@
+"""Variable-length full flash attention for sparse feature sequences."""
+
+# Adapted from Microsoft TRELLIS under the MIT License.
+# Modified for SPARC3D: variable-length flash attention only.
+
+from __future__ import annotations
+
+import torch
+
+from ..basic import SparseTensor
+
+
+def _flash_attn():
+    """Import flash-attn when sparse attention is first executed."""
+    try:
+        import flash_attn
+    except ImportError as exc:
+        raise ImportError(
+            "Sparc3DTransformer attention requires flash-attn; "
+            "install sparc3d[inference]"
+        ) from exc
+    return flash_attn
+
+
+def _lengths(tensor: SparseTensor) -> list[int]:
+    return [span.stop - span.start for span in tensor.layout]
+
+
+def _cumulative(lengths: list[int], device: torch.device) -> torch.Tensor:
+    return torch.tensor(
+        [0, *lengths], device=device, dtype=torch.int32
+    ).cumsum(0, dtype=torch.int32)
+
+
+def sparse_scaled_dot_product_attention(
+    query: SparseTensor, kv: torch.Tensor | None = None
+) -> SparseTensor:
+    """Apply variable-length full flash attention over sparse queries.
+
+    Args:
+        query: Packed sparse ``qkv`` of shape ``[N, 3, H, D]`` for self-attention,
+            or sparse queries ``[N, H, D]`` when ``kv`` is given.
+        kv: Dense packed keys and values ``[B, L, 2, H, D]`` for cross-attention;
+            ``None`` selects self-attention over the packed ``query``.
+
+    Returns:
+        Sparse output over the query's coordinates.
+
+    Raises:
+        TypeError: ``query`` is not sparse.
+        ValueError: ``kv`` does not share the query's batch size.
+    """
+    flash_attn = _flash_attn()
+    if not isinstance(query, SparseTensor):
+        raise TypeError("Sparc3D sparse attention requires sparse queries")
+    query_lengths = _lengths(query)
+    cumulative_query = _cumulative(query_lengths, query.device)
+
+    if kv is None:
+        output = flash_attn.flash_attn_varlen_qkvpacked_func(
+            query.feats, cumulative_query, max(query_lengths)
+        )
+        return query.replace(output)
+
+    batch, length = kv.shape[:2]
+    if batch != query.shape[0]:
+        raise ValueError("query and context batch sizes must match")
+    key_lengths = [length] * batch
+    output = flash_attn.flash_attn_varlen_kvpacked_func(
+        query.feats,
+        kv.reshape(batch * length, *kv.shape[2:]),
+        cumulative_query,
+        _cumulative(key_lengths, query.device),
+        max(query_lengths),
+        max(key_lengths),
+    )
+    return query.replace(output)

sparc3d/nn/sparse/attention/modules.py

@@ -0,0 +1,123 @@
+"""Full multi-head attention over sparse variable-length batches."""
+
+# Adapted from Microsoft TRELLIS under the MIT License.
+# Modified for SPARC3D: full flash attention with spatial RoPE.
+
+from __future__ import annotations
+
+import torch
+import torch.nn.functional as F
+from torch import nn
+
+from ...rope import RotaryPositionEmbedder
+from ..basic import SparseTensor
+from .full_attn import sparse_scaled_dot_product_attention
+
+
+class SparseMultiHeadRMSNorm(nn.Module):
+    """Per-head RMS normalization of a ``[N, H, D]`` query or key projection."""
+
+    def __init__(self, dim: int, heads: int):
+        """
+        Args:
+            dim: Channels per head.
+            heads: Attention heads, each with its own gain.
+        """
+        super().__init__()
+        self.scale = dim**0.5
+        self.gamma = nn.Parameter(torch.ones(heads, dim))
+
+    def forward(self, x: torch.Tensor) -> torch.Tensor:
+        """Normalize the head dimension in float32 and restore ``x``'s dtype."""
+        return (F.normalize(x.float(), dim=-1) * self.gamma * self.scale).to(x.dtype)
+
+
+class SparseMultiHeadAttention(nn.Module):
+    """Full flash self- or cross-attention over sparse queries."""
+
+    def __init__(
+        self,
+        channels: int,
+        num_heads: int,
+        ctx_channels: int | None = None,
+        *,
+        attention_type: str = "self",
+    ):
+        """
+        Args:
+            channels: Query feature channels; must be divisible by ``num_heads``.
+            num_heads: Attention heads.
+            ctx_channels: Context channels for cross-attention; defaults to
+                ``channels``. Ignored for self-attention.
+            attention_type: ``"self"`` or ``"cross"``. Self-attention alone carries
+                rotary embeddings and query/key RMS normalization, matching the
+                parameters the released weights provide.
+
+        Raises:
+            ValueError: ``channels`` is not divisible by ``num_heads``, or
+                ``attention_type`` is not one of the two supported kinds.
+        """
+        super().__init__()
+        if channels % num_heads:
+            raise ValueError("channels must be divisible by num_heads")
+        if attention_type not in {"self", "cross"}:
+            raise ValueError("attention_type must be 'self' or 'cross'")
+        self.channels = channels
+        self.ctx_channels = ctx_channels or channels
+        self.num_heads = num_heads
+        self.head_dim = channels // num_heads
+        self._type = attention_type
+        if attention_type == "self":
+            self.to_qkv = nn.Linear(channels, channels * 3, bias=True)
+            # Self-attention alone is positional and query/key normalized; the
+            # released weights carry no RoPE or RMS parameters on the cross path.
+            self.q_rms_norm = SparseMultiHeadRMSNorm(self.head_dim, num_heads)
+            self.k_rms_norm = SparseMultiHeadRMSNorm(self.head_dim, num_heads)
+            self.rope = RotaryPositionEmbedder(self.head_dim)
+        else:
+            self.to_q = nn.Linear(channels, channels, bias=True)
+            self.to_kv = nn.Linear(self.ctx_channels, channels * 2, bias=True)
+        self.to_out = nn.Linear(channels, channels)
+
+    @staticmethod
+    def _linear(
+        module: nn.Linear, x: SparseTensor | torch.Tensor
+    ) -> SparseTensor | torch.Tensor:
+        if isinstance(x, SparseTensor):
+            return x.replace(module(x.feats))
+        return module(x)
+
+    def _fused_pre(
+        self, x: SparseTensor | torch.Tensor, count: int
+    ) -> SparseTensor | torch.Tensor:
+        if isinstance(x, SparseTensor):
+            return x.reshape(count, self.num_heads, self.head_dim)
+        return x.reshape(*x.shape[:2], count, self.num_heads, self.head_dim)
+
+    def forward(
+        self,
+        x: SparseTensor,
+        context: SparseTensor | torch.Tensor | None = None,
+    ) -> SparseTensor:
+        """Attend from sparse ``x`` to itself or dense ``context``."""
+        if self._type == "self":
+            qkv = self._fused_pre(self._linear(self.to_qkv, x), 3)
+            assert isinstance(qkv, SparseTensor)
+            q, k, v = qkv.feats.unbind(dim=1)
+            q, k = self.rope(q, k, qkv.coords[:, 1:])
+            q = self.q_rms_norm(q)
+            k = self.k_rms_norm(k)
+            qkv = qkv.replace(torch.stack((q, k, v), dim=1))
+            output = sparse_scaled_dot_product_attention(qkv)
+        else:
+            if context is None:
+                raise ValueError("cross-attention requires context")
+            query = self._linear(self.to_q, x)
+            assert isinstance(query, SparseTensor)
+            query = query.reshape(self.num_heads, self.head_dim)
+            kv = self._fused_pre(self._linear(self.to_kv, context), 2)
+            output = sparse_scaled_dot_product_attention(query, kv)
+        output = output.reshape(-1)
+        projected = self._linear(self.to_out, output)
+        assert isinstance(projected, SparseTensor)
+        return projected

sparc3d/nn/sparse/basic.py

@@ -0,0 +1,185 @@
+"""Private sparse tensor wrapper with contiguous batches and spatial caches."""
+
+# Adapted from Microsoft TRELLIS under the MIT License.
+# Modified for SPARC3D to use the local sparse backend and paired resampling cache.
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import Any
+
+import torch
+
+from sparc3d.ops import sparse_backend
+
+
+class SparseTensor:
+    """Sparse features with batch-first coordinates and shared spatial caches."""
+
+    def __init__(
+        self,
+        feats: torch.Tensor | None = None,
+        coords: torch.Tensor | None = None,
+        shape: torch.Size | None = None,
+        layout: list[slice] | None = None,
+        *,
+        data: Any | None = None,
+        scale: tuple[int, ...] = (1, 1, 1),
+        spatial_cache: dict[str, dict[str, Any]] | None = None,
+    ):
+        """
+        Args:
+            feats: Features ``[N, C]``, one row per occupied coordinate.
+            coords: Coordinates ``[N, 4]`` as ``(batch, x, y, z)``, sorted by batch.
+            shape: Logical shape; derived from ``coords`` and ``feats`` when omitted.
+            layout: Per-batch row slices; recomputed from ``coords`` when omitted.
+            data: Backend sparse tensor to adopt instead of ``feats`` and ``coords``.
+            scale: Cumulative downsampling factor relative to the original grid, so
+                ``(1, 1, 1)`` is the original resolution and each downsample
+                multiplies it. It also keys :attr:`_spatial_cache`, so it has to
+                differ between nesting levels.
+            spatial_cache: Cache shared with tensors over the same geometry, which is
+                how a downsample hands its inverse mapping to the paired upsample.
+
+        Raises:
+            ValueError: Both ``data`` and explicit features or coordinates were given,
+                either is missing, the shapes disagree, or the tensor would be empty.
+        """
+        if data is not None:
+            if feats is not None or coords is not None:
+                raise ValueError("provide either data or feats and coords")
+            feats = sparse_backend.get_feats(data)
+            coords = data.indices
+        if feats is None or coords is None:
+            raise ValueError("feats and coords are required")
+        if coords.ndim != 2 or coords.shape[1] != 4:
+            raise ValueError(f"expected coords [N, 4], got {tuple(coords.shape)}")
+        if feats.shape[0] != coords.shape[0]:
+            raise ValueError("features and coordinates must have the same row count")
+        if coords.shape[0] == 0:
+            raise ValueError("a SparseTensor cannot be empty")
+        self._feats = feats
+        self._coords = coords.int().contiguous()
+        self.data = data
+        batch_size = int(self._coords[:, 0].max().item()) + 1
+        self._shape = shape or torch.Size((batch_size, *feats.shape[1:]))
+        self._layout = layout or self._calculate_layout(self._coords, batch_size)
+        self._scale = tuple(scale)
+        self._spatial_cache = spatial_cache if spatial_cache is not None else {}
+        self._validate_layout()
+
+    @staticmethod
+    def _calculate_layout(coords: torch.Tensor, batch_size: int) -> list[slice]:
+        counts = torch.bincount(coords[:, 0].long(), minlength=batch_size)
+        offsets = torch.cumsum(counts, dim=0)
+        return [
+            slice(int(offsets[i] - counts[i]), int(offsets[i]))
+            for i in range(batch_size)
+        ]
+
+    def _validate_layout(self) -> None:
+        for batch, span in enumerate(self._layout):
+            if not torch.all(self._coords[span, 0] == batch):
+                raise ValueError("coordinates for each batch must be contiguous")
+
+    def backend_data(self) -> Any:
+        """Return the sparse-backend tensor, creating it lazily."""
+        if self.data is None:
+            self.data = sparse_backend.sparse_tensor(self._feats, self._coords)
+        return self.data
+
+    @property
+    def shape(self) -> torch.Size:
+        """Logical shape ``[B, *feature_shape]``."""
+        return self._shape
+
+    @property
+    def layout(self) -> list[slice]:
+        """Contiguous feature slice for each batch element."""
+        return self._layout
+
+    @property
+    def feats(self) -> torch.Tensor:
+        """Feature values in coordinate-row order."""
+        return self._feats
+
+    @property
+    def coords(self) -> torch.Tensor:
+        """Batch-first integer coordinates in ``[batch, x, y, z]`` order."""
+        return self._coords
+
+    @property
+    def dtype(self) -> torch.dtype:
+        """Feature dtype."""
+        return self.feats.dtype
+
+    @property
+    def device(self) -> torch.device:
+        """Feature device."""
+        return self.feats.device
+
+    @property
+    def scale(self) -> tuple[int, ...]:
+        """Current spatial scale tracked by paired resampling."""
+        return self._scale
+
+    def replace(self, feats: torch.Tensor) -> "SparseTensor":
+        """Return a tensor sharing coordinates and caches with new features."""
+        if feats.shape[0] != self.feats.shape[0]:
+            raise ValueError("replacement features must preserve the sparse row count")
+        data = None
+        if self.data is not None and feats.ndim == 2:
+            data = sparse_backend.replace_feats(self.data, feats)
+        return SparseTensor(
+            feats=feats if data is None else None,
+            coords=self.coords if data is None else None,
+            data=data,
+            shape=torch.Size((self.shape[0], *feats.shape[1:])),
+            layout=self.layout,
+            scale=self._scale,
+            spatial_cache=self._spatial_cache,
+        )
+
+    def reshape(self, *shape: int) -> "SparseTensor":
+        """Reshape feature dimensions while retaining the sparse coordinates."""
+        return self.replace(self.feats.reshape(self.feats.shape[0], *shape))
+
+    def type(self, dtype: torch.dtype) -> "SparseTensor":
+        """Cast features to ``dtype``."""
+        return self.replace(self.feats.to(dtype=dtype))
+
+    def register_spatial_cache(self, key: str, value: Any) -> None:
+        """Store ``value`` under ``key`` for the current scale."""
+        self._spatial_cache.setdefault(str(self._scale), {})[key] = value
+
+    def get_spatial_cache(self, key: str) -> Any | None:
+        """Return a cached value for the current scale."""
+        return self._spatial_cache.get(str(self._scale), {}).get(key)
+
+    def _elementwise(
+        self,
+        other: torch.Tensor | "SparseTensor" | float,
+        operation: Callable[[torch.Tensor, Any], torch.Tensor],
+    ) -> "SparseTensor":
+        if isinstance(other, SparseTensor):
+            if not torch.equal(self.coords, other.coords):
+                raise ValueError("sparse operands must have identical coordinates")
+            other = other.feats
+        elif isinstance(other, torch.Tensor) and other.ndim >= 1:
+            if other.shape[0] == self.shape[0] and other.shape != self.feats.shape:
+                other = sparse_batch_broadcast(self, other)
+        return self.replace(operation(self.feats, other))
+
+    def __add__(self, other):
+        return self._elementwise(other, torch.add)
+
+    def __mul__(self, other):
+        return self._elementwise(other, torch.mul)
+
+
+def sparse_batch_broadcast(input: SparseTensor, other: torch.Tensor) -> torch.Tensor:
+    """Broadcast a batch-first tensor over sparse feature rows."""
+    output = torch.empty_like(input.feats)
+    for batch, span in enumerate(input.layout):
+        output[span] = other[batch]
+    return output

sparc3d/nn/sparse/conv.py

@@ -0,0 +1,88 @@
+"""Sparse submanifold convolution over spconv."""
+
+# Adapted from Microsoft TRELLIS under the MIT License.
+# Modified for SPARC3D to route convolution through ``ops.sparse_backend``.
+
+from __future__ import annotations
+
+import torch
+from torch import nn
+
+from sparc3d.ops import sparse_backend
+
+from .basic import SparseTensor
+
+
+class _DeferredConv3d(nn.Module):
+    """State-compatible placeholder used when spconv is not installed."""
+
+    def __init__(
+        self,
+        in_channels: int,
+        out_channels: int,
+        kernel_size: int,
+        bias: bool,
+    ):
+        super().__init__()
+        self.weight = nn.Parameter(
+            torch.empty(
+                out_channels,
+                kernel_size,
+                kernel_size,
+                kernel_size,
+                in_channels,
+            )
+        )
+        self.bias = nn.Parameter(torch.empty(out_channels)) if bias else None
+        nn.init.kaiming_uniform_(self.weight, a=5**0.5)
+        if self.bias is not None:
+            nn.init.zeros_(self.bias)
+
+    def forward(self, _input):
+        """Raise the deferred sparse-backend import error."""
+        raise ImportError("sparse convolution requires spconv")
+
+
+class SparseConv3d(nn.Module):
+    """Coordinate-preserving three-dimensional sparse convolution."""
+
+    _sparc3d_convertible = True
+
+    def __init__(
+        self,
+        in_channels: int,
+        out_channels: int,
+        kernel_size: int,
+        bias: bool = True,
+    ):
+        """
+        Args:
+            in_channels: Input feature channels.
+            out_channels: Output feature channels.
+            kernel_size: Cubic kernel extent.
+            bias: Add a bias term.
+        """
+        super().__init__()
+        try:
+            self.conv = sparse_backend.Conv3d(
+                in_channels,
+                out_channels,
+                kernel_size=kernel_size,
+                bias=bias,
+            )
+        except ImportError:
+            # Construction and state-dict validation must work without spconv.
+            # Forward still raises; this is not an inference fallback.
+            self.conv = _DeferredConv3d(in_channels, out_channels, kernel_size, bias)
+        self.out_channels = out_channels
+
+    def forward(self, x: SparseTensor) -> SparseTensor:
+        """Convolve ``x`` while preserving its coordinate lineage."""
+        output = self.conv(x.backend_data())
+        return SparseTensor(
+            data=output,
+            shape=x.shape[:1] + (self.out_channels,),
+            layout=x.layout,
+            scale=x.scale,
+            spatial_cache=x._spatial_cache,
+        )

sparc3d/nn/sparse/linear.py

@@ -0,0 +1,18 @@
+"""Linear projection over sparse feature rows."""
+
+# Adapted from Microsoft TRELLIS under the MIT License.
+# Modified for SPARC3D's private sparse tensor.
+
+from __future__ import annotations
+
+from torch import nn
+
+from .basic import SparseTensor
+
+
+class SparseLinear(nn.Linear):
+    """Linear layer preserving sparse coordinates and caches."""
+
+    def forward(self, input: SparseTensor) -> SparseTensor:
+        """Project ``input`` features."""
+        return input.replace(super().forward(input.feats))

sparc3d/nn/sparse/nonlinearity.py

@@ -0,0 +1,18 @@
+"""Nonlinear activations over sparse feature rows."""
+
+# Adapted from Microsoft TRELLIS under the MIT License.
+# Modified for SPARC3D to retain GELU only.
+
+from __future__ import annotations
+
+from torch import nn
+
+from .basic import SparseTensor
+
+
+class SparseGELU(nn.GELU):
+    """GELU activation preserving sparse coordinates and caches."""
+
+    def forward(self, input: SparseTensor) -> SparseTensor:
+        """Activate ``input`` features."""
+        return input.replace(super().forward(input.feats))

sparc3d/nn/sparse/spatial.py

@@ -0,0 +1,125 @@
+"""Paired average downsampling and cached nearest-neighbor upsampling."""
+
+# Adapted from Microsoft TRELLIS under the MIT License.
+# Modified for SPARC3D to retain only paired downsample and upsample operations.
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+
+import torch
+from torch import nn
+
+from .basic import SparseTensor
+
+
+def _factor_tuple(factor: int | Sequence[int], dimensions: int) -> tuple[int, ...]:
+    values = tuple(factor) if isinstance(factor, Sequence) else (factor,) * dimensions
+    if len(values) != dimensions or any(value <= 0 for value in values):
+        raise ValueError("factor must provide one positive value per spatial dimension")
+    return values
+
+
+class SparseDownsample(nn.Module):
+    """Average features that collapse onto the same downsampled coordinate."""
+
+    def __init__(self, factor: int | Sequence[int]):
+        """
+        Args:
+            factor: Per-axis downsampling factor, or one factor for every axis.
+        """
+        super().__init__()
+        self.factor = tuple(factor) if isinstance(factor, Sequence) else factor
+
+    def forward(self, input: SparseTensor) -> SparseTensor:
+        """Downsample ``input`` and register the inverse mapping."""
+        dimensions = input.coords.shape[-1] - 1
+        factor = _factor_tuple(self.factor, dimensions)
+        coordinate_columns = list(input.coords.unbind(dim=-1))
+        for axis, value in enumerate(factor):
+            coordinate_columns[axis + 1] = coordinate_columns[axis + 1] // value
+
+        extents = [
+            int(coordinate_columns[axis + 1].max().item()) + 1
+            for axis in range(dimensions)
+        ]
+        offsets = torch.cumprod(torch.tensor(extents[::-1]), 0).tolist()[::-1] + [1]
+        codes = sum(
+            coordinate * offset
+            for coordinate, offset in zip(coordinate_columns, offsets)
+        )
+        unique_codes, inverse = codes.unique(return_inverse=True)
+        new_feats = torch.scatter_reduce(
+            torch.zeros(
+                unique_codes.shape[0],
+                input.feats.shape[1],
+                device=input.device,
+                dtype=input.dtype,
+            ),
+            dim=0,
+            index=inverse[:, None].expand(-1, input.feats.shape[1]),
+            src=input.feats,
+            reduce="mean",
+        )
+        new_coords = torch.stack(
+            [unique_codes // offsets[0]]
+            + [
+                (unique_codes // offsets[axis + 1]) % extents[axis]
+                for axis in range(dimensions)
+            ],
+            dim=-1,
+        )
+        output = SparseTensor(
+            new_feats,
+            new_coords,
+            shape=input.shape,
+            scale=tuple(scale * value for scale, value in zip(input.scale, factor)),
+            spatial_cache=input._spatial_cache,
+        )
+        output.register_spatial_cache(f"upsample_{factor}_coords", input.coords)
+        output.register_spatial_cache(f"upsample_{factor}_layout", input.layout)
+        output.register_spatial_cache(f"upsample_{factor}_idx", inverse)
+        return output
+
+
+class SparseUpsample(nn.Module):
+    """Restore coordinates from a paired downsample cache."""
+
+    def __init__(self, factor: int | Sequence[int]):
+        """
+        Args:
+            factor: Per-axis factor, matching the paired :class:`SparseDownsample`.
+        """
+        super().__init__()
+        self.factor = tuple(factor) if isinstance(factor, Sequence) else factor
+
+    def forward(self, input: SparseTensor) -> SparseTensor:
+        """Upsample ``input`` through the recorded inverse mapping.
+
+        Raises:
+            ValueError: ``input`` is not at a scale this factor could have produced,
+                or no paired :class:`SparseDownsample` registered a cache for it.
+        """
+        dimensions = input.coords.shape[-1] - 1
+        factor = _factor_tuple(self.factor, dimensions)
+        if any(scale % value for scale, value in zip(input.scale, factor)):
+            raise ValueError(
+                f"cannot upsample by {factor} from scale {input.scale}; "
+                "SparseUpsample must mirror its paired SparseDownsample"
+            )
+        coords = input.get_spatial_cache(f"upsample_{factor}_coords")
+        layout = input.get_spatial_cache(f"upsample_{factor}_layout")
+        inverse = input.get_spatial_cache(f"upsample_{factor}_idx")
+        if coords is None or layout is None or inverse is None:
+            raise ValueError(
+                "upsample cache not found; SparseUpsample must follow its "
+                "paired SparseDownsample"
+            )
+        return SparseTensor(
+            input.feats[inverse],
+            coords,
+            shape=input.shape,
+            layout=layout,
+            scale=tuple(scale // value for scale, value in zip(input.scale, factor)),
+            spatial_cache=input._spatial_cache,
+        )

sparc3d/nn/sparse/transformer/__init__.py

@@ -0,0 +1,5 @@
+"""Transformer blocks over private sparse tensors."""
+
+from .modulated import ModulatedSparseTransformerCrossBlock
+
+__all__ = ["ModulatedSparseTransformerCrossBlock"]

sparc3d/nn/sparse/transformer/blocks.py

@@ -0,0 +1,34 @@
+"""Feed-forward building block for the sparse transformer."""
+
+# Adapted from Microsoft TRELLIS under the MIT License.
+# Modified for SPARC3D to retain the sparse feed-forward path only.
+
+from __future__ import annotations
+
+from torch import nn
+
+from ..basic import SparseTensor
+from ..linear import SparseLinear
+from ..nonlinearity import SparseGELU
+
+
+class SparseFeedForwardNet(nn.Module):
+    """Two-layer sparse MLP with tanh-approximated GELU."""
+
+    def __init__(self, channels: int, mlp_ratio: float = 4.0):
+        """
+        Args:
+            channels: Input and output channels.
+            mlp_ratio: Hidden width as a multiple of ``channels``.
+        """
+        super().__init__()
+        hidden_channels = int(channels * mlp_ratio)
+        self.mlp = nn.Sequential(
+            SparseLinear(channels, hidden_channels),
+            SparseGELU(approximate="tanh"),
+            SparseLinear(hidden_channels, channels),
+        )
+
+    def forward(self, x: SparseTensor) -> SparseTensor:
+        """Transform sparse features with the MLP."""
+        return self.mlp(x)

sparc3d/nn/sparse/transformer/modulated.py

@@ -0,0 +1,65 @@
+"""Shared-modulation sparse transformer cross-attention block."""
+
+# Adapted from Microsoft TRELLIS under the MIT License.
+# Modified for SPARC3D: shared timestep modulation with full attention.
+
+from __future__ import annotations
+
+import torch
+from torch import nn
+
+from ...norm import LayerNorm32
+from ..attention import SparseMultiHeadAttention
+from ..basic import SparseTensor
+from .blocks import SparseFeedForwardNet
+
+
+class ModulatedSparseTransformerCrossBlock(nn.Module):
+    """Sparse self/cross-attention block with shared adaptive normalization."""
+
+    def __init__(
+        self,
+        channels: int,
+        ctx_channels: int,
+        num_heads: int,
+        mlp_ratio: float = 4.0,
+    ):
+        super().__init__()
+        self.norm1 = LayerNorm32(channels, elementwise_affine=False, eps=1e-6)
+        self.norm2 = LayerNorm32(channels, elementwise_affine=True, eps=1e-6)
+        self.norm3 = LayerNorm32(channels, elementwise_affine=False, eps=1e-6)
+        self.self_attn = SparseMultiHeadAttention(
+            channels,
+            num_heads,
+            attention_type="self",
+        )
+        self.cross_attn = SparseMultiHeadAttention(
+            channels,
+            num_heads,
+            ctx_channels=ctx_channels,
+            attention_type="cross",
+        )
+        self.mlp = SparseFeedForwardNet(channels, mlp_ratio)
+        self.modulation = nn.Parameter(torch.randn(1, 6 * channels) / channels**0.5)
+
+    def forward(
+        self, x: SparseTensor, mod: torch.Tensor, context: torch.Tensor
+    ) -> SparseTensor:
+        """Transform ``x`` with timestep modulation and image context."""
+        (
+            shift_msa,
+            scale_msa,
+            gate_msa,
+            shift_mlp,
+            scale_mlp,
+            gate_mlp,
+        ) = (self.modulation + mod).chunk(6, dim=1)
+        h = x.replace(self.norm1(x.feats))
+        h = h * (1 + scale_msa) + shift_msa
+        h = self.self_attn(h) * gate_msa
+        x = x + h
+        h = x.replace(self.norm2(x.feats))
+        x = x + self.cross_attn(h, context)
+        h = x.replace(self.norm3(x.feats))
+        h = h * (1 + scale_mlp) + shift_mlp
+        return x + self.mlp(h) * gate_mlp

sparc3d/nn/utils.py

@@ -0,0 +1,29 @@
+"""Parameter precision and initialization helpers for neural network modules."""
+
+# Adapted from Microsoft TRELLIS under the MIT License.
+# Modified for SPARC3D to retain the sparse-transformer precision closure.
+
+from __future__ import annotations
+
+from torch import nn
+
+
+def _is_convertible(module: nn.Module) -> bool:
+    return isinstance(module, (nn.Conv1d, nn.Conv2d, nn.Conv3d, nn.Linear)) or bool(
+        getattr(module, "_sparc3d_convertible", False)
+    )
+
+
+def convert_module_to_f16(module: nn.Module) -> None:
+    """Convert primitive module parameters to float16."""
+    if _is_convertible(module):
+        recurse = bool(getattr(module, "_sparc3d_convertible", False))
+        for parameter in module.parameters(recurse=recurse):
+            parameter.data = parameter.data.half()
+
+
+def zero_module(module: nn.Module) -> nn.Module:
+    """Zero ``module`` parameters and return the module."""
+    for parameter in module.parameters():
+        parameter.detach().zero_()
+    return module

sparc3d/ops/__init__.py

@@ -0,0 +1,8 @@
+"""Public GPU operations backed by Triton kernels."""
+
+from sparc3d.ops.voxelize import MeshVoxelizer, adaptive_vox
+
+__all__ = [
+    "MeshVoxelizer",
+    "adaptive_vox",
+]

sparc3d/ops/_triton.py

@@ -0,0 +1,21 @@
+"""Lazy loader for the Triton operation backend."""
+
+from __future__ import annotations
+
+from types import ModuleType
+
+
+def load_triton_ops() -> ModuleType:
+    """Import and return ``sparc3d.ops.triton``, or raise a clear ``ImportError``.
+
+    Raises:
+        ImportError: Triton is unavailable in the running environment.
+    """
+    try:
+        from sparc3d.ops import triton as triton_ops
+    except ImportError as exc:
+        raise ImportError(
+            "The SPARC3D operations require Triton. Install the verified Linux "
+            "CUDA PyTorch stack, which supplies it."
+        ) from exc
+    return triton_ops

sparc3d/ops/flexicubes/LICENSE.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.

sparc3d/ops/flexicubes/__init__.py

@@ -0,0 +1,12 @@
+"""
+Vendored FlexiCubes isosurface extractor.
+
+Vendored from `nv-tlabs/FlexiCubes <https://github.com/nv-tlabs/FlexiCubes>`_ and
+distributed under the Apache License 2.0 in ``LICENSE.txt``. The modifications
+this package makes are listed in the header of ``flexicubes.py`` and marked at
+each site.
+"""
+
+from sparc3d.ops.flexicubes.flexicubes import FlexiCubes
+
+__all__ = ["FlexiCubes"]

sparc3d/ops/flexicubes/flexicubes.py

@@ -0,0 +1,349 @@
+# Copyright (c) 2025 NVIDIA CORPORATION & AFFILIATES.
+# All rights reserved.
+#
+# 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.
+#
+# This file has been modified from nv-tlabs/FlexiCubes. Every change is marked
+# below with a "SPARC3D modification" comment. In summary:
+#
+#   * sparse cube indexing -- ``_get_case_id_sparse`` resolves the ambiguous DMC
+#     configurations through an explicit ``cube_index_map`` instead of scanning a
+#     dense ``res x res x res`` array, so the extractor never materializes the
+#     full grid;
+#   * lookup tables and index tensors are int32 rather than int64;
+#   * ``__call__`` takes a ``dtype`` so the extractor can run in half precision;
+#   * the quadrilateral winding fix is out-of-place (``torch.cat``) instead of
+#     masked in-place assignment;
+#   * removed upstream code that this inference-only package never reaches: the
+#     ``construct_voxel_grid`` dense grid builder, ``_tetrahedralize`` and the
+#     ``output_tetmesh`` output mode, the ``grad_func`` gradient path, the dense
+#     ``_get_case_id`` superseded by ``_get_case_id_sparse``, the unused
+#     ``_solve_vd_QEF`` dual-vertex solver, the ``L_dev`` developability
+#     regularizer, and the differentiable ``training`` quad-splitting branch;
+#   * removed the learned per-cube weights ``alpha``/``beta``/``gamma_f`` and the
+#     ``weight_scale`` that normalizes them. They are trainable features of the
+#     upstream extractor and no released checkpoint carries them, so the
+#     inference path always passed ``None`` and ``_normalize_weights`` always
+#     returned tensors of ones. Folding those ones through leaves plain linear
+#     interpolation, an unweighted mean over each dual vertex, and the fixed
+#     ``quad_split_2`` triangulation of every quadrilateral. The float32
+#     accumulation the all-ones weights used to force is kept explicitly, so
+#     half-precision inputs still reduce in float32;
+#   * ``cube_index_map`` is required rather than defaulting to ``None``, and the
+#     unread ``cube_corners`` table is dropped.
+"""FlexiCubes dual marching cubes extractor with sparse cube indexing."""
+
+import torch
+
+# SPARC3D modification: relative import, since the tables live in this package.
+from .tables import *
+
+__all__ = [
+    'FlexiCubes'
+]
+
+
+class FlexiCubes:
+    """Dual marching cubes extractor over a sparse set of occupied cubes."""
+
+    # SPARC3D modification: every table below is int32 rather than upstream's int64.
+    def __init__(self, device="cuda"):
+        """
+        Args:
+            device: Device the lookup tables are allocated on. Inputs to
+                :meth:`__call__` must live on the same device.
+        """
+        self.device = device
+        self.dmc_table = torch.tensor(dmc_table, dtype=torch.int32, device=device, requires_grad=False)
+        self.num_vd_table = torch.tensor(num_vd_table,
+                                         dtype=torch.int32, device=device, requires_grad=False)
+        self.check_table = torch.tensor(
+            check_table,
+            dtype=torch.int32, device=device, requires_grad=False)
+
+        self.quad_split_2 = torch.tensor([0, 1, 3, 3, 1, 2], dtype=torch.int32, device=device, requires_grad=False)
+
+        self.cube_corners_idx = torch.pow(2, torch.arange(8, dtype=torch.int32, requires_grad=False))
+        self.cube_edges = torch.tensor([0, 1, 1, 5, 4, 5, 0, 4, 2, 3, 3, 7, 6, 7, 2, 6,
+                                       2, 0, 3, 1, 7, 5, 6, 4], dtype=torch.int32, device=device, requires_grad=False)
+
+    # SPARC3D modification: renamed arguments, added dtype and cube_index_map, and
+    # dropped upstream's output_tetmesh and grad_func. Extracts a triangle mesh from the
+    # sparse scalar field; returns (vertices, faces).
+    def __call__(self, voxelgrid_vertices, scalar_field, cube_idx, resolution,
+                 cube_index_map, dtype=None): # dtype so that it can work with half precision.
+        """Extract a triangle mesh from a sparse signed scalar field.
+
+        Args:
+            voxelgrid_vertices: Cube-corner positions ``[V, 3]``.
+            scalar_field: Signed value at each corner ``[V]``; the surface is its
+                zero level set.
+            cube_idx: Corner indices of each occupied cube ``[C, 8]``.
+            resolution: Grid resolution the cube indices are expressed in.
+            cube_index_map: Integer grid coordinate of each cube ``[C, 3]``, used to
+                resolve ambiguous configurations against neighbours. Required: the
+                sparse case-id path indexes it directly, so omitting it fails only
+                once a mesh happens to contain an ambiguous cube.
+            dtype: Float dtype to unify inputs to, e.g. ``torch.float16``. Inferred
+                from ``voxelgrid_vertices`` when ``None``, defaulting to float32.
+
+        Returns:
+            ``(vertices, faces)``, both empty when no cube straddles the surface.
+        """
+        # unify floating tensors to a chosen dtype, so it can work with half, etc:
+        if dtype is None:
+            if voxelgrid_vertices.dtype in (torch.float16, torch.bfloat16, torch.float32, torch.float64):
+                dtype = voxelgrid_vertices.dtype
+            else:
+                dtype = torch.float32
+
+        # cast all to dtype, so that it works with half-precision:
+        voxelgrid_vertices = voxelgrid_vertices.to(dtype)  # Cast the geometry to the chosen dtype
+        scalar_field = scalar_field.to(dtype)
+
+        surf_cubes, occ_fx8 = self._identify_surf_cubes(scalar_field, cube_idx)
+        if surf_cubes.sum() == 0:
+            return (
+                torch.zeros((0, 3), device=self.device, dtype=dtype),
+                torch.zeros((0, 3), dtype=torch.int32, device=self.device),
+            )
+
+        case_ids = self._get_case_id_sparse(occ_fx8, surf_cubes, resolution, cube_index_map)
+        
+        surf_edges, idx_map, edge_counts, surf_edges_mask = self._identify_surf_edges(
+            scalar_field, cube_idx, surf_cubes
+        )
+
+        vd, vd_idx_map = self._compute_vd(
+            voxelgrid_vertices, surf_edges, scalar_field, case_ids, idx_map)
+
+        return self._triangulate(
+            scalar_field, surf_edges, vd, edge_counts, idx_map,
+            vd_idx_map, surf_edges_mask)
+
+    # SPARC3D modification: sparse replacement for _get_case_id. Upstream builds a
+    # dense res^3 x 5 array to look up the configuration of adjacent cubes; this
+    # version sorts the occupied cube keys and binary-searches them instead, so
+    # cost scales with the number of surface cubes rather than with res^3.
+    @torch.no_grad()
+    def _get_case_id_sparse(self, occ_fx8, surf_cubes, res, cube_index_map):
+        """
+        Obtains the ID of topology cases based on cell corner occupancy. This function resolves the 
+        ambiguity in the Dual Marching Cubes (DMC) configurations as described in Section 1.3 of the 
+        supplementary material.
+        """
+        occ_int = occ_fx8[surf_cubes].to(torch.int32)  # Convert boolean to int32
+        corners_idx = self.cube_corners_idx.to(self.device).unsqueeze(0)
+        case_ids = (occ_int * corners_idx).sum(-1, dtype=torch.int32) # int32 else sum defaults to int64 by default
+        problem_config = self.check_table.to(self.device)[case_ids]
+        to_check = problem_config[..., 0] == 1
+        
+        problem_config = problem_config[to_check]
+        problem_config_index = cube_index_map[surf_cubes][to_check]
+
+        # SPARC3D modification: an ambiguous cube is resolved against its neighbour, which
+        # upstream looks up in a dense res^3 array of per-cube configurations. Here the
+        # neighbour is found by binary-searching the sorted keys of the occupied cubes
+        # below, so no dense volume is ever allocated.
+        vol_idx = cube_index_map  # N, 3
+        vol_idx_problem = vol_idx[surf_cubes][to_check]
+        
+        vol_idx_problem_adj = vol_idx_problem + problem_config[..., 1:4]
+
+        within_range = (
+            vol_idx_problem_adj[..., 0] >= 0) & (
+            vol_idx_problem_adj[..., 0] < res) & (
+            vol_idx_problem_adj[..., 1] >= 0) & (
+            vol_idx_problem_adj[..., 1] < res) & (
+            vol_idx_problem_adj[..., 2] >= 0) & (
+            vol_idx_problem_adj[..., 2] < res)
+
+        vol_idx_problem = vol_idx_problem[within_range]
+        vol_idx_problem_adj = vol_idx_problem_adj[within_range]
+        problem_config = problem_config[within_range]
+        problem_config_index = problem_config_index[within_range]
+
+        if problem_config.shape[0] == 0:
+            return case_ids
+
+        inverse_keys = (
+            (vol_idx_problem_adj[..., 0].long() * res
+             + vol_idx_problem_adj[..., 1].long()) * res
+            + vol_idx_problem_adj[..., 2].long()
+        )
+        problem_keys = (
+            (problem_config_index[..., 0].long() * res
+             + problem_config_index[..., 1].long()) * res
+            + problem_config_index[..., 2].long()
+        )
+        sorted_keys, sorted_order = torch.sort(problem_keys)
+        positions = torch.searchsorted(sorted_keys, inverse_keys)
+        bounded_positions = positions.clamp(max=sorted_keys.shape[0] - 1)
+        found = (positions < sorted_keys.shape[0]) & (
+            sorted_keys[bounded_positions] == inverse_keys
+        )
+        inverse_indices = torch.full_like(positions, -1, dtype=torch.long)
+        inverse_indices[found] = sorted_order[bounded_positions[found]]
+        problem_config = torch.cat(
+            (
+                problem_config,
+                torch.zeros(
+                    (1, 5),
+                    dtype=problem_config.dtype,
+                    device=problem_config.device,
+                ),
+            )
+        )
+        problem_config_adj = problem_config[inverse_indices]
+
+        # If two cubes with cases C16 and C19 share an ambiguous face, both cases are inverted.
+        to_invert = (problem_config_adj[..., 0] == 1)
+        idx = torch.arange(case_ids.shape[0], dtype=torch.int32, device=self.device)[to_check][within_range][to_invert]
+        case_ids.index_put_((idx,), problem_config[:-1][to_invert][..., -1])
+
+        return case_ids
+    
+
+    @torch.no_grad()
+    def _identify_surf_edges(self, scalar_field, cube_idx, surf_cubes):
+        """
+        Identifies grid edges that intersect with the underlying surface by checking for opposite signs. As each edge 
+        can be shared by multiple cubes, this function also assigns a unique index to each surface-intersecting edge 
+        and marks the cube edges with this index.
+        """
+        occ_n = scalar_field < 0
+        all_edges = cube_idx[surf_cubes][:, self.cube_edges].reshape(-1, 2)
+        unique_edges, _idx_map, counts = torch.unique(all_edges, dim=0, return_inverse=True, return_counts=True)
+
+        unique_edges = unique_edges.int()
+        mask_edges = occ_n[unique_edges.reshape(-1)].reshape(-1, 2).sum(-1) == 1
+
+        surf_edges_mask = mask_edges[_idx_map]
+        counts = counts[_idx_map]
+
+        mapping = torch.ones((unique_edges.shape[0]), dtype=torch.int32, device=cube_idx.device) * -1
+        mapping[mask_edges] = torch.arange(mask_edges.sum(), dtype=torch.int32, device=cube_idx.device) # int32 else arrange defaults to int64
+        # Shaped as [number of cubes x 12 edges per cube]. This is later used to map a cube edge to the unique index
+        # for a surface-intersecting edge. Non-surface-intersecting edges are marked with -1.
+        idx_map = mapping[_idx_map]
+        surf_edges = unique_edges[mask_edges]
+        return surf_edges, idx_map, counts, surf_edges_mask
+
+    @torch.no_grad()
+    def _identify_surf_cubes(self, scalar_field, cube_idx):
+        """
+        Identifies grid cubes that intersect with the underlying surface by checking if the signs at 
+        all corners are not identical.
+        """
+        occ_n = scalar_field < 0
+        occ_fx8 = occ_n[cube_idx.reshape(-1)].reshape(-1, 8)
+        _occ_sum = torch.sum(occ_fx8, -1)
+        surf_cubes = (_occ_sum > 0) & (_occ_sum < 8)
+        return surf_cubes, occ_fx8
+
+    def _linear_interp(self, edges_weight, edges_x):
+        """
+        Computes the location of zero-crossings on 'edges_x' using linear interpolation with 'edges_weight'.
+        """
+        edge_dim = edges_weight.dim() - 2
+        assert edges_weight.shape[edge_dim] == 2
+        edges_weight = torch.cat([torch.index_select(input=edges_weight, index=torch.tensor(1, device=self.device), dim=edge_dim), -
+                                 torch.index_select(input=edges_weight, index=torch.tensor(0, device=self.device), dim=edge_dim)]
+                                 , edge_dim)
+        denominator = edges_weight.sum(edge_dim)
+        ue = (edges_x * edges_weight).sum(edge_dim) / denominator
+        return ue
+
+    def _compute_vd(self, voxelgrid_vertices, surf_edges, scalar_field,
+                    case_ids, idx_map):
+        """
+        Computes the location of dual vertices as described in Section 4.2
+        """
+        surf_edges_x = torch.index_select(input=voxelgrid_vertices, index=surf_edges.reshape(-1), dim=0).reshape(-1, 2, 3)
+        surf_edges_s = torch.index_select(input=scalar_field, index=surf_edges.reshape(-1), dim=0).reshape(-1, 2, 1)
+
+        idx_map = idx_map.reshape(-1, 12)
+        num_vd = torch.index_select(input=self.num_vd_table, index=case_ids, dim=0)
+        edge_group, edge_group_to_vd, edge_group_to_cube = [], [], []
+
+        total_num_vd = 0
+        vd_idx_map = torch.zeros((case_ids.shape[0], 12), dtype=torch.int64, device=self.device, requires_grad=False)
+
+        for num in torch.unique(num_vd):
+            cur_cubes = (num_vd == num)  # consider cubes with the same numbers of vd emitted (for batching)
+            curr_num_vd = cur_cubes.sum() * num
+            curr_edge_group = self.dmc_table[case_ids[cur_cubes], :num].reshape(-1, num * 7)
+            curr_edge_group_to_vd = torch.arange(
+                curr_num_vd, device=self.device).unsqueeze(-1).repeat(1, 7) + total_num_vd
+            total_num_vd += curr_num_vd
+            curr_edge_group_to_cube = torch.arange(idx_map.shape[0], device=self.device)[
+                cur_cubes].unsqueeze(-1).repeat(1, num * 7).reshape_as(curr_edge_group)
+
+            curr_mask = (curr_edge_group != -1)
+            edge_group.append(torch.masked_select(curr_edge_group, curr_mask))
+            edge_group_to_vd.append(torch.masked_select(curr_edge_group_to_vd.reshape_as(curr_edge_group), curr_mask))
+            edge_group_to_cube.append(torch.masked_select(curr_edge_group_to_cube, curr_mask))
+
+        edge_group = torch.cat(edge_group)
+        edge_group_to_vd = torch.cat(edge_group_to_vd)
+        edge_group_to_cube = torch.cat(edge_group_to_cube)
+
+        # SPARC3D modification: dual vertices accumulate in float32 even when the inputs
+        # are half. Averaging up to twelve edge crossings per vertex in half precision
+        # loses enough mantissa to move the surface visibly.
+        vd = torch.zeros((total_num_vd, 3), device=self.device, dtype=torch.float)
+        edges_per_vd = torch.zeros((total_num_vd, 1), device=self.device, dtype=torch.float)
+
+        idx_group = torch.gather(input=idx_map.reshape(-1), dim=0, index=edge_group_to_cube * 12 + edge_group)
+
+        x_group = torch.index_select(input=surf_edges_x, index=idx_group.reshape(-1), dim=0).reshape(-1, 2, 3)
+        s_group = torch.index_select(input=surf_edges_s, index=idx_group.reshape(-1), dim=0).reshape(-1, 2, 1)
+
+        ue_group = self._linear_interp(s_group.float(), x_group)
+
+        edges_per_vd = edges_per_vd.index_add_(
+            0, index=edge_group_to_vd, source=torch.ones_like(ue_group[:, :1]))
+        vd = vd.index_add_(0, index=edge_group_to_vd, source=ue_group) / edges_per_vd
+
+        v_idx = torch.arange(vd.shape[0], dtype=torch.int64, device=self.device)  # + total_num_vd
+        index = edge_group_to_cube * 12 + edge_group
+        vd_idx_map = (vd_idx_map.reshape(-1)).scatter(dim=0, index=index, src=v_idx[edge_group_to_vd])
+
+        return vd, vd_idx_map
+
+    # SPARC3D modification: every quadrilateral splits along the same fixed diagonal.
+    # Choosing per-quad between the two diagonals needs the learned gamma weights, which
+    # the released inference weights do not carry.
+    def _triangulate(self, scalar_field, surf_edges, vd, edge_counts, idx_map, vd_idx_map, surf_edges_mask):
+        """
+        Connects four neighboring dual vertices to form a quadrilateral. Each quadrilateral is then split
+        into two triangles along a fixed diagonal, as described in Section 4.3.
+        """
+        with torch.no_grad():
+            group_mask = (edge_counts == 4) & surf_edges_mask  # surface edges shared by 4 cubes.
+            group = idx_map.reshape(-1)[group_mask]
+            vd_idx = vd_idx_map[group_mask]
+            edge_indices, indices = torch.sort(group, stable=True)
+            indices = indices.to(torch.int32)
+            quad_vd_idx = vd_idx[indices].reshape(-1, 4).to(torch.int32)
+
+            # Ensure all face directions point towards the positive SDF to maintain consistent winding.
+            # SPARC3D modification: rebuilt out-of-place rather than by masked
+            # in-place assignment, which reorders the quadrilaterals.
+            s_edges = scalar_field[surf_edges[edge_indices.reshape(-1, 4)[:, 0]].reshape(-1)].reshape(-1, 2)
+            flip_mask = s_edges[:, 0] > 0
+            quad_vd_idx = torch.cat((quad_vd_idx[flip_mask][:, [0, 1, 3, 2]],
+                                     quad_vd_idx[~flip_mask][:, [2, 3, 1, 0]]))
+
+        faces = quad_vd_idx[:, self.quad_split_2].reshape(-1, 3)
+        return vd, faces

sparc3d/ops/flexicubes/tables.py

@@ -0,0 +1,546 @@
+# Copyright (c) 2025 NVIDIA CORPORATION & AFFILIATES.
+# All rights reserved.
+#
+# 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.
+#
+# Vendored from nv-tlabs/FlexiCubes. The surviving table data is unmodified.
+# SPARC3D modification: upstream's ``tet_table`` is dropped along with the
+# tetrahedral output mode that was its only consumer.
+"""Dual marching cubes lookup tables used by :class:`FlexiCubes`."""
+
+dmc_table = [
+[[-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1]],
+[[0, 3, 8, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1]],
+[[0, 1, 9, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1]],
+[[1, 3, 8, 9, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1]],
+[[4, 7, 8, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1]],
+[[0, 3, 4, 7, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1]],
+[[0, 1, 9, -1, -1, -1, -1], [4, 7, 8, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1]],
+[[1, 3, 4, 7, 9, -1, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1]],
+[[4, 5, 9, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1]],
+[[0, 3, 8, -1, -1, -1, -1], [4, 5, 9, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1]],
+[[0, 1, 4, 5, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1]],
+[[1, 3, 4, 5, 8, -1, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1]],
+[[5, 7, 8, 9, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1]],
+[[0, 3, 5, 7, 9, -1, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1]],
+[[0, 1, 5, 7, 8, -1, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1]],
+[[1, 3, 5, 7, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1]],
+[[2, 3, 11, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1]],
+[[0, 2, 8, 11, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1]],
+[[0, 1, 9, -1, -1, -1, -1], [2, 3, 11, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1]],
+[[1, 2, 8, 9, 11, -1, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1]],
+[[4, 7, 8, -1, -1, -1, -1], [2, 3, 11, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1]],
+[[0, 2, 4, 7, 11, -1, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1]],
+[[0, 1, 9, -1, -1, -1, -1], [4, 7, 8, -1, -1, -1, -1], [2, 3, 11, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1]],
+[[1, 2, 4, 7, 9, 11, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1]],
+[[4, 5, 9, -1, -1, -1, -1], [2, 3, 11, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1]],
+[[0, 2, 8, 11, -1, -1, -1], [4, 5, 9, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1]],
+[[0, 1, 4, 5, -1, -1, -1], [2, 3, 11, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1]],
+[[1, 2, 4, 5, 8, 11, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1]],
+[[5, 7, 8, 9, -1, -1, -1], [2, 3, 11, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1]],
+[[0, 2, 5, 7, 9, 11, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1]],
+[[0, 1, 5, 7, 8, -1, -1], [2, 3, 11, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1]],
+[[1, 2, 5, 7, 11, -1, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1]],
+[[1, 2, 10, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1]],
+[[0, 3, 8, -1, -1, -1, -1], [1, 2, 10, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1]],
+[[0, 2, 9, 10, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1]],
+[[2, 3, 8, 9, 10, -1, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1]],
+[[4, 7, 8, -1, -1, -1, -1], [1, 2, 10, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1]],
+[[0, 3, 4, 7, -1, -1, -1], [1, 2, 10, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1]],
+[[0, 2, 9, 10, -1, -1, -1], [4, 7, 8, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1]],
+[[2, 3, 4, 7, 9, 10, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1]],
+[[4, 5, 9, -1, -1, -1, -1], [1, 2, 10, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1]],
+[[0, 3, 8, -1, -1, -1, -1], [4, 5, 9, -1, -1, -1, -1], [1, 2, 10, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1]],
+[[0, 2, 4, 5, 10, -1, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1]],
+[[2, 3, 4, 5, 8, 10, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1]],
+[[5, 7, 8, 9, -1, -1, -1], [1, 2, 10, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1]],
+[[0, 3, 5, 7, 9, -1, -1], [1, 2, 10, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1]],
+[[0, 2, 5, 7, 8, 10, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1]],
+[[2, 3, 5, 7, 10, -1, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1]],
+[[1, 3, 10, 11, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1]],
+[[0, 1, 8, 10, 11, -1, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1]],
+[[0, 3, 9, 10, 11, -1, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1]],
+[[8, 9, 10, 11, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1]],
+[[4, 7, 8, -1, -1, -1, -1], [1, 3, 10, 11, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1]],
+[[0, 1, 4, 7, 10, 11, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1]],
+[[0, 3, 9, 10, 11, -1, -1], [4, 7, 8, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1]],
+[[4, 7, 9, 10, 11, -1, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1]],
+[[4, 5, 9, -1, -1, -1, -1], [1, 3, 10, 11, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1]],
+[[0, 1, 8, 10, 11, -1, -1], [4, 5, 9, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1]],
+[[0, 3, 4, 5, 10, 11, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1]],
+[[4, 5, 8, 10, 11, -1, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1]],
+[[5, 7, 8, 9, -1, -1, -1], [1, 3, 10, 11, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1]],
+[[0, 1, 5, 7, 9, 10, 11], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1]],
+[[0, 3, 5, 7, 8, 10, 11], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1]],
+[[5, 7, 10, 11, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1]],
+[[6, 7, 11, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1]],
+[[0, 3, 8, -1, -1, -1, -1], [6, 7, 11, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1]],
+[[0, 1, 9, -1, -1, -1, -1], [6, 7, 11, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1]],
+[[1, 3, 8, 9, -1, -1, -1], [6, 7, 11, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1]],
+[[4, 6, 8, 11, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1]],
+[[0, 3, 4, 6, 11, -1, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1]],
+[[0, 1, 9, -1, -1, -1, -1], [4, 6, 8, 11, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1]],
+[[1, 3, 4, 6, 9, 11, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1]],
+[[4, 5, 9, -1, -1, -1, -1], [6, 7, 11, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1]],
+[[0, 3, 8, -1, -1, -1, -1], [4, 5, 9, -1, -1, -1, -1], [6, 7, 11, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1]],
+[[0, 1, 4, 5, -1, -1, -1], [6, 7, 11, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1]],
+[[1, 3, 4, 5, 8, -1, -1], [6, 7, 11, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1]],
+[[5, 6, 8, 9, 11, -1, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1]],
+[[0, 3, 5, 6, 9, 11, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1]],
+[[0, 1, 5, 6, 8, 11, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1]],
+[[1, 3, 5, 6, 11, -1, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1]],
+[[2, 3, 6, 7, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1]],
+[[0, 2, 6, 7, 8, -1, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1]],
+[[0, 1, 9, -1, -1, -1, -1], [2, 3, 6, 7, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1]],
+[[1, 2, 6, 7, 8, 9, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1]],
+[[2, 3, 4, 6, 8, -1, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1]],
+[[0, 2, 4, 6, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1]],
+[[0, 1, 9, -1, -1, -1, -1], [2, 3, 4, 6, 8, -1, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1]],
+[[1, 2, 4, 6, 9, -1, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1]],
+[[4, 5, 9, -1, -1, -1, -1], [2, 3, 6, 7, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1]],
+[[0, 2, 6, 7, 8, -1, -1], [4, 5, 9, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1]],
+[[0, 1, 4, 5, -1, -1, -1], [2, 3, 6, 7, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1]],
+[[1, 2, 4, 5, 6, 7, 8], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1]],
+[[2, 3, 5, 6, 8, 9, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1]],
+[[0, 2, 5, 6, 9, -1, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1]],
+[[0, 1, 2, 3, 5, 6, 8], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1]],
+[[1, 2, 5, 6, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1]],
+[[1, 2, 10, -1, -1, -1, -1], [6, 7, 11, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1]],
+[[0, 3, 8, -1, -1, -1, -1], [1, 2, 10, -1, -1, -1, -1], [6, 7, 11, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1]],
+[[0, 2, 9, 10, -1, -1, -1], [6, 7, 11, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1]],
+[[2, 3, 8, 9, 10, -1, -1], [6, 7, 11, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1]],
+[[4, 6, 8, 11, -1, -1, -1], [1, 2, 10, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1]],
+[[0, 3, 4, 6, 11, -1, -1], [1, 2, 10, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1]],
+[[0, 2, 9, 10, -1, -1, -1], [4, 6, 8, 11, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1]],
+[[2, 3, 4, 6, 9, 10, 11], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1]],
+[[4, 5, 9, -1, -1, -1, -1], [1, 2, 10, -1, -1, -1, -1], [6, 7, 11, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1]],
+[[0, 3, 8, -1, -1, -1, -1], [4, 5, 9, -1, -1, -1, -1], [1, 2, 10, -1, -1, -1, -1], [6, 7, 11, -1, -1, -1, -1]],
+[[0, 2, 4, 5, 10, -1, -1], [6, 7, 11, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1]],
+[[2, 3, 4, 5, 8, 10, -1], [6, 7, 11, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1]],
+[[5, 6, 8, 9, 11, -1, -1], [1, 2, 10, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1]],
+[[0, 3, 5, 6, 9, 11, -1], [1, 2, 10, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1]],
+[[0, 2, 5, 6, 8, 10, 11], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1]],
+[[2, 3, 5, 6, 10, 11, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1]],
+[[1, 3, 6, 7, 10, -1, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1]],
+[[0, 1, 6, 7, 8, 10, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1]],
+[[0, 3, 6, 7, 9, 10, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1]],
+[[6, 7, 8, 9, 10, -1, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1]],
+[[1, 3, 4, 6, 8, 10, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1]],
+[[0, 1, 4, 6, 10, -1, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1]],
+[[0, 3, 4, 6, 8, 9, 10], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1]],
+[[4, 6, 9, 10, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1]],
+[[4, 5, 9, -1, -1, -1, -1], [1, 3, 6, 7, 10, -1, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1]],
+[[0, 1, 6, 7, 8, 10, -1], [4, 5, 9, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1]],
+[[0, 3, 4, 5, 6, 7, 10], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1]],
+[[4, 5, 6, 7, 8, 10, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1]],
+[[1, 3, 5, 6, 8, 9, 10], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1]],
+[[0, 1, 5, 6, 9, 10, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1]],
+[[0, 3, 8, -1, -1, -1, -1], [5, 6, 10, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1]],
+[[5, 6, 10, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1]],
+[[5, 6, 10, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1]],
+[[0, 3, 8, -1, -1, -1, -1], [5, 6, 10, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1]],
+[[0, 1, 9, -1, -1, -1, -1], [5, 6, 10, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1]],
+[[1, 3, 8, 9, -1, -1, -1], [5, 6, 10, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1]],
+[[4, 7, 8, -1, -1, -1, -1], [5, 6, 10, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1]],
+[[0, 3, 4, 7, -1, -1, -1], [5, 6, 10, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1]],
+[[0, 1, 9, -1, -1, -1, -1], [4, 7, 8, -1, -1, -1, -1], [5, 6, 10, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1]],
+[[1, 3, 4, 7, 9, -1, -1], [5, 6, 10, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1]],
+[[4, 6, 9, 10, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1]],
+[[0, 3, 8, -1, -1, -1, -1], [4, 6, 9, 10, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1]],
+[[0, 1, 4, 6, 10, -1, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1]],
+[[1, 3, 4, 6, 8, 10, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1]],
+[[6, 7, 8, 9, 10, -1, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1]],
+[[0, 3, 6, 7, 9, 10, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1]],
+[[0, 1, 6, 7, 8, 10, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1]],
+[[1, 3, 6, 7, 10, -1, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1]],
+[[2, 3, 11, -1, -1, -1, -1], [5, 6, 10, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1]],
+[[0, 2, 8, 11, -1, -1, -1], [5, 6, 10, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1]],
+[[0, 1, 9, -1, -1, -1, -1], [2, 3, 11, -1, -1, -1, -1], [5, 6, 10, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1]],
+[[1, 2, 8, 9, 11, -1, -1], [5, 6, 10, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1]],
+[[4, 7, 8, -1, -1, -1, -1], [2, 3, 11, -1, -1, -1, -1], [5, 6, 10, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1]],
+[[0, 2, 4, 7, 11, -1, -1], [5, 6, 10, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1]],
+[[0, 1, 9, -1, -1, -1, -1], [4, 7, 8, -1, -1, -1, -1], [2, 3, 11, -1, -1, -1, -1], [5, 6, 10, -1, -1, -1, -1]],
+[[1, 2, 4, 7, 9, 11, -1], [5, 6, 10, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1]],
+[[4, 6, 9, 10, -1, -1, -1], [2, 3, 11, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1]],
+[[0, 2, 8, 11, -1, -1, -1], [4, 6, 9, 10, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1]],
+[[0, 1, 4, 6, 10, -1, -1], [2, 3, 11, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1]],
+[[1, 2, 4, 6, 8, 10, 11], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1]],
+[[6, 7, 8, 9, 10, -1, -1], [2, 3, 11, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1]],
+[[0, 2, 6, 7, 9, 10, 11], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1]],
+[[0, 1, 6, 7, 8, 10, -1], [2, 3, 11, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1]],
+[[1, 2, 6, 7, 10, 11, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1]],
+[[1, 2, 5, 6, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1]],
+[[0, 3, 8, -1, -1, -1, -1], [1, 2, 5, 6, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1]],
+[[0, 2, 5, 6, 9, -1, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1]],
+[[2, 3, 5, 6, 8, 9, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1]],
+[[4, 7, 8, -1, -1, -1, -1], [1, 2, 5, 6, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1]],
+[[0, 3, 4, 7, -1, -1, -1], [1, 2, 5, 6, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1]],
+[[0, 2, 5, 6, 9, -1, -1], [4, 7, 8, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1]],
+[[2, 3, 4, 5, 6, 7, 9], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1]],
+[[1, 2, 4, 6, 9, -1, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1]],
+[[0, 3, 8, -1, -1, -1, -1], [1, 2, 4, 6, 9, -1, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1]],
+[[0, 2, 4, 6, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1]],
+[[2, 3, 4, 6, 8, -1, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1]],
+[[1, 2, 6, 7, 8, 9, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1]],
+[[0, 1, 2, 3, 6, 7, 9], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1]],
+[[0, 2, 6, 7, 8, -1, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1]],
+[[2, 3, 6, 7, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1]],
+[[1, 3, 5, 6, 11, -1, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1]],
+[[0, 1, 5, 6, 8, 11, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1]],
+[[0, 3, 5, 6, 9, 11, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1]],
+[[5, 6, 8, 9, 11, -1, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1]],
+[[4, 7, 8, -1, -1, -1, -1], [1, 3, 5, 6, 11, -1, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1]],
+[[0, 1, 4, 5, 6, 7, 11], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1]],
+[[0, 3, 5, 6, 9, 11, -1], [4, 7, 8, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1]],
+[[4, 5, 6, 7, 9, 11, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1]],
+[[1, 3, 4, 6, 9, 11, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1]],
+[[0, 1, 4, 6, 8, 9, 11], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1]],
+[[0, 3, 4, 6, 11, -1, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1]],
+[[4, 6, 8, 11, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1]],
+[[1, 3, 6, 7, 8, 9, 11], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1]],
+[[0, 1, 9, -1, -1, -1, -1], [6, 7, 11, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1]],
+[[0, 3, 6, 7, 8, 11, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1]],
+[[6, 7, 11, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1]],
+[[5, 7, 10, 11, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1]],
+[[0, 3, 8, -1, -1, -1, -1], [5, 7, 10, 11, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1]],
+[[0, 1, 9, -1, -1, -1, -1], [5, 7, 10, 11, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1]],
+[[1, 3, 8, 9, -1, -1, -1], [5, 7, 10, 11, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1]],
+[[4, 5, 8, 10, 11, -1, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1]],
+[[0, 3, 4, 5, 10, 11, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1]],
+[[0, 1, 9, -1, -1, -1, -1], [4, 5, 8, 10, 11, -1, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1]],
+[[1, 3, 4, 5, 9, 10, 11], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1]],
+[[4, 7, 9, 10, 11, -1, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1]],
+[[0, 3, 8, -1, -1, -1, -1], [4, 7, 9, 10, 11, -1, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1]],
+[[0, 1, 4, 7, 10, 11, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1]],
+[[1, 3, 4, 7, 8, 10, 11], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1]],
+[[8, 9, 10, 11, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1]],
+[[0, 3, 9, 10, 11, -1, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1]],
+[[0, 1, 8, 10, 11, -1, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1]],
+[[1, 3, 10, 11, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1]],
+[[2, 3, 5, 7, 10, -1, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1]],
+[[0, 2, 5, 7, 8, 10, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1]],
+[[0, 1, 9, -1, -1, -1, -1], [2, 3, 5, 7, 10, -1, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1]],
+[[1, 2, 5, 7, 8, 9, 10], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1]],
+[[2, 3, 4, 5, 8, 10, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1]],
+[[0, 2, 4, 5, 10, -1, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1]],
+[[0, 1, 9, -1, -1, -1, -1], [2, 3, 4, 5, 8, 10, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1]],
+[[1, 2, 4, 5, 9, 10, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1]],
+[[2, 3, 4, 7, 9, 10, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1]],
+[[0, 2, 4, 7, 8, 9, 10], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1]],
+[[0, 1, 2, 3, 4, 7, 10], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1]],
+[[4, 7, 8, -1, -1, -1, -1], [1, 2, 10, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1]],
+[[2, 3, 8, 9, 10, -1, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1]],
+[[0, 2, 9, 10, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1]],
+[[0, 1, 2, 3, 8, 10, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1]],
+[[1, 2, 10, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1]],
+[[1, 2, 5, 7, 11, -1, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1]],
+[[0, 3, 8, -1, -1, -1, -1], [1, 2, 5, 7, 11, -1, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1]],
+[[0, 2, 5, 7, 9, 11, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1]],
+[[2, 3, 5, 7, 8, 9, 11], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1]],
+[[1, 2, 4, 5, 8, 11, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1]],
+[[0, 1, 2, 3, 4, 5, 11], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1]],
+[[0, 2, 4, 5, 8, 9, 11], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1]],
+[[4, 5, 9, -1, -1, -1, -1], [2, 3, 11, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1]],
+[[1, 2, 4, 7, 9, 11, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1]],
+[[0, 3, 8, -1, -1, -1, -1], [1, 2, 4, 7, 9, 11, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1]],
+[[0, 2, 4, 7, 11, -1, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1]],
+[[2, 3, 4, 7, 8, 11, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1]],
+[[1, 2, 8, 9, 11, -1, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1]],
+[[0, 1, 2, 3, 9, 11, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1]],
+[[0, 2, 8, 11, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1]],
+[[2, 3, 11, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1]],
+[[1, 3, 5, 7, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1]],
+[[0, 1, 5, 7, 8, -1, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1]],
+[[0, 3, 5, 7, 9, -1, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1]],
+[[5, 7, 8, 9, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1]],
+[[1, 3, 4, 5, 8, -1, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1]],
+[[0, 1, 4, 5, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1]],
+[[0, 3, 4, 5, 8, 9, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1]],
+[[4, 5, 9, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1]],
+[[1, 3, 4, 7, 9, -1, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1]],
+[[0, 1, 4, 7, 8, 9, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1]],
+[[0, 3, 4, 7, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1]],
+[[4, 7, 8, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1]],
+[[1, 3, 8, 9, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1]],
+[[0, 1, 9, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1]],
+[[0, 3, 8, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1]],
+[[-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1]]
+]
+num_vd_table = [0, 1, 1, 1, 1, 1, 2, 1, 1, 2, 1, 1, 1, 1, 1, 1, 1, 1, 2, 1, 2, 1, 3, 1, 2, 2,
+2, 1, 2, 1, 2, 1, 1, 2, 1, 1, 2, 2, 2, 1, 2, 3, 1, 1, 2, 2, 1, 1, 1, 1, 1, 1, 2,
+1, 2, 1, 2, 2, 1, 1, 2, 1, 1, 1, 1, 2, 2, 2, 1, 1, 2, 1, 2, 3, 2, 2, 1, 1, 1, 1,
+1, 1, 2, 1, 1, 1, 2, 1, 2, 2, 2, 1, 1, 1, 1, 1, 2, 3, 2, 2, 2, 2, 2, 1, 3, 4, 2,
+2, 2, 2, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 2, 2, 1, 1, 1, 1, 2, 1, 1, 2, 2, 2, 2, 2,
+3, 2, 1, 2, 1, 1, 1, 1, 1, 1, 2, 2, 3, 2, 3, 2, 4, 2, 2, 2, 2, 1, 2, 1, 2, 1, 1,
+2, 1, 1, 2, 2, 2, 1, 1, 2, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 2, 1, 2, 1, 1, 1, 1, 1,
+1, 2, 1, 1, 1, 2, 2, 2, 1, 1, 2, 1, 1, 2, 1, 1, 1, 1, 1, 1, 1, 1, 2, 1, 1, 1, 2,
+1, 1, 1, 1, 2, 1, 1, 1, 1, 1, 2, 1, 1, 1, 1, 1, 2, 1, 2, 1, 1, 1, 1, 1, 1, 1, 1,
+1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 0]
+check_table = [
+[0, 0, 0, 0, 0],
+[0, 0, 0, 0, 0],
+[0, 0, 0, 0, 0],
+[0, 0, 0, 0, 0],
+[0, 0, 0, 0, 0],
+[0, 0, 0, 0, 0],
+[0, 0, 0, 0, 0],
+[0, 0, 0, 0, 0],
+[0, 0, 0, 0, 0],
+[0, 0, 0, 0, 0],
+[0, 0, 0, 0, 0],
+[0, 0, 0, 0, 0],
+[0, 0, 0, 0, 0],
+[0, 0, 0, 0, 0],
+[0, 0, 0, 0, 0],
+[0, 0, 0, 0, 0],
+[0, 0, 0, 0, 0],
+[0, 0, 0, 0, 0],
+[0, 0, 0, 0, 0],
+[0, 0, 0, 0, 0],
+[0, 0, 0, 0, 0],
+[0, 0, 0, 0, 0],
+[0, 0, 0, 0, 0],
+[0, 0, 0, 0, 0],
+[0, 0, 0, 0, 0],
+[0, 0, 0, 0, 0],
+[0, 0, 0, 0, 0],
+[0, 0, 0, 0, 0],
+[0, 0, 0, 0, 0],
+[0, 0, 0, 0, 0],
+[0, 0, 0, 0, 0],
+[0, 0, 0, 0, 0],
+[0, 0, 0, 0, 0],
+[0, 0, 0, 0, 0],
+[0, 0, 0, 0, 0],
+[0, 0, 0, 0, 0],
+[0, 0, 0, 0, 0],
+[0, 0, 0, 0, 0],
+[0, 0, 0, 0, 0],
+[0, 0, 0, 0, 0],
+[0, 0, 0, 0, 0],
+[0, 0, 0, 0, 0],
+[0, 0, 0, 0, 0],
+[0, 0, 0, 0, 0],
+[0, 0, 0, 0, 0],
+[0, 0, 0, 0, 0],
+[0, 0, 0, 0, 0],
+[0, 0, 0, 0, 0],
+[0, 0, 0, 0, 0],
+[0, 0, 0, 0, 0],
+[0, 0, 0, 0, 0],
+[0, 0, 0, 0, 0],
+[0, 0, 0, 0, 0],
+[0, 0, 0, 0, 0],
+[0, 0, 0, 0, 0],
+[0, 0, 0, 0, 0],
+[0, 0, 0, 0, 0],
+[0, 0, 0, 0, 0],
+[0, 0, 0, 0, 0],
+[0, 0, 0, 0, 0],
+[0, 0, 0, 0, 0],
+[1, 1, 0, 0, 194],
+[1, -1, 0, 0, 193],
+[0, 0, 0, 0, 0],
+[0, 0, 0, 0, 0],
+[0, 0, 0, 0, 0],
+[0, 0, 0, 0, 0],
+[0, 0, 0, 0, 0],
+[0, 0, 0, 0, 0],
+[0, 0, 0, 0, 0],
+[0, 0, 0, 0, 0],
+[0, 0, 0, 0, 0],
+[0, 0, 0, 0, 0],
+[0, 0, 0, 0, 0],
+[0, 0, 0, 0, 0],
+[0, 0, 0, 0, 0],
+[0, 0, 0, 0, 0],
+[0, 0, 0, 0, 0],
+[0, 0, 0, 0, 0],
+[0, 0, 0, 0, 0],
+[0, 0, 0, 0, 0],
+[0, 0, 0, 0, 0],
+[0, 0, 0, 0, 0],
+[0, 0, 0, 0, 0],
+[0, 0, 0, 0, 0],
+[0, 0, 0, 0, 0],
+[0, 0, 0, 0, 0],
+[0, 0, 0, 0, 0],
+[0, 0, 0, 0, 0],
+[0, 0, 0, 0, 0],
+[0, 0, 0, 0, 0],
+[1, 0, 1, 0, 164],
+[0, 0, 0, 0, 0],
+[0, 0, 0, 0, 0],
+[1, 0, -1, 0, 161],
+[0, 0, 0, 0, 0],
+[0, 0, 0, 0, 0],
+[0, 0, 0, 0, 0],
+[0, 0, 0, 0, 0],
+[0, 0, 0, 0, 0],
+[0, 0, 0, 0, 0],
+[0, 0, 0, 0, 0],
+[0, 0, 0, 0, 0],
+[1, 0, 0, 1, 152],
+[0, 0, 0, 0, 0],
+[0, 0, 0, 0, 0],
+[0, 0, 0, 0, 0],
+[0, 0, 0, 0, 0],
+[0, 0, 0, 0, 0],
+[0, 0, 0, 0, 0],
+[1, 0, 0, 1, 145],
+[1, 0, 0, 1, 144],
+[0, 0, 0, 0, 0],
+[0, 0, 0, 0, 0],
+[0, 0, 0, 0, 0],
+[0, 0, 0, 0, 0],
+[0, 0, 0, 0, 0],
+[0, 0, 0, 0, 0],
+[1, 0, 0, -1, 137],
+[0, 0, 0, 0, 0],
+[0, 0, 0, 0, 0],
+[0, 0, 0, 0, 0],
+[1, 0, 1, 0, 133],
+[1, 0, 1, 0, 132],
+[1, 1, 0, 0, 131],
+[1, 1, 0, 0, 130],
+[0, 0, 0, 0, 0],
+[0, 0, 0, 0, 0],
+[0, 0, 0, 0, 0],
+[0, 0, 0, 0, 0],
+[0, 0, 0, 0, 0],
+[0, 0, 0, 0, 0],
+[0, 0, 0, 0, 0],
+[0, 0, 0, 0, 0],
+[0, 0, 0, 0, 0],
+[0, 0, 0, 0, 0],
+[0, 0, 0, 0, 0],
+[0, 0, 0, 0, 0],
+[0, 0, 0, 0, 0],
+[0, 0, 0, 0, 0],
+[0, 0, 0, 0, 0],
+[0, 0, 0, 0, 0],
+[0, 0, 0, 0, 0],
+[0, 0, 0, 0, 0],
+[0, 0, 0, 0, 0],
+[0, 0, 0, 0, 0],
+[0, 0, 0, 0, 0],
+[0, 0, 0, 0, 0],
+[0, 0, 0, 0, 0],
+[0, 0, 0, 0, 0],
+[0, 0, 0, 0, 0],
+[0, 0, 0, 0, 0],
+[0, 0, 0, 0, 0],
+[0, 0, 0, 0, 0],
+[0, 0, 0, 0, 0],
+[1, 0, 0, 1, 100],
+[0, 0, 0, 0, 0],
+[1, 0, 0, 1, 98],
+[0, 0, 0, 0, 0],
+[1, 0, 0, 1, 96],
+[0, 0, 0, 0, 0],
+[0, 0, 0, 0, 0],
+[0, 0, 0, 0, 0],
+[0, 0, 0, 0, 0],
+[0, 0, 0, 0, 0],
+[0, 0, 0, 0, 0],
+[0, 0, 0, 0, 0],
+[1, 0, 1, 0, 88],
+[0, 0, 0, 0, 0],
+[0, 0, 0, 0, 0],
+[0, 0, 0, 0, 0],
+[0, 0, 0, 0, 0],
+[0, 0, 0, 0, 0],
+[1, 0, -1, 0, 82],
+[0, 0, 0, 0, 0],
+[0, 0, 0, 0, 0],
+[0, 0, 0, 0, 0],
+[0, 0, 0, 0, 0],
+[0, 0, 0, 0, 0],
+[0, 0, 0, 0, 0],
+[0, 0, 0, 0, 0],
+[1, 0, 1, 0, 74],
+[0, 0, 0, 0, 0],
+[1, 0, 1, 0, 72],
+[0, 0, 0, 0, 0],
+[1, 0, 0, -1, 70],
+[0, 0, 0, 0, 0],
+[0, 0, 0, 0, 0],
+[1, -1, 0, 0, 67],
+[0, 0, 0, 0, 0],
+[1, -1, 0, 0, 65],
+[0, 0, 0, 0, 0],
+[0, 0, 0, 0, 0],
+[0, 0, 0, 0, 0],
+[0, 0, 0, 0, 0],
+[0, 0, 0, 0, 0],
+[0, 0, 0, 0, 0],
+[0, 0, 0, 0, 0],
+[0, 0, 0, 0, 0],
+[1, 1, 0, 0, 56],
+[0, 0, 0, 0, 0],
+[0, 0, 0, 0, 0],
+[0, 0, 0, 0, 0],
+[1, -1, 0, 0, 52],
+[0, 0, 0, 0, 0],
+[0, 0, 0, 0, 0],
+[0, 0, 0, 0, 0],
+[0, 0, 0, 0, 0],
+[0, 0, 0, 0, 0],
+[0, 0, 0, 0, 0],
+[0, 0, 0, 0, 0],
+[1, 1, 0, 0, 44],
+[0, 0, 0, 0, 0],
+[0, 0, 0, 0, 0],
+[0, 0, 0, 0, 0],
+[1, 1, 0, 0, 40],
+[0, 0, 0, 0, 0],
+[1, 0, 0, -1, 38],
+[1, 0, -1, 0, 37],
+[0, 0, 0, 0, 0],
+[0, 0, 0, 0, 0],
+[0, 0, 0, 0, 0],
+[1, 0, -1, 0, 33],
+[0, 0, 0, 0, 0],
+[0, 0, 0, 0, 0],
+[0, 0, 0, 0, 0],
+[0, 0, 0, 0, 0],
+[1, -1, 0, 0, 28],
+[0, 0, 0, 0, 0],
+[1, 0, -1, 0, 26],
+[1, 0, 0, -1, 25],
+[0, 0, 0, 0, 0],
+[0, 0, 0, 0, 0],
+[0, 0, 0, 0, 0],
+[0, 0, 0, 0, 0],
+[1, -1, 0, 0, 20],
+[0, 0, 0, 0, 0],
+[1, 0, -1, 0, 18],
+[0, 0, 0, 0, 0],
+[0, 0, 0, 0, 0],
+[0, 0, 0, 0, 0],
+[0, 0, 0, 0, 0],
+[0, 0, 0, 0, 0],
+[0, 0, 0, 0, 0],
+[0, 0, 0, 0, 0],
+[0, 0, 0, 0, 0],
+[1, 0, 0, -1, 9],
+[0, 0, 0, 0, 0],
+[0, 0, 0, 0, 0],
+[1, 0, 0, -1, 6],
+[0, 0, 0, 0, 0],
+[0, 0, 0, 0, 0],
+[0, 0, 0, 0, 0],
+[0, 0, 0, 0, 0],
+[0, 0, 0, 0, 0],
+[0, 0, 0, 0, 0]
+]

sparc3d/ops/sparse_backend.py

@@ -0,0 +1,288 @@
+"""Sparse-convolution primitives built on spconv."""
+
+from __future__ import annotations
+
+from math import prod
+from typing import Any, Optional, Tuple
+
+import torch
+from torch import nn
+
+_SPARSE_CONV_FLAG = "_sparc3d_sparse_conv"
+"""Instance attribute marking a module that consumes and returns a sparse tensor."""
+
+_SPCONV_INT32_BYTE_LIMIT = 2**31 - 1
+"""Largest input matrix spconv's implicit-GEMM indexing can address."""
+
+_spconv_conv_class: Optional[type] = None
+
+
+def _spconv():
+    """Import spconv's PyTorch namespace, with an actionable error if it is absent."""
+    try:
+        import spconv.pytorch as spconv
+    except ImportError as error:
+        raise ImportError(
+            "the sparse autoencoder needs spconv; install sparc3d[inference]"
+        ) from error
+    return spconv
+
+
+def _submanifold_conv_class() -> type:
+    """Build (once) a submanifold convolution that ignores autocast and preserves dtype.
+
+    The released weights require a convolution that returns whatever precision its input
+    features carry and casts its kernel to match, regardless of any enclosing autocast
+    context. Stock spconv does the opposite: it downcasts under autocast, and outside one
+    it has no kernel for half features at all. The subclass restores the required
+    behaviour, at the cost of running the GEMM in the weight's precision.
+    """
+    global _spconv_conv_class
+    if _spconv_conv_class is not None:
+        return _spconv_conv_class
+
+    spconv = _spconv()
+
+    class SubMConv3d(spconv.SubMConv3d):
+        def _large_forward(self, input: Any) -> Any:
+            """Evaluate a submanifold convolution without cumm's int32 GEMM limit."""
+            from spconv.pytorch import ops
+            from spconv.pytorch.core import IndiceData
+
+            indice_key = (
+                f"{self.indice_key}_large" if self.indice_key is not None else None
+            )
+            data = input.find_indice_pair(indice_key)
+            if data is None:
+                out_indices, pairs, pair_counts = ops.get_indice_pairs(
+                    input.indices,
+                    input.batch_size,
+                    input.spatial_shape,
+                    spconv.ConvAlgo.Native,
+                    self.kernel_size,
+                    self.stride,
+                    self.padding,
+                    self.dilation,
+                    self.output_padding,
+                    True,
+                    False,
+                )
+                data = IndiceData(
+                    out_indices,
+                    input.indices,
+                    pairs,
+                    pair_counts,
+                    input.spatial_shape,
+                    input.spatial_shape,
+                    is_subm=True,
+                    algo=spconv.ConvAlgo.Native,
+                    ksize=self.kernel_size,
+                    stride=self.stride,
+                    padding=self.padding,
+                    dilation=self.dilation,
+                )
+            else:
+                out_indices = data.out_indices
+                pairs = data.indice_pairs
+                pair_counts = data.indice_pair_num
+
+            features = input.features
+            kernel_volume = prod(self.kernel_size)
+            weights = self.weight.reshape(
+                self.out_channels, kernel_volume, self.in_channels
+            )
+            center = kernel_volume // 2
+            output = torch.empty(
+                (features.shape[0], self.out_channels),
+                dtype=features.dtype,
+                device=features.device,
+            )
+            chunk_rows = 250_000
+            for start in range(0, len(features), chunk_rows):
+                stop = min(start + chunk_rows, len(features))
+                output[start:stop] = features[start:stop] @ weights[:, center, :].T
+
+            def accumulate(
+                source: torch.Tensor,
+                target: torch.Tensor,
+                weight: torch.Tensor,
+            ) -> None:
+                for start in range(0, len(source), chunk_rows):
+                    stop = min(start + chunk_rows, len(source))
+                    contribution = features[source[start:stop]] @ weight.T
+                    output.index_add_(0, target[start:stop], contribution)
+
+            for offset in range(center):
+                count = int(pair_counts[offset])
+                source = pairs[0, offset, :count].long()
+                target = pairs[1, offset, :count].long()
+                accumulate(source, target, weights[:, offset, :])
+                accumulate(target, source, weights[:, kernel_volume - 1 - offset, :])
+            if self.bias is not None:
+                output.add_(self.bias)
+
+            result = input.replace_feature(output)
+            if indice_key is not None:
+                result.indice_dict[indice_key] = data
+            result.indices = out_indices
+            return result
+
+        def forward(self, input: Any) -> Any:
+            feats_dtype = input.features.dtype
+            matrix_element_size = max(
+                input.features.element_size(), self.weight.element_size()
+            )
+            input_bytes = input.features.numel() * matrix_element_size
+            with torch.autocast("cuda", enabled=False):
+                if feats_dtype != self.weight.dtype:
+                    input = input.replace_feature(input.features.to(self.weight.dtype))
+                if input_bytes >= _SPCONV_INT32_BYTE_LIMIT:
+                    # Both cumm convolution algorithms flatten the feature matrix
+                    # with int32 indices. Chunked PyTorch GEMMs retain the exact
+                    # native pair traversal for final 1536-scale decoding.
+                    out = self._large_forward(input)
+                else:
+                    out = super().forward(input)
+                if out.features.dtype != feats_dtype:
+                    out = out.replace_feature(out.features.to(feats_dtype))
+            return out
+
+    _spconv_conv_class = SubMConv3d
+    return _spconv_conv_class
+
+
+def Conv3d(
+    in_channels: int,
+    out_channels: int,
+    kernel_size: int = 3,
+    stride: int = 1,
+    padding: Optional[int] = None,
+    bias: bool = True,
+) -> nn.Module:
+    """Build a submanifold sparse convolution.
+
+    A submanifold convolution keeps the input's occupied coordinates and their row
+    order, which is what lets the surrounding code index features positionally.
+
+    Args:
+        in_channels: Input channels.
+        out_channels: Output channels.
+        kernel_size: Cubic kernel extent; must be odd.
+        stride: Only ``1`` is supported; a strided convolution would change the
+            occupied set and is not part of this architecture.
+        padding: Only the submanifold value ``kernel_size // 2`` (or ``None``, which
+            means the same) is supported.
+        bias: Whether to add a per-output-channel bias.
+
+    Returns:
+        A module taking and returning an spconv sparse tensor.
+
+    Raises:
+        ValueError: ``kernel_size`` is even, or ``stride``/``padding`` are not the
+            submanifold configuration.
+    """
+    if kernel_size % 2 == 0:
+        raise ValueError(f"kernel_size must be odd, got {kernel_size}")
+    if stride != 1:
+        raise ValueError(f"only stride 1 is supported, got {stride}")
+    if padding is not None and padding != kernel_size // 2:
+        raise ValueError(
+            f"only submanifold padding {kernel_size // 2} is supported, got {padding}"
+        )
+
+    import os
+
+    extra = {}
+    if os.environ.get("SPCONV_ALGO", "").lower() == "native":
+        # HF Space patch: the implicit-GEMM kernels shipped by spconv-cu120 are not
+        # built for Blackwell (sm_120); the native gather-GEMM-scatter path is.
+        extra["algo"] = _spconv().ConvAlgo.Native
+    conv = _submanifold_conv_class()(
+        in_channels,
+        out_channels,
+        kernel_size=kernel_size,
+        bias=bias,
+        **extra,
+        # Submanifold output coordinates always equal the input's, so every
+        # convolution over one tensor lineage can share the cached index pairs.
+        indice_key=f"subm{kernel_size}",
+    )
+    setattr(conv, _SPARSE_CONV_FLAG, True)
+    return conv
+
+
+def is_sparse_conv(module: nn.Module) -> bool:
+    """Return whether ``module`` was built by :func:`Conv3d`."""
+    return getattr(module, _SPARSE_CONV_FLAG, False)
+
+
+def sparse_tensor(
+    feats: torch.Tensor,
+    coords: torch.Tensor,
+    spatial_shape: Optional[Tuple[int, int, int]] = None,
+) -> Any:
+    """Wrap features and coordinates in an spconv sparse tensor.
+
+    Args:
+        feats: Features ``[N, C]``.
+        coords: Integer coordinates ``[N, 4]`` laid out as ``[batch, x, y, z]``.
+        spatial_shape: Grid extent per axis; derived from ``coords`` when ``None``.
+
+    Returns:
+        The spconv sparse tensor.
+
+    Raises:
+        ValueError: ``coords`` is not ``[N, 4]``, holds negative entries, or exceeds
+            ``spatial_shape``.
+    """
+    if coords.ndim != 2 or coords.shape[1] != 4:
+        raise ValueError(f"expected coords [N, 4], got {tuple(coords.shape)}")
+    coords = coords.int().contiguous()
+
+    spconv = _spconv()
+    grid = coords[:, 1:]
+    if int(grid.min()) < 0:
+        raise ValueError("grid coordinates must be non-negative")
+    extent = (grid.max(dim=0).values + 1).tolist()
+    if spatial_shape is None:
+        spatial_shape = tuple(extent)
+    elif any(bound < size for bound, size in zip(spatial_shape, extent)):
+        raise ValueError(
+            f"grid coordinates reach {extent}, outside spatial_shape {spatial_shape}"
+        )
+    return spconv.SparseConvTensor(
+        features=feats,
+        indices=coords,
+        spatial_shape=list(spatial_shape),
+        batch_size=int(coords[:, 0].max()) + 1,
+    )
+
+
+def get_feats(tensor: Any) -> torch.Tensor:
+    """Return the feature matrix of a sparse tensor."""
+    return tensor.features
+
+
+def replace_feats(tensor: Any, feats: torch.Tensor) -> Any:
+    """Return a sparse tensor with the same coordinates and new features.
+
+    spconv rejects assignment to ``features``, so the result may be a different
+    object than ``tensor``; callers must use the returned value.
+
+    Args:
+        tensor: Sparse tensor.
+        feats: Replacement features ``[N, C]``, one row per coordinate.
+
+    Returns:
+        The updated sparse tensor.
+
+    Raises:
+        ValueError: ``feats`` has a different number of rows than the tensor holds.
+    """
+    current = get_feats(tensor)
+    if feats.shape[0] != current.shape[0]:
+        raise ValueError(
+            f"expected {current.shape[0]} rows to match the coordinates, "
+            f"got {feats.shape[0]}"
+        )
+    return tensor.replace_feature(feats)

sparc3d/ops/triton/__init__.py

@@ -0,0 +1,7 @@
+"""Triton implementations of SPARC3D surface voxelization."""
+
+from sparc3d.ops.triton.voxelize import coarse_voxelize
+
+__all__ = [
+    "coarse_voxelize",
+]

sparc3d/ops/triton/voxelize.py

@@ -0,0 +1,302 @@
+"""Triton surface-voxelization kernels and CSR construction."""
+
+from __future__ import annotations
+
+from typing import Tuple
+
+import torch
+import triton
+import triton.language as tl
+
+
+@triton.jit
+def _axis_overlaps(
+    v0x,
+    v0y,
+    v0z,
+    v1x,
+    v1y,
+    v1z,
+    v2x,
+    v2y,
+    v2z,
+    ax,
+    ay,
+    az,
+):
+    p0 = v0x * ax + v0y * ay + v0z * az
+    p1 = v1x * ax + v1y * ay + v1z * az
+    p2 = v2x * ax + v2y * ay + v2z * az
+    lower = tl.minimum(tl.minimum(p0, p1), p2)
+    upper = tl.maximum(tl.maximum(p0, p1), p2)
+    radius = 0.5 * (tl.abs(ax) + tl.abs(ay) + tl.abs(az))
+    return (lower <= radius) & (upper >= -radius)
+
+
+@triton.jit
+def _triangle_overlaps_voxel(
+    a0,
+    a1,
+    a2,
+    b0,
+    b1,
+    b2,
+    c0,
+    c1,
+    c2,
+    x,
+    y,
+    z,
+):
+    center_x = x.to(tl.float32) + 0.5
+    center_y = y.to(tl.float32) + 0.5
+    center_z = z.to(tl.float32) + 0.5
+    v0x, v0y, v0z = a0 - center_x, a1 - center_y, a2 - center_z
+    v1x, v1y, v1z = b0 - center_x, b1 - center_y, b2 - center_z
+    v2x, v2y, v2z = c0 - center_x, c1 - center_y, c2 - center_z
+
+    overlaps = (
+        (tl.minimum(tl.minimum(v0x, v1x), v2x) <= 0.5)
+        & (tl.maximum(tl.maximum(v0x, v1x), v2x) >= -0.5)
+        & (tl.minimum(tl.minimum(v0y, v1y), v2y) <= 0.5)
+        & (tl.maximum(tl.maximum(v0y, v1y), v2y) >= -0.5)
+        & (tl.minimum(tl.minimum(v0z, v1z), v2z) <= 0.5)
+        & (tl.maximum(tl.maximum(v0z, v1z), v2z) >= -0.5)
+    )
+
+    e0x, e0y, e0z = v1x - v0x, v1y - v0y, v1z - v0z
+    e1x, e1y, e1z = v2x - v1x, v2y - v1y, v2z - v1z
+    e2x, e2y, e2z = v0x - v2x, v0y - v2y, v0z - v2z
+
+    overlaps &= _axis_overlaps(
+        v0x, v0y, v0z, v1x, v1y, v1z, v2x, v2y, v2z, 0.0, e0z, -e0y
+    )
+    overlaps &= _axis_overlaps(
+        v0x, v0y, v0z, v1x, v1y, v1z, v2x, v2y, v2z, -e0z, 0.0, e0x
+    )
+    overlaps &= _axis_overlaps(
+        v0x, v0y, v0z, v1x, v1y, v1z, v2x, v2y, v2z, e0y, -e0x, 0.0
+    )
+    overlaps &= _axis_overlaps(
+        v0x, v0y, v0z, v1x, v1y, v1z, v2x, v2y, v2z, 0.0, e1z, -e1y
+    )
+    overlaps &= _axis_overlaps(
+        v0x, v0y, v0z, v1x, v1y, v1z, v2x, v2y, v2z, -e1z, 0.0, e1x
+    )
+    overlaps &= _axis_overlaps(
+        v0x, v0y, v0z, v1x, v1y, v1z, v2x, v2y, v2z, e1y, -e1x, 0.0
+    )
+    overlaps &= _axis_overlaps(
+        v0x, v0y, v0z, v1x, v1y, v1z, v2x, v2y, v2z, 0.0, e2z, -e2y
+    )
+    overlaps &= _axis_overlaps(
+        v0x, v0y, v0z, v1x, v1y, v1z, v2x, v2y, v2z, -e2z, 0.0, e2x
+    )
+    overlaps &= _axis_overlaps(
+        v0x, v0y, v0z, v1x, v1y, v1z, v2x, v2y, v2z, e2y, -e2x, 0.0
+    )
+
+    nx = e0y * e1z - e0z * e1y
+    ny = e0z * e1x - e0x * e1z
+    nz = e0x * e1y - e0y * e1x
+    plane_offset = -(nx * v0x + ny * v0y + nz * v0z)
+    plane_radius = 0.5 * (tl.abs(nx) + tl.abs(ny) + tl.abs(nz))
+    return overlaps & (tl.abs(plane_offset) <= plane_radius)
+
+
+@triton.jit
+def _load_triangle(vertices_ptr, faces_ptr, face_id):
+    index0 = tl.load(faces_ptr + face_id * 3)
+    index1 = tl.load(faces_ptr + face_id * 3 + 1)
+    index2 = tl.load(faces_ptr + face_id * 3 + 2)
+    a0 = tl.load(vertices_ptr + index0 * 3)
+    a1 = tl.load(vertices_ptr + index0 * 3 + 1)
+    a2 = tl.load(vertices_ptr + index0 * 3 + 2)
+    b0 = tl.load(vertices_ptr + index1 * 3)
+    b1 = tl.load(vertices_ptr + index1 * 3 + 1)
+    b2 = tl.load(vertices_ptr + index1 * 3 + 2)
+    c0 = tl.load(vertices_ptr + index2 * 3)
+    c1 = tl.load(vertices_ptr + index2 * 3 + 1)
+    c2 = tl.load(vertices_ptr + index2 * 3 + 2)
+    return a0, a1, a2, b0, b1, b2, c0, c1, c2
+
+
+@triton.jit
+def _count_intersections_kernel(
+    vertices_ptr,
+    faces_ptr,
+    counts_ptr,
+    resolution: tl.constexpr,
+):
+    face_id = tl.program_id(0)
+    a0, a1, a2, b0, b1, b2, c0, c1, c2 = _load_triangle(
+        vertices_ptr, faces_ptr, face_id
+    )
+    start_x = tl.maximum(
+        tl.floor(tl.minimum(tl.minimum(a0, b0), c0)).to(tl.int32), 0
+    )
+    start_y = tl.maximum(
+        tl.floor(tl.minimum(tl.minimum(a1, b1), c1)).to(tl.int32), 0
+    )
+    start_z = tl.maximum(
+        tl.floor(tl.minimum(tl.minimum(a2, b2), c2)).to(tl.int32), 0
+    )
+    end_x = tl.minimum(
+        tl.floor(tl.maximum(tl.maximum(a0, b0), c0)).to(tl.int32),
+        resolution - 1,
+    )
+    end_y = tl.minimum(
+        tl.floor(tl.maximum(tl.maximum(a1, b1), c1)).to(tl.int32),
+        resolution - 1,
+    )
+    end_z = tl.minimum(
+        tl.floor(tl.maximum(tl.maximum(a2, b2), c2)).to(tl.int32),
+        resolution - 1,
+    )
+
+    count = 0
+    for z in tl.range(start_z, end_z + 1):
+        for y in tl.range(start_y, end_y + 1):
+            for x in tl.range(start_x, end_x + 1):
+                count += _triangle_overlaps_voxel(
+                    a0, a1, a2, b0, b1, b2, c0, c1, c2, x, y, z
+                ).to(tl.int32)
+    tl.store(counts_ptr + face_id, count)
+
+
+@triton.jit
+def _emit_intersections_kernel(
+    vertices_ptr,
+    faces_ptr,
+    offsets_ptr,
+    keys_ptr,
+    face_ids_ptr,
+    resolution: tl.constexpr,
+):
+    face_id = tl.program_id(0)
+    a0, a1, a2, b0, b1, b2, c0, c1, c2 = _load_triangle(
+        vertices_ptr, faces_ptr, face_id
+    )
+    start_x = tl.maximum(
+        tl.floor(tl.minimum(tl.minimum(a0, b0), c0)).to(tl.int32), 0
+    )
+    start_y = tl.maximum(
+        tl.floor(tl.minimum(tl.minimum(a1, b1), c1)).to(tl.int32), 0
+    )
+    start_z = tl.maximum(
+        tl.floor(tl.minimum(tl.minimum(a2, b2), c2)).to(tl.int32), 0
+    )
+    end_x = tl.minimum(
+        tl.floor(tl.maximum(tl.maximum(a0, b0), c0)).to(tl.int32),
+        resolution - 1,
+    )
+    end_y = tl.minimum(
+        tl.floor(tl.maximum(tl.maximum(a1, b1), c1)).to(tl.int32),
+        resolution - 1,
+    )
+    end_z = tl.minimum(
+        tl.floor(tl.maximum(tl.maximum(a2, b2), c2)).to(tl.int32),
+        resolution - 1,
+    )
+
+    output = tl.load(offsets_ptr + face_id)
+    for z in tl.range(start_z, end_z + 1):
+        for y in tl.range(start_y, end_y + 1):
+            for x in tl.range(start_x, end_x + 1):
+                hit = _triangle_overlaps_voxel(
+                    a0, a1, a2, b0, b1, b2, c0, c1, c2, x, y, z
+                )
+                key = (
+                    (z.to(tl.int64) << 22)
+                    | (y.to(tl.int64) << 11)
+                    | x.to(tl.int64)
+                )
+                tl.store(keys_ptr + output, key, mask=hit)
+                tl.store(face_ids_ptr + output, face_id, mask=hit)
+                output += hit.to(tl.int32)
+
+
+def coarse_voxelize(
+    vertices: torch.Tensor,
+    faces: torch.Tensor,
+    resolution: int,
+) -> Tuple[torch.Tensor, torch.Tensor, torch.Tensor, torch.Tensor, torch.Tensor]:
+    """Voxelize triangles and return voxel-to-face CSR tensors.
+
+    Args:
+        vertices: CUDA float coordinates with shape ``[V, 3]`` in voxel space.
+        faces: CUDA triangle indices with shape ``[F, 3]``.
+        resolution: Side length of the voxel grid.
+
+    Returns:
+        Encoded coordinates, grouped face IDs, CSR starts, CSR counts, and
+        per-face voxel counts.
+
+    Raises:
+        ValueError: Inputs do not satisfy the low-level voxelizer contract.
+    """
+    if not vertices.is_cuda or not faces.is_cuda:
+        raise ValueError("vertices and faces must be CUDA tensors")
+    if vertices.device != faces.device:
+        raise ValueError("vertices and faces must be on the same device")
+    if vertices.ndim != 2 or vertices.shape[1] != 3:
+        raise ValueError("vertices must have shape [num_vertices, 3]")
+    if faces.ndim != 2 or faces.shape[1] != 3:
+        raise ValueError("faces must have shape [num_faces, 3]")
+    if resolution < 1 or resolution > 2048:
+        raise ValueError(f"resolution must be in [1, 2048], got {resolution}")
+
+    vertices = vertices.to(torch.float32).contiguous()
+    faces = faces.to(torch.int32).contiguous()
+    num_faces = faces.shape[0]
+    counts = torch.zeros(num_faces, dtype=torch.int32, device=faces.device)
+    if num_faces == 0:
+        empty_u64 = torch.empty(0, dtype=torch.uint64, device=faces.device)
+        empty_u32 = torch.empty(0, dtype=torch.uint32, device=faces.device)
+        return empty_u64, empty_u32, counts, counts, counts
+
+    _count_intersections_kernel[(num_faces,)](
+        vertices, faces, counts, resolution, num_warps=1
+    )
+    inclusive = torch.cumsum(counts, dim=0, dtype=torch.int32)
+    offsets = torch.cat(
+        [torch.zeros(1, dtype=torch.int32, device=faces.device), inclusive[:-1]]
+    )
+    total = int(inclusive[-1].item())
+    if total == 0:
+        empty_u64 = torch.empty(0, dtype=torch.uint64, device=faces.device)
+        empty_u32 = torch.empty(0, dtype=torch.uint32, device=faces.device)
+        empty_i32 = torch.empty(0, dtype=torch.int32, device=faces.device)
+        return empty_u64, empty_u32, empty_i32, empty_i32, counts
+
+    keys = torch.empty(total, dtype=torch.int64, device=faces.device)
+    face_ids = torch.empty(total, dtype=torch.int32, device=faces.device)
+    _emit_intersections_kernel[(num_faces,)](
+        vertices,
+        faces,
+        offsets,
+        keys,
+        face_ids,
+        resolution,
+        num_warps=1,
+    )
+
+    sorted_keys, order = torch.sort(keys, stable=True)
+    grouped_faces = face_ids[order]
+    unique_keys, unique_counts = torch.unique_consecutive(
+        sorted_keys, return_counts=True
+    )
+    unique_counts = unique_counts.to(torch.int32)
+    unique_starts = torch.cat(
+        [
+            torch.zeros(1, dtype=torch.int32, device=faces.device),
+            torch.cumsum(unique_counts, dim=0, dtype=torch.int32)[:-1],
+        ]
+    )
+    return (
+        unique_keys.to(torch.uint64),
+        grouped_faces.to(torch.uint32),
+        unique_starts,
+        unique_counts,
+        counts,
+    )