Duplicate from tencent/Hunyuan3D-2.1

Co-authored-by: huiwenshi <[email protected]>

.gitattributes

@@ -0,0 +1,35 @@
+*.7z filter=lfs diff=lfs merge=lfs -text
+*.arrow filter=lfs diff=lfs merge=lfs -text
+*.bin filter=lfs diff=lfs merge=lfs -text
+*.bz2 filter=lfs diff=lfs merge=lfs -text
+*.ckpt filter=lfs diff=lfs merge=lfs -text
+*.ftz filter=lfs diff=lfs merge=lfs -text
+*.gz filter=lfs diff=lfs merge=lfs -text
+*.h5 filter=lfs diff=lfs merge=lfs -text
+*.joblib filter=lfs diff=lfs merge=lfs -text
+*.lfs.* filter=lfs diff=lfs merge=lfs -text
+*.mlmodel filter=lfs diff=lfs merge=lfs -text
+*.model filter=lfs diff=lfs merge=lfs -text
+*.msgpack filter=lfs diff=lfs merge=lfs -text
+*.npy filter=lfs diff=lfs merge=lfs -text
+*.npz filter=lfs diff=lfs merge=lfs -text
+*.onnx filter=lfs diff=lfs merge=lfs -text
+*.ot filter=lfs diff=lfs merge=lfs -text
+*.parquet filter=lfs diff=lfs merge=lfs -text
+*.pb filter=lfs diff=lfs merge=lfs -text
+*.pickle filter=lfs diff=lfs merge=lfs -text
+*.pkl filter=lfs diff=lfs merge=lfs -text
+*.pt filter=lfs diff=lfs merge=lfs -text
+*.pth filter=lfs diff=lfs merge=lfs -text
+*.rar filter=lfs diff=lfs merge=lfs -text
+*.safetensors filter=lfs diff=lfs merge=lfs -text
+saved_model/**/* filter=lfs diff=lfs merge=lfs -text
+*.tar.* filter=lfs diff=lfs merge=lfs -text
+*.tar filter=lfs diff=lfs merge=lfs -text
+*.tflite filter=lfs diff=lfs merge=lfs -text
+*.tgz filter=lfs diff=lfs merge=lfs -text
+*.wasm filter=lfs diff=lfs merge=lfs -text
+*.xz 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

LICENSE

@@ -0,0 +1,82 @@
+TENCENT HUNYUAN 3D 2.1 COMMUNITY LICENSE AGREEMENT
+Tencent Hunyuan 3D 2.1 Release Date: June 13, 2025
+THIS LICENSE AGREEMENT DOES NOT APPLY IN THE EUROPEAN UNION, UNITED KINGDOM AND SOUTH KOREA AND IS EXPRESSLY LIMITED TO THE TERRITORY, AS DEFINED BELOW.
+By clicking to agree or by using, reproducing, modifying, distributing, performing or displaying any portion or element of the Tencent Hunyuan 3D 2.1 Works, including via any Hosted Service, You will be deemed to have recognized and accepted the content of this Agreement, which is effective immediately.
+1.	DEFINITIONS.
+a.	“Acceptable Use Policy” shall mean the policy made available by Tencent as set forth in the Exhibit A.
+b.	“Agreement” shall mean the terms and conditions for use, reproduction, distribution, modification, performance and displaying of Tencent Hunyuan 3D 2.1 Works or any portion or element thereof set forth herein.
+c.	“Documentation” shall mean the specifications, manuals and documentation for Tencent Hunyuan 3D 2.1 made publicly available by Tencent.
+d.	“Hosted Service” shall mean a hosted service offered via an application programming interface (API), web access, or any other electronic or remote means.
+e.	“Licensee,” “You” or “Your” shall mean a natural person or legal entity exercising the rights granted by this Agreement and/or using the Tencent Hunyuan 3D 2.1 Works for any purpose and in any field of use.
+f.	“Materials” shall mean, collectively, Tencent’s proprietary Tencent Hunyuan 3D 2.1 and Documentation (and any portion thereof) as made available by Tencent under this Agreement.
+g.	“Model Derivatives” shall mean all: (i) modifications to Tencent Hunyuan 3D 2.1 or any Model Derivative of Tencent Hunyuan 3D 2.1; (ii) works based on Tencent Hunyuan 3D 2.1 or any Model Derivative of Tencent Hunyuan 3D 2.1; or (iii) any other machine learning model which is created by transfer of patterns of the weights, parameters, operations, or Output of Tencent Hunyuan 3D 2.1 or any Model Derivative of Tencent Hunyuan 3D 2.1, to that model in order to cause that model to perform similarly to Tencent Hunyuan 3D 2.1 or a Model Derivative of Tencent Hunyuan 3D 2.1, including distillation methods, methods that use intermediate data representations, or methods based on the generation of synthetic data Outputs by Tencent Hunyuan 3D 2.1 or a Model Derivative of Tencent Hunyuan 3D 2.1 for training that model. For clarity, Outputs by themselves are not deemed Model Derivatives.
+h.	“Output” shall mean the information and/or content output of Tencent Hunyuan 3D 2.1 or a Model Derivative that results from operating or otherwise using Tencent Hunyuan 3D 2.1 or a Model Derivative, including via a Hosted Service.
+i.	“Tencent,” “We” or “Us” shall mean the applicable entity or entities in the Tencent corporate family that own(s) intellectual property or other rights embodied in or utilized by the Materials.
+*   Section 1.i of the previous Hunyuan License Agreement defined “Tencent,” “We” or “Us” to mean THL A29 Limited, and the copyright notices pertaining to the Materials were previously in the name of “THL A29 Limited.”  That entity has now been de-registered.  You should treat all previously distributed copies of the Materials as if Section 1.i of the Agreement defined “Tencent,” “We” or “Us” to mean “the applicable entity or entities in the Tencent corporate family that own(s) intellectual property or other rights embodied in or utilized by the Materials,” and treat the copyright notice(s) accompanying the Materials as if they were in the name of “Tencent.”  When providing a copy of any Agreement to Third Party recipients of the Tencent Hunyuan Works or products or services using them, as required by Section 3.a of the Agreement, you should provide the most current version of the Agreement, including the change of definition in Section 1.i of the Agreement.
+j.	“Tencent Hunyuan 3D 2.1” shall mean the 3D generation models and their software and algorithms, including trained model weights, parameters (including optimizer states), machine-learning model code, inference-enabling code, training-enabling code, fine-tuning enabling code and other elements of the foregoing made publicly available by Us at [ https://github.com/Tencent-Hunyuan/Hunyuan3D-2.1].
+k.	“Tencent Hunyuan 3D 2.1 Works” shall mean: (i) the Materials; (ii) Model Derivatives; and (iii) all derivative works thereof.
+l.	“Territory” shall mean the worldwide territory, excluding the territory of the European Union, United Kingdom and South Korea. 
+m.	“Third Party” or “Third Parties” shall mean individuals or legal entities that are not under common control with Us or You.
+n.	“including” shall mean including but not limited to.
+2.	GRANT OF RIGHTS.
+We grant You, for the Territory only, a non-exclusive, non-transferable and royalty-free limited license under Tencent’s intellectual property or other rights owned by Us embodied in or utilized by the Materials to use, reproduce, distribute, create derivative works of (including Model Derivatives), and make modifications to the Materials, only in accordance with the terms of this Agreement and the Acceptable Use Policy, and You must not violate (or encourage or permit anyone else to violate) any term of this Agreement or the Acceptable Use Policy.
+3.	DISTRIBUTION.
+You may, subject to Your compliance with this Agreement, distribute or make available to Third Parties the Tencent Hunyuan 3D 2.1 Works, exclusively in the Territory, provided that You meet all of the following conditions:
+a.	You must provide all such Third Party recipients of the Tencent Hunyuan 3D 2.1 Works or products or services using them a copy of this Agreement;
+b.	You must cause any modified files to carry prominent notices stating that You changed the files;
+c.	You are encouraged to: (i) publish at least one technology introduction blogpost or one public statement expressing Your experience of using the Tencent Hunyuan 3D 2.1 Works; and (ii) mark the products or services developed by using the Tencent Hunyuan 3D 2.1 Works to indicate that the product/service is “Powered by Tencent Hunyuan”; and
+d.	All distributions to Third Parties (other than through a Hosted Service) must be accompanied by a “Notice” text file that contains the following notice: “Tencent Hunyuan 3D 2.1 is licensed under the Tencent Hunyuan 3D 2.1 Community License Agreement, Copyright © 2025 Tencent. All Rights Reserved. The trademark rights of “Tencent Hunyuan” are owned by Tencent or its affiliate.”
+You may add Your own copyright statement to Your modifications and, except as set forth in this Section and in Section 5, may provide additional or different license terms and conditions for use, reproduction, or distribution of Your modifications, or for any such Model Derivatives as a whole, provided Your use, reproduction, modification, distribution, performance and display of the work otherwise complies with the terms and conditions of this Agreement (including as regards the Territory). If You receive Tencent Hunyuan 3D 2.1 Works from a Licensee as part of an integrated end user product, then this Section 3 of this Agreement will not apply to You.
+4.	ADDITIONAL COMMERCIAL TERMS.
+If, on the Tencent Hunyuan 3D 2.1 version release date, the monthly active users of all products or services made available by or for Licensee is greater than 1 million monthly active users in the preceding calendar month, You must request a license from Tencent, which Tencent may grant to You in its sole discretion, and You are not authorized to exercise any of the rights under this Agreement unless or until Tencent otherwise expressly grants You such rights. 
+Subject to Tencent's written approval, you may request a license for the use of Tencent Hunyuan 3D 2.1 by submitting the following information to [email protected]:
+a.	Your company’s name and associated business sector that plans to use Tencent Hunyuan 3D 2.1.
+b.	Your intended use case and the purpose of using Tencent Hunyuan 3D 2.1.
+c.	Your plans to modify Tencent Hunyuan 3D 2.1 or create Model Derivatives.
+5.	RULES OF USE.
+a.	Your use of the Tencent Hunyuan 3D 2.1 Works must comply with applicable laws and regulations (including trade compliance laws and regulations) and adhere to the Acceptable Use Policy for the Tencent Hunyuan 3D 2.1 Works, which is hereby incorporated by reference into this Agreement. You must include the use restrictions referenced in these Sections 5(a) and 5(b) as an enforceable provision in any agreement (e.g., license agreement, terms of use, etc.) governing the use and/or distribution of Tencent Hunyuan 3D 2.1 Works and You must provide notice to subsequent users to whom You distribute that Tencent Hunyuan 3D 2.1 Works are subject to the use restrictions in these Sections 5(a) and 5(b).
+b.	You must not use the Tencent Hunyuan 3D 2.1 Works or any Output or results of the Tencent Hunyuan 3D 2.1 Works to improve any other AI model (other than Tencent Hunyuan 3D 2.1 or Model Derivatives thereof).
+c.	You must not use, reproduce, modify, distribute, or display the Tencent Hunyuan 3D 2.1 Works, Output or results of the Tencent Hunyuan 3D 2.1 Works outside the Territory. Any such use outside the Territory is unlicensed and unauthorized under this Agreement.
+6.	INTELLECTUAL PROPERTY.
+a.	Subject to Tencent’s ownership of Tencent Hunyuan 3D 2.1 Works made by or for Tencent and intellectual property rights therein, conditioned upon Your compliance with the terms and conditions of this Agreement, as between You and Tencent, You will be the owner of any derivative works and modifications of the Materials and any Model Derivatives that are made by or for You.
+b.	No trademark licenses are granted under this Agreement, and in connection with the Tencent Hunyuan 3D 2.1 Works, Licensee may not use any name or mark owned by or associated with Tencent or any of its affiliates, except as required for reasonable and customary use in describing and distributing the Tencent Hunyuan 3D 2.1 Works. Tencent hereby grants You a license to use “Tencent Hunyuan” (the “Mark”) in the Territory solely as required to comply with the provisions of Section 3(c), provided that You comply with any applicable laws related to trademark protection. All goodwill arising out of Your use of the Mark will inure to the benefit of Tencent.
+c.	If You commence a lawsuit or other proceedings (including a cross-claim or counterclaim in a lawsuit) against Us or any person or entity alleging that the Materials or any Output, or any portion of any of the foregoing, infringe any intellectual property or other right owned or licensable by You, then all licenses granted to You under this Agreement shall terminate as of the date such lawsuit or other proceeding is filed. You will defend, indemnify and hold harmless Us from and against any claim by any Third Party arising out of or related to Your or the Third Party’s use or distribution of the Tencent Hunyuan 3D 2.1 Works.
+d.	Tencent claims no rights in Outputs You generate. You and Your users are solely responsible for Outputs and their subsequent uses.
+7.	DISCLAIMERS OF WARRANTY AND LIMITATIONS OF LIABILITY.
+a.	We are not obligated to support, update, provide training for, or develop any further version of the Tencent Hunyuan 3D 2.1 Works or to grant any license thereto.
+b.	UNLESS AND ONLY TO THE EXTENT REQUIRED BY APPLICABLE LAW, THE TENCENT HUNYUAN 3D 2.1 WORKS AND ANY OUTPUT AND RESULTS THEREFROM ARE PROVIDED “AS IS” WITHOUT ANY EXPRESS OR IMPLIED WARRANTIES OF ANY KIND INCLUDING ANY WARRANTIES OF TITLE, MERCHANTABILITY, NONINFRINGEMENT, COURSE OF DEALING, USAGE OF TRADE, OR FITNESS FOR A PARTICULAR PURPOSE. YOU ARE SOLELY RESPONSIBLE FOR DETERMINING THE APPROPRIATENESS OF USING, REPRODUCING, MODIFYING, PERFORMING, DISPLAYING OR DISTRIBUTING ANY OF THE TENCENT HUNYUAN 3D 2.1 WORKS OR OUTPUTS AND ASSUME ANY AND ALL RISKS ASSOCIATED WITH YOUR OR A THIRD PARTY’S USE OR DISTRIBUTION OF ANY OF THE TENCENT HUNYUAN 3D 2.1 WORKS OR OUTPUTS AND YOUR EXERCISE OF RIGHTS AND PERMISSIONS UNDER THIS AGREEMENT.
+c.	TO THE FULLEST EXTENT PERMITTED BY APPLICABLE LAW, IN NO EVENT SHALL TENCENT OR ITS AFFILIATES BE LIABLE UNDER ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, TORT, NEGLIGENCE, PRODUCTS LIABILITY, OR OTHERWISE, FOR ANY DAMAGES, INCLUDING ANY DIRECT, INDIRECT, SPECIAL, INCIDENTAL, EXEMPLARY, CONSEQUENTIAL OR PUNITIVE DAMAGES, OR LOST PROFITS OF ANY KIND ARISING FROM THIS AGREEMENT OR RELATED TO ANY OF THE TENCENT HUNYUAN 3D 2.1 WORKS OR OUTPUTS, EVEN IF TENCENT OR ITS AFFILIATES HAVE BEEN ADVISED OF THE POSSIBILITY OF ANY OF THE FOREGOING.
+8.	SURVIVAL AND TERMINATION.
+a.	The term of this Agreement shall commence upon Your acceptance of this Agreement or access to the Materials and will continue in full force and effect until terminated in accordance with the terms and conditions herein.
+b.	We may terminate this Agreement if You breach any of the terms or conditions of this Agreement. Upon termination of this Agreement, You must promptly delete and cease use of the Tencent Hunyuan 3D 2.1 Works. Sections 6(a), 6(c), 7 and 9 shall survive the termination of this Agreement.
+9.	GOVERNING LAW AND JURISDICTION.
+a.	This Agreement and any dispute arising out of or relating to it will be governed by the laws of the Hong Kong Special Administrative Region of the People’s Republic of China, without regard to conflict of law principles, and the UN Convention on Contracts for the International Sale of Goods does not apply to this Agreement.
+b.	Exclusive jurisdiction and venue for any dispute arising out of or relating to this Agreement will be a court of competent jurisdiction in the Hong Kong Special Administrative Region of the People’s Republic of China, and Tencent and Licensee consent to the exclusive jurisdiction of such court with respect to any such dispute.
+ 
+EXHIBIT A
+ACCEPTABLE USE POLICY
+
+Tencent reserves the right to update this Acceptable Use Policy from time to time.
+Last modified: November 5, 2024
+
+Tencent endeavors to promote safe and fair use of its tools and features, including Tencent Hunyuan 3D 2.1. You agree not to use Tencent Hunyuan 3D 2.1 or Model Derivatives:
+1.	Outside the Territory;
+2.	In any way that violates any applicable national, federal, state, local, international or any other law or regulation;
+3.	To harm Yourself or others;
+4.	To repurpose or distribute output from Tencent Hunyuan 3D 2.1 or any Model Derivatives to harm Yourself or others; 
+5.	To override or circumvent the safety guardrails and safeguards We have put in place;
+6.	For the purpose of exploiting, harming or attempting to exploit or harm minors in any way;
+7.	To generate or disseminate verifiably false information and/or content with the purpose of harming others or influencing elections;
+8.	To generate or facilitate false online engagement, including fake reviews and other means of fake online engagement;
+9.	To intentionally defame, disparage or otherwise harass others;
+10.	To generate and/or disseminate malware (including ransomware) or any other content to be used for the purpose of harming electronic systems;
+11.	To generate or disseminate personal identifiable information with the purpose of harming others;
+12.	To generate or disseminate information (including images, code, posts, articles), and place the information in any public context (including –through the use of bot generated tweets), without expressly and conspicuously identifying that the information and/or content is machine generated;
+13.	To impersonate another individual without consent, authorization, or legal right;
+14.	To make high-stakes automated decisions in domains that affect an individual’s safety, rights or wellbeing (e.g., law enforcement, migration, medicine/health, management of critical infrastructure, safety components of products, essential services, credit, employment, housing, education, social scoring, or insurance);
+15.	In a manner that violates or disrespects the social ethics and moral standards of other countries or regions;
+16.	To perform, facilitate, threaten, incite, plan, promote or encourage violent extremism or terrorism;
+17.	For any use intended to discriminate against or harm individuals or groups based on protected characteristics or categories, online or offline social behavior or known or predicted personal or personality characteristics;
+18.	To intentionally exploit any of the vulnerabilities of a specific group of persons based on their age, social, physical or mental characteristics, in order to materially distort the behavior of a person pertaining to that group in a manner that causes or is likely to cause that person or another person physical or psychological harm;
+19.	For military purposes;
+20.	To engage in the unauthorized or unlicensed practice of any profession including, but not limited to, financial, legal, medical/health, or other professional practices.

Notice.txt

@@ -0,0 +1,122 @@
+Usage and Legal Notices:
+
+Tencent is pleased to support the open source community by making Hunyuan 3D 2.1 available.
+
+Copyright (C) 2025 Tencent.  All rights reserved. The below software and/or models in this distribution may have been modified by Tencent ("Tencent Modifications"). All Tencent Modifications are Copyright (C) Tencent.
+
+Hunyuan 3D 2.1 is licensed under the TENCENT HUNYUAN 3D 2.1 COMMUNITY LICENSE AGREEMENT except for the third-party components listed below, which is licensed under different terms. Hunyuan 3D 2.1 does not impose any additional limitations beyond what is outlined in the respective licenses of these third-party components. Users must comply with all terms and conditions of original licenses of these third-party components and must ensure that the usage of the third party components adheres to all relevant laws and regulations. 
+
+For avoidance of doubts, Hunyuan 3D 2.1 means inference-enabling code, parameters, and weights of this Model only, which are made publicly available by Tencent in accordance with TENCENT HUNYUAN 3D 2.1 COMMUNITY LICENSE AGREEMENT.
+
+
+Other dependencies and licenses:
+
+
+Open Source Model Licensed under the MIT and CreativeML Open RAIL++-M License:
+--------------------------------------------------------------------
+1. Stable Diffusion
+Copyright (c) 2022 Stability AI
+
+
+Terms of the MIT and CreativeML Open RAIL++-M License:
+--------------------------------------------------------------------
+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.
+
+
+CreativeML Open RAIL++-M License
+dated November 24, 2022
+
+Section I: PREAMBLE
+
+Multimodal generative models are being widely adopted and used, and have the potential to transform the way artists, among other individuals, conceive and benefit from AI or ML technologies as a tool for content creation.
+
+Notwithstanding the current and potential benefits that these artifacts can bring to society at large, there are also concerns about potential misuses of them, either due to their technical limitations or ethical considerations.
+
+In short, this license strives for both the open and responsible downstream use of the accompanying model. When it comes to the open character, we took inspiration from open source permissive licenses regarding the grant of IP rights. Referring to the downstream responsible use, we added use-based restrictions not permitting the use of the Model in very specific scenarios, in order for the licensor to be able to enforce the license in case potential misuses of the Model may occur. At the same time, we strive to promote open and responsible research on generative models for art and content generation.
+
+Even though downstream derivative versions of the model could be released under different licensing terms, the latter will always have to include - at minimum - the same use-based restrictions as the ones in the original license (this license). We believe in the intersection between open and responsible AI development; thus, this License aims to strike a balance between both in order to enable responsible open-science in the field of AI.
+
+This License governs the use of the model (and its derivatives) and is informed by the model card associated with the model.
+
+NOW THEREFORE, You and Licensor agree as follows:
+
+1. Definitions
+
+- "License" means the terms and conditions for use, reproduction, and Distribution as defined in this document.
+- "Data" means a collection of information and/or content extracted from the dataset used with the Model, including to train, pretrain, or otherwise evaluate the Model. The Data is not licensed under this License.
+- "Output" means the results of operating a Model as embodied in informational content resulting therefrom.
+- "Model" means any accompanying machine-learning based assemblies (including checkpoints), consisting of learnt weights, parameters (including optimizer states), corresponding to the model architecture as embodied in the Complementary Material, that have been trained or tuned, in whole or in part on the Data, using the Complementary Material.
+- "Derivatives of the Model" means all modifications to the Model, works based on the Model, or any other model which is created or initialized by transfer of patterns of the weights, parameters, activations or output of the Model, to the other model, in order to cause the other model to perform similarly to the Model, including - but not limited to - distillation methods entailing the use of intermediate data representations or methods based on the generation of synthetic data by the Model for training the other model.
+- "Complementary Material" means the accompanying source code and scripts used to define, run, load, benchmark or evaluate the Model, and used to prepare data for training or evaluation, if any. This includes any accompanying documentation, tutorials, examples, etc, if any.
+- "Distribution" means any transmission, reproduction, publication or other sharing of the Model or Derivatives of the Model to a third party, including providing the Model as a hosted service made available by electronic or other remote means - e.g. API-based or web access.
+- "Licensor" means the copyright owner or entity authorized by the copyright owner that is granting the License, including the persons or entities that may have rights in the Model and/or distributing the Model.
+- "You" (or "Your") means an individual or Legal Entity exercising permissions granted by this License and/or making use of the Model for whichever purpose and in any field of use, including usage of the Model in an end-use application - e.g. chatbot, translator, image generator.
+- "Third Parties" means individuals or legal entities that are not under common control with Licensor or You.
+- "Contribution" means any work of authorship, including the original version of the Model and any modifications or additions to that Model or Derivatives of the Model thereof, that is intentionally submitted to Licensor for inclusion in the Model 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 Model, but excluding communication that is conspicuously marked or otherwise designated in writing by the copyright owner as "Not a Contribution."
+- "Contributor" means Licensor and any individual or Legal Entity on behalf of whom a Contribution has been received by Licensor and subsequently incorporated within the Model.
+
+Section II: INTELLECTUAL PROPERTY RIGHTS
+
+Both copyright and patent grants apply to the Model, Derivatives of the Model and Complementary Material. The Model and Derivatives of the Model are subject to additional terms as described in Section III.
+
+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, publicly display, publicly perform, sublicense, and distribute the Complementary Material, the Model, and Derivatives of the Model.
+3. Grant of Patent License. Subject to the terms and conditions of this License and where and as applicable, each Contributor hereby grants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable (except as stated in this paragraph) patent license to make, have made, use, offer to sell, sell, import, and otherwise transfer the Model and the Complementary Material, 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 Model 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 Model and/or Complementary Material or a Contribution incorporated within the Model and/or Complementary Material constitutes direct or contributory patent infringement, then any patent licenses granted to You under this License for the Model and/or Work shall terminate as of the date such litigation is asserted or filed.
+
+Section III: CONDITIONS OF USAGE, DISTRIBUTION AND REDISTRIBUTION
+
+4. Distribution and Redistribution. You may host for Third Party remote access purposes (e.g. software-as-a-service), reproduce and distribute copies of the Model or Derivatives of the Model thereof in any medium, with or without modifications, provided that You meet the following conditions:
+Use-based restrictions as referenced in paragraph 5 MUST be included as an enforceable provision by You in any type of legal agreement (e.g. a license) governing the use and/or distribution of the Model or Derivatives of the Model, and You shall give notice to subsequent users You Distribute to, that the Model or Derivatives of the Model are subject to paragraph 5. This provision does not apply to the use of Complementary Material.
+You must give any Third Party recipients of the Model or Derivatives of the Model a copy of this License;
+You must cause any modified files to carry prominent notices stating that You changed the files;
+You must retain all copyright, patent, trademark, and attribution notices excluding those notices that do not pertain to any part of the Model, Derivatives of the Model.
+You may add Your own copyright statement to Your modifications and may provide additional or different license terms and conditions - respecting paragraph 4.a. - for use, reproduction, or Distribution of Your modifications, or for any such Derivatives of the Model as a whole, provided Your use, reproduction, and Distribution of the Model otherwise complies with the conditions stated in this License.
+5. Use-based restrictions. The restrictions set forth in Attachment A are considered Use-based restrictions. Therefore You cannot use the Model and the Derivatives of the Model for the specified restricted uses. You may use the Model subject to this License, including only for lawful purposes and in accordance with the License. Use may include creating any content with, finetuning, updating, running, training, evaluating and/or reparametrizing the Model. You shall require all of Your users who use the Model or a Derivative of the Model to comply with the terms of this paragraph (paragraph 5).
+6. The Output You Generate. Except as set forth herein, Licensor claims no rights in the Output You generate using the Model. You are accountable for the Output you generate and its subsequent uses. No use of the output can contravene any provision as stated in the License.
+
+Section IV: OTHER PROVISIONS
+
+7. Updates and Runtime Restrictions. To the maximum extent permitted by law, Licensor reserves the right to restrict (remotely or otherwise) usage of the Model in violation of this License.
+8. Trademarks and related. Nothing in this License permits You to make use of Licensors’ trademarks, trade names, logos or to otherwise suggest endorsement or misrepresent the relationship between the parties; and any rights not expressly granted herein are reserved by the Licensors.
+9. Disclaimer of Warranty. Unless required by applicable law or agreed to in writing, Licensor provides the Model and the Complementary Material (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 Model, Derivatives of the Model, and the Complementary Material and assume any risks associated with Your exercise of permissions under this License.
+10. 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 Model and the Complementary Material (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.
+11. Accepting Warranty or Additional Liability. While redistributing the Model, Derivatives of the Model and the Complementary Material 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.
+12. If any provision of this License is held to be invalid, illegal or unenforceable, the remaining provisions shall be unaffected thereby and remain valid as if such provision had not been set forth herein.
+
+END OF TERMS AND CONDITIONS
+
+
+
+
+Attachment A
+
+Use Restrictions
+
+You agree not to use the Model or Derivatives of the Model:
+
+- In any way that violates any applicable national, federal, state, local or international law or regulation;
+- For the purpose of exploiting, harming or attempting to exploit or harm minors in any way;
+- To generate or disseminate verifiably false information and/or content with the purpose of harming others;
+- To generate or disseminate personal identifiable information that can be used to harm an individual;
+- To defame, disparage or otherwise harass others;
+- For fully automated decision making that adversely impacts an individual’s legal rights or otherwise creates or modifies a binding, enforceable obligation;
+- For any use intended to or which has the effect of discriminating against or harming individuals or groups based on online or offline social behavior or known or predicted personal or personality characteristics;
+- To exploit any of the vulnerabilities of a specific group of persons based on their age, social, physical or mental characteristics, in order to materially distort the behavior of a person pertaining to that group in a manner that causes or is likely to cause that person or another person physical or psychological harm;
+- For any use intended to or which has the effect of discriminating against individuals or groups based on legally protected characteristics or categories;
+- To provide medical advice and medical results interpretation;
+- To generate or disseminate information for the purpose to be used for administration of justice, law enforcement, immigration or asylum processes, such as predicting an individual will commit fraud/crime commitment (e.g. by text profiling, drawing causal relationships between assertions made in documents, indiscriminate and arbitrarily-targeted use).

README.md

@@ -0,0 +1,78 @@
+---
+library_name: hunyuan3d-2
+license: other
+license_name: tencent-hunyuan-community
+license_link: https://github.com/Tencent-Hunyuan/Hunyuan3D-2.1/blob/main/LICENSE
+language:
+  - en
+  - zh
+tags:
+  - image-to-3d
+  - text-to-3d
+pipeline_tag: image-to-3d
+extra_gated_eu_disallowed: true
+---
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/Tencent-Hunyuan/Hunyuan3D-2.1/refs/heads/main/assets/images/teaser.jpg">
+</p>
+
+<div align="center">
+  <a href=https://3d.hunyuan.tencent.com target="_blank"><img src=https://img.shields.io/badge/Hunyuan3D-black.svg?logo=homepage height=22px></a>
+  <a href=https://huggingface.co/spaces/tencent/Hunyuan3D-2.1  target="_blank"><img src=https://img.shields.io/badge/%F0%9F%A4%97%20Demo-276cb4.svg height=22px></a>
+  <a href=https://huggingface.co/tencent/Hunyuan3D-2.1 target="_blank"><img src=https://img.shields.io/badge/%F0%9F%A4%97%20Models-d96902.svg height=22px></a>
+  <a href=https://github.com/Tencent-Hunyuan/Hunyuan3D-2.1 target="_blank"><img src= https://img.shields.io/badge/Page-bb8a2e.svg?logo=github height=22px></a>
+<a href=https://discord.gg/GuaWYwzKbX target="_blank"><img src= https://img.shields.io/badge/Discord-white.svg?logo=discord height=22px></a>
+    <a href=https://arxiv.org/abs/2506.15442 target="_blank"><img src=https://img.shields.io/badge/Report-b5212f.svg?logo=arxiv height=22px></a>
+</div>
+
+## 🔗 BibTeX
+
+If you found this repository helpful, please cite our report:
+
+```bibtex
+@misc{hunyuan3d2025hunyuan3d,
+    title={Hunyuan3D 2.1: From Images to High-Fidelity 3D Assets with Production-Ready PBR Material},
+    author={Team Hunyuan3D and Shuhui Yang and Mingxin Yang and Yifei Feng and Xin Huang and Sheng Zhang and Zebin He and Di Luo and Haolin Liu and Yunfei Zhao and Qingxiang Lin and Zeqiang Lai and Xianghui Yang and Huiwen Shi and Zibo Zhao and Bowen Zhang and Hongyu Yan and Lifu Wang and Sicong Liu and Jihong Zhang and Meng Chen and Liang Dong and Yiwen Jia and Yulin Cai and Jiaao Yu and Yixuan Tang and Dongyuan Guo and Junlin Yu and Hao Zhang and Zheng Ye and Peng He and Runzhou Wu and Shida Wei and Chao Zhang and Yonghao Tan and Yifu Sun and Lin Niu and Shirui Huang and Bojian Zheng and Shu Liu and Shilin Chen and Xiang Yuan and Xiaofeng Yang and Kai Liu and Jianchen Zhu and Peng Chen and Tian Liu and Di Wang and Yuhong Liu and Linus and Jie Jiang and Jingwei Huang and Chunchao Guo},
+    year={2025},
+    eprint={2506.15442},
+    archivePrefix={arXiv},
+    primaryClass={cs.CV}
+}
+
+@misc{hunyuan3d22025tencent,
+    title={Hunyuan3D 2.0: Scaling Diffusion Models for High Resolution Textured 3D Assets Generation},
+    author={Tencent Hunyuan3D Team},
+    year={2025},
+    eprint={2501.12202},
+    archivePrefix={arXiv},
+    primaryClass={cs.CV}
+}
+
+@misc{yang2024tencent,
+    title={Tencent Hunyuan3D-1.0: A Unified Framework for Text-to-3D and Image-to-3D Generation},
+    author={Tencent Hunyuan3D Team},
+    year={2024},
+    eprint={2411.02293},
+    archivePrefix={arXiv},
+    primaryClass={cs.CV}
+}
+```
+
+
+
+## Acknowledgements
+
+We would like to thank the contributors to
+the [TripoSG](https://github.com/VAST-AI-Research/TripoSG), [DINOv2](https://github.com/facebookresearch/dinov2), [Stable Diffusion](https://github.com/Stability-AI/stablediffusion), [FLUX](https://github.com/black-forest-labs/flux), [diffusers](https://github.com/huggingface/diffusers)
+and [HuggingFace](https://huggingface.co) repositories, for their open research and exploration.
+
+## Star History
+
+<a href="https://star-history.com/#Tencent-Hunyuan/Hunyuan3D-2.1&Date">
+ <picture>
+   <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/svg?repos=Tencent-Hunyuan/Hunyuan3D-2.1&type=Date&theme=dark" />
+   <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/svg?repos=Tencent-Hunyuan/Hunyuan3D-2.1&type=Date" />
+   <img alt="Star History Chart" src="https://api.star-history.com/svg?repos=Tencent-Hunyuan/Hunyuan3D-2.1&type=Date" />
+ </picture>
+</a>

demo.py

@@ -0,0 +1,47 @@
+import sys
+sys.path.insert(0, './hy3dshape')
+sys.path.insert(0, './hy3dpaint')
+
+from PIL import Image
+from hy3dshape.rembg import BackgroundRemover
+from hy3dshape.pipelines import Hunyuan3DDiTFlowMatchingPipeline
+
+
+from textureGenPipeline import Hunyuan3DPaintPipeline, Hunyuan3DPaintConfig
+
+try:
+    from torchvision_fix import apply_fix
+    apply_fix()
+except ImportError:
+    print("Warning: torchvision_fix module not found, proceeding without compatibility fix")                                      
+except Exception as e:
+    print(f"Warning: Failed to apply torchvision fix: {e}")
+
+# shape
+model_path = 'tencent/Hunyuan3D-2.1'
+pipeline_shapegen = Hunyuan3DDiTFlowMatchingPipeline.from_pretrained(model_path)
+#
+image_path = 'assets/demo.png'
+image = Image.open(image_path).convert("RGBA")
+if image.mode == 'RGB':
+    rembg = BackgroundRemover()
+    image = rembg(image)
+
+mesh = pipeline_shapegen(image=image)[0]
+mesh.export('demo.glb')
+
+# paint
+max_num_view = 6  # can be 6 to 9
+resolution = 512  # can be 768 or 512
+conf = Hunyuan3DPaintConfig(max_num_view, resolution)
+conf.realesrgan_ckpt_path = "hy3dpaint/ckpt/RealESRGAN_x4plus.pth"
+conf.multiview_cfg_path = "hy3dpaint/cfgs/hunyuan-paint-pbr.yaml"
+conf.custom_pipeline = "hy3dpaint/hunyuanpaintpbr"
+paint_pipeline = Hunyuan3DPaintPipeline(conf)
+
+output_mesh_path = 'demo_textured.glb'
+output_mesh_path = paint_pipeline(
+    mesh_path = "demo.glb", 
+    image_path = 'assets/demo.png',
+    output_mesh_path = output_mesh_path
+)

hunyuan3d-dit-v2-1/config.yaml

@@ -0,0 +1,82 @@
+model:
+  target: hy3dshape.models.denoisers.hunyuandit.HunYuanDiTPlain
+  params:
+    input_size: &num_latents 4096
+    in_channels: 64
+    hidden_size: 2048
+    context_dim: 1024
+    depth: 21
+    num_heads: 16
+    qk_norm: true
+    text_len: 1370
+    with_decoupled_ca: false
+    use_attention_pooling: false
+    qk_norm_type: 'rms'
+    qkv_bias: false
+    use_pos_emb: false
+    num_moe_layers: 6
+    num_experts: 8
+    moe_top_k: 2
+
+vae:
+  target: hy3dshape.models.autoencoders.ShapeVAE
+  params:
+    num_latents: *num_latents
+    embed_dim: 64
+    num_freqs: 8
+    include_pi: false
+    heads: 16
+    width: 1024
+    num_encoder_layers: 8
+    num_decoder_layers: 16
+    qkv_bias: false
+    qk_norm: true
+    scale_factor: 1.0039506158752403
+    geo_decoder_mlp_expand_ratio: 4
+    geo_decoder_downsample_ratio: 1
+    geo_decoder_ln_post: true
+    point_feats: 4
+    pc_size: 81920
+    pc_sharpedge_size: 0
+
+conditioner:
+  target: hy3dshape.models.conditioner.SingleImageEncoder
+  params:
+    main_image_encoder:
+        type: DinoImageEncoder # dino large
+        kwargs:
+            config:
+              attention_probs_dropout_prob: 0.0
+              drop_path_rate: 0.0
+              hidden_act: gelu
+              hidden_dropout_prob: 0.0
+              hidden_size: 1024
+              image_size: 518
+              initializer_range: 0.02
+              layer_norm_eps: 1.e-6
+              layerscale_value: 1.0
+              mlp_ratio: 4
+              model_type: dinov2
+              num_attention_heads: 16
+              num_channels: 3
+              num_hidden_layers: 24
+              patch_size: 14
+              qkv_bias: true
+              torch_dtype: float32
+              use_swiglu_ffn: false
+            image_size: 518
+            use_cls_token: true
+
+scheduler:
+  target: hy3dshape.schedulers.FlowMatchEulerDiscreteScheduler
+  params:
+    num_train_timesteps: 1000
+
+image_processor:
+  target: hy3dshape.preprocessors.ImageProcessorV2
+  params:
+    size: 512
+    border_ratio: 0.15
+
+pipeline:
+  target: hy3dshape.pipelines.Hunyuan3DDiTFlowMatchingPipeline

hunyuan3d-dit-v2-1/model.fp16.ckpt

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

hunyuan3d-paintpbr-v2-1/README.md

@@ -0,0 +1,53 @@
+---
+license: openrail++
+tags:
+- stable-diffusion
+- text-to-image
+---
+
+# SD v2.1-base with Zero Terminal SNR (LAION Aesthetic 6+)
+
+This model is used in [Diffusion Model with Perceptual Loss](https://arxiv.org/abs/2401.00110) paper as the MSE baseline.
+
+This model is trained using zero terminal SNR schedule following [Common Diffusion Noise Schedules and Sample Steps are Flawed](https://arxiv.org/abs/2305.08891) paper on LAION aesthetic 6+ data.
+
+This model is finetuned from [stabilityai/stable-diffusion-2-1-base](https://huggingface.co/stabilityai/stable-diffusion-2-1-base).
+
+This model is meant for research demonstration, not for production use.
+
+## Usage
+
+```python
+from diffusers import StableDiffusionPipeline
+prompt = "A young girl smiling"
+pipe = StableDiffusionPipeline.from_pretrained("ByteDance/sd2.1-base-zsnr-laionaes6").to("cuda")
+pipe(prompt, guidance_scale=7.5, guidance_rescale=0.7).images[0].save("out.jpg")
+```
+
+## Related Models
+
+* [bytedance/sd2.1-base-zsnr-laionaes5](https://huggingface.co/ByteDance/sd2.1-base-zsnr-laionaes5)
+* [bytedance/sd2.1-base-zsnr-laionaes6](https://huggingface.co/ByteDance/sd2.1-base-zsnr-laionaes6)
+* [bytedance/sd2.1-base-zsnr-laionaes6-perceptual](https://huggingface.co/ByteDance/sd2.1-base-zsnr-laionaes6-perceptual)
+
+
+## Cite as
+```
+@misc{lin2024diffusion,
+      title={Diffusion Model with Perceptual Loss}, 
+      author={Shanchuan Lin and Xiao Yang},
+      year={2024},
+      eprint={2401.00110},
+      archivePrefix={arXiv},
+      primaryClass={cs.CV}
+}
+
+@misc{lin2023common,
+      title={Common Diffusion Noise Schedules and Sample Steps are Flawed}, 
+      author={Shanchuan Lin and Bingchen Liu and Jiashi Li and Xiao Yang},
+      year={2023},
+      eprint={2305.08891},
+      archivePrefix={arXiv},
+      primaryClass={cs.CV}
+}
+```

hunyuan3d-paintpbr-v2-1/feature_extractor/preprocessor_config.json

@@ -0,0 +1,20 @@
+{
+  "crop_size": 224,
+  "do_center_crop": true,
+  "do_convert_rgb": true,
+  "do_normalize": true,
+  "do_resize": true,
+  "feature_extractor_type": "CLIPFeatureExtractor",
+  "image_mean": [
+    0.48145466,
+    0.4578275,
+    0.40821073
+  ],
+  "image_std": [
+    0.26862954,
+    0.26130258,
+    0.27577711
+  ],
+  "resample": 3,
+  "size": 224
+}

hunyuan3d-paintpbr-v2-1/image_encoder/config.json

@@ -0,0 +1,23 @@
+{
+  "_name_or_path": "vision_encoder",
+  "architectures": [
+    "CLIPVisionModelWithProjection"
+  ],
+  "attention_dropout": 0.0,
+  "dropout": 0.0,
+  "hidden_act": "gelu",
+  "hidden_size": 1280,
+  "image_size": 224,
+  "initializer_factor": 1.0,
+  "initializer_range": 0.02,
+  "intermediate_size": 5120,
+  "layer_norm_eps": 1e-05,
+  "model_type": "clip_vision_model",
+  "num_attention_heads": 16,
+  "num_channels": 3,
+  "num_hidden_layers": 32,
+  "patch_size": 14,
+  "projection_dim": 1024,
+  "torch_dtype": "float16",
+  "transformers_version": "4.36.0"
+}

hunyuan3d-paintpbr-v2-1/image_encoder/model.safetensors

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

hunyuan3d-paintpbr-v2-1/model_index.json

@@ -0,0 +1,37 @@
+{
+  "_class_name": "HunyuanPaintPipeline",
+  "_diffusers_version": "0.24.0",
+  "feature_extractor": [
+    "transformers",
+    "CLIPImageProcessor"
+  ],
+  "requires_safety_checker": false,
+  "safety_checker": [
+    null,
+    null
+  ],
+  "scheduler": [
+    "diffusers",
+    "DDIMScheduler"
+  ],
+  "text_encoder": [
+    "transformers",
+    "CLIPTextModel"
+  ],
+  "tokenizer": [
+    "transformers",
+    "CLIPTokenizer"
+  ],
+  "unet": [
+    "modules",
+    "UNet2p5DConditionModel"
+  ],
+  "vae": [
+    "diffusers",
+    "AutoencoderKL"
+  ],
+  "image_encoder": [
+    "transformers",
+    "CLIPVisionModelWithProjection"
+  ]
+}

hunyuan3d-paintpbr-v2-1/scheduler/scheduler_config.json

@@ -0,0 +1,15 @@
+{
+  "_class_name": "DDIMScheduler",
+  "_diffusers_version": "0.23.1",
+  "beta_end": 0.012,
+  "beta_schedule": "scaled_linear",
+  "beta_start": 0.00085,
+  "clip_sample": false,
+  "num_train_timesteps": 1000,
+  "prediction_type": "v_prediction",
+  "set_alpha_to_one": true,
+  "steps_offset": 1,
+  "trained_betas": null,
+  "timestep_spacing": "trailing",
+  "rescale_betas_zero_snr": true
+}

hunyuan3d-paintpbr-v2-1/text_encoder/config.json

@@ -0,0 +1,25 @@
+{
+  "_name_or_path": "stabilityai/stable-diffusion-2",
+  "architectures": [
+    "CLIPTextModel"
+  ],
+  "attention_dropout": 0.0,
+  "bos_token_id": 0,
+  "dropout": 0.0,
+  "eos_token_id": 2,
+  "hidden_act": "gelu",
+  "hidden_size": 1024,
+  "initializer_factor": 1.0,
+  "initializer_range": 0.02,
+  "intermediate_size": 4096,
+  "layer_norm_eps": 1e-05,
+  "max_position_embeddings": 77,
+  "model_type": "clip_text_model",
+  "num_attention_heads": 16,
+  "num_hidden_layers": 23,
+  "pad_token_id": 1,
+  "projection_dim": 512,
+  "torch_dtype": "float32",
+  "transformers_version": "4.25.0.dev0",
+  "vocab_size": 49408
+}

hunyuan3d-paintpbr-v2-1/text_encoder/pytorch_model.bin

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

hunyuan3d-paintpbr-v2-1/tokenizer/special_tokens_map.json

@@ -0,0 +1,24 @@
+{
+  "bos_token": {
+    "content": "<|startoftext|>",
+    "lstrip": false,
+    "normalized": true,
+    "rstrip": false,
+    "single_word": false
+  },
+  "eos_token": {
+    "content": "<|endoftext|>",
+    "lstrip": false,
+    "normalized": true,
+    "rstrip": false,
+    "single_word": false
+  },
+  "pad_token": "!",
+  "unk_token": {
+    "content": "<|endoftext|>",
+    "lstrip": false,
+    "normalized": true,
+    "rstrip": false,
+    "single_word": false
+  }
+}

hunyuan3d-paintpbr-v2-1/tokenizer/tokenizer_config.json

@@ -0,0 +1,34 @@
+{
+  "add_prefix_space": false,
+  "bos_token": {
+    "__type": "AddedToken",
+    "content": "<|startoftext|>",
+    "lstrip": false,
+    "normalized": true,
+    "rstrip": false,
+    "single_word": false
+  },
+  "do_lower_case": true,
+  "eos_token": {
+    "__type": "AddedToken",
+    "content": "<|endoftext|>",
+    "lstrip": false,
+    "normalized": true,
+    "rstrip": false,
+    "single_word": false
+  },
+  "errors": "replace",
+  "model_max_length": 77,
+  "name_or_path": "stabilityai/stable-diffusion-2",
+  "pad_token": "<|endoftext|>",
+  "special_tokens_map_file": "./special_tokens_map.json",
+  "tokenizer_class": "CLIPTokenizer",
+  "unk_token": {
+    "__type": "AddedToken",
+    "content": "<|endoftext|>",
+    "lstrip": false,
+    "normalized": true,
+    "rstrip": false,
+    "single_word": false
+  }
+}

hunyuan3d-paintpbr-v2-1/unet/attn_processor.py

@@ -0,0 +1,839 @@
+# Hunyuan 3D is licensed under the TENCENT HUNYUAN NON-COMMERCIAL LICENSE AGREEMENT
+# except for the third-party components listed below.
+# Hunyuan 3D does not impose any additional limitations beyond what is outlined
+# in the repsective licenses of these third-party components.
+# Users must comply with all terms and conditions of original licenses of these third-party
+# components and must ensure that the usage of the third party components adheres to
+# all relevant laws and regulations.
+
+# For avoidance of doubts, Hunyuan 3D means the large language models and
+# their software and algorithms, including trained model weights, parameters (including
+# optimizer states), machine-learning model code, inference-enabling code, training-enabling code,
+# fine-tuning enabling code and other elements of the foregoing made publicly available
+# by Tencent in accordance with TENCENT HUNYUAN COMMUNITY LICENSE AGREEMENT.
+
+import torch
+import torch.nn as nn
+import torch.nn.functional as F
+from typing import Optional, Dict, Tuple, Union, Literal, List, Callable
+from einops import rearrange
+from diffusers.utils import deprecate
+from diffusers.models.attention_processor import Attention, AttnProcessor
+
+
+class AttnUtils:
+    """
+    Shared utility functions for attention processing.
+
+    This class provides common operations used across different attention processors
+    to eliminate code duplication and improve maintainability.
+    """
+
+    @staticmethod
+    def check_pytorch_compatibility():
+        """
+        Check PyTorch compatibility for scaled_dot_product_attention.
+
+        Raises:
+            ImportError: If PyTorch version doesn't support scaled_dot_product_attention
+        """
+        if not hasattr(F, "scaled_dot_product_attention"):
+            raise ImportError("AttnProcessor2_0 requires PyTorch 2.0, to use it, please upgrade PyTorch to 2.0.")
+
+    @staticmethod
+    def handle_deprecation_warning(args, kwargs):
+        """
+        Handle deprecation warning for the 'scale' argument.
+
+        Args:
+            args: Positional arguments passed to attention processor
+            kwargs: Keyword arguments passed to attention processor
+        """
+        if len(args) > 0 or kwargs.get("scale", None) is not None:
+            deprecation_message = (
+                "The `scale` argument is deprecated and will be ignored."
+                "Please remove it, as passing it will raise an error in the future."
+                "`scale` should directly be passed while calling the underlying pipeline component"
+                "i.e., via `cross_attention_kwargs`."
+            )
+            deprecate("scale", "1.0.0", deprecation_message)
+
+    @staticmethod
+    def prepare_hidden_states(
+        hidden_states, attn, temb, spatial_norm_attr="spatial_norm", group_norm_attr="group_norm"
+    ):
+        """
+        Common preprocessing of hidden states for attention computation.
+
+        Args:
+            hidden_states: Input hidden states tensor
+            attn: Attention module instance
+            temb: Optional temporal embedding tensor
+            spatial_norm_attr: Attribute name for spatial normalization
+            group_norm_attr: Attribute name for group normalization
+
+        Returns:
+            Tuple of (processed_hidden_states, residual, input_ndim, shape_info)
+        """
+        residual = hidden_states
+
+        spatial_norm = getattr(attn, spatial_norm_attr, None)
+        if spatial_norm is not None:
+            hidden_states = spatial_norm(hidden_states, temb)
+
+        input_ndim = hidden_states.ndim
+
+        if input_ndim == 4:
+            batch_size, channel, height, width = hidden_states.shape
+            hidden_states = hidden_states.view(batch_size, channel, height * width).transpose(1, 2)
+        else:
+            batch_size, channel, height, width = None, None, None, None
+
+        group_norm = getattr(attn, group_norm_attr, None)
+        if group_norm is not None:
+            hidden_states = group_norm(hidden_states.transpose(1, 2)).transpose(1, 2)
+
+        return hidden_states, residual, input_ndim, (batch_size, channel, height, width)
+
+    @staticmethod
+    def prepare_attention_mask(attention_mask, attn, sequence_length, batch_size):
+        """
+        Prepare attention mask for scaled_dot_product_attention.
+
+        Args:
+            attention_mask: Input attention mask tensor or None
+            attn: Attention module instance
+            sequence_length: Length of the sequence
+            batch_size: Batch size
+
+        Returns:
+            Prepared attention mask tensor reshaped for multi-head attention
+        """
+        if attention_mask is not None:
+            attention_mask = attn.prepare_attention_mask(attention_mask, sequence_length, batch_size)
+            attention_mask = attention_mask.view(batch_size, attn.heads, -1, attention_mask.shape[-1])
+        return attention_mask
+
+    @staticmethod
+    def reshape_qkv_for_attention(tensor, batch_size, attn_heads, head_dim):
+        """
+        Reshape Q/K/V tensors for multi-head attention computation.
+
+        Args:
+            tensor: Input tensor to reshape
+            batch_size: Batch size
+            attn_heads: Number of attention heads
+            head_dim: Dimension per attention head
+
+        Returns:
+            Reshaped tensor with shape [batch_size, attn_heads, seq_len, head_dim]
+        """
+        return tensor.view(batch_size, -1, attn_heads, head_dim).transpose(1, 2)
+
+    @staticmethod
+    def apply_norms(query, key, norm_q, norm_k):
+        """
+        Apply Q/K normalization layers if available.
+
+        Args:
+            query: Query tensor
+            key: Key tensor
+            norm_q: Query normalization layer (optional)
+            norm_k: Key normalization layer (optional)
+
+        Returns:
+            Tuple of (normalized_query, normalized_key)
+        """
+        if norm_q is not None:
+            query = norm_q(query)
+        if norm_k is not None:
+            key = norm_k(key)
+        return query, key
+
+    @staticmethod
+    def finalize_output(hidden_states, input_ndim, shape_info, attn, residual, to_out):
+        """
+        Common output processing including projection, dropout, reshaping, and residual connection.
+
+        Args:
+            hidden_states: Processed hidden states from attention
+            input_ndim: Original input tensor dimensions
+            shape_info: Tuple containing original shape information
+            attn: Attention module instance
+            residual: Residual connection tensor
+            to_out: Output projection layers [linear, dropout]
+
+        Returns:
+            Final output tensor after all processing steps
+        """
+        batch_size, channel, height, width = shape_info
+
+        # Apply output projection and dropout
+        hidden_states = to_out[0](hidden_states)
+        hidden_states = to_out[1](hidden_states)
+
+        # Reshape back if needed
+        if input_ndim == 4:
+            hidden_states = hidden_states.transpose(-1, -2).reshape(batch_size, channel, height, width)
+
+        # Apply residual connection
+        if attn.residual_connection:
+            hidden_states = hidden_states + residual
+
+        # Apply rescaling
+        hidden_states = hidden_states / attn.rescale_output_factor
+        return hidden_states
+
+
+# Base class for attention processors (eliminating initialization duplication)
+class BaseAttnProcessor(nn.Module):
+    """
+    Base class for attention processors with common initialization.
+
+    This base class provides shared parameter initialization and module registration
+    functionality to reduce code duplication across different attention processor types.
+    """
+
+    def __init__(
+        self,
+        query_dim: int,
+        pbr_setting: List[str] = ["albedo", "mr"],
+        cross_attention_dim: Optional[int] = None,
+        heads: int = 8,
+        kv_heads: Optional[int] = None,
+        dim_head: int = 64,
+        dropout: float = 0.0,
+        bias: bool = False,
+        upcast_attention: bool = False,
+        upcast_softmax: bool = False,
+        cross_attention_norm: Optional[str] = None,
+        cross_attention_norm_num_groups: int = 32,
+        qk_norm: Optional[str] = None,
+        added_kv_proj_dim: Optional[int] = None,
+        added_proj_bias: Optional[bool] = True,
+        norm_num_groups: Optional[int] = None,
+        spatial_norm_dim: Optional[int] = None,
+        out_bias: bool = True,
+        scale_qk: bool = True,
+        only_cross_attention: bool = False,
+        eps: float = 1e-5,
+        rescale_output_factor: float = 1.0,
+        residual_connection: bool = False,
+        _from_deprecated_attn_block: bool = False,
+        processor: Optional["AttnProcessor"] = None,
+        out_dim: int = None,
+        out_context_dim: int = None,
+        context_pre_only=None,
+        pre_only=False,
+        elementwise_affine: bool = True,
+        is_causal: bool = False,
+        **kwargs,
+    ):
+        """
+        Initialize base attention processor with common parameters.
+
+        Args:
+            query_dim: Dimension of query features
+            pbr_setting: List of PBR material types to process (e.g., ["albedo", "mr"])
+            cross_attention_dim: Dimension of cross-attention features (optional)
+            heads: Number of attention heads
+            kv_heads: Number of key-value heads for grouped query attention (optional)
+            dim_head: Dimension per attention head
+            dropout: Dropout rate
+            bias: Whether to use bias in linear projections
+            upcast_attention: Whether to upcast attention computation to float32
+            upcast_softmax: Whether to upcast softmax computation to float32
+            cross_attention_norm: Type of cross-attention normalization (optional)
+            cross_attention_norm_num_groups: Number of groups for cross-attention norm
+            qk_norm: Type of query-key normalization (optional)
+            added_kv_proj_dim: Dimension for additional key-value projections (optional)
+            added_proj_bias: Whether to use bias in additional projections
+            norm_num_groups: Number of groups for normalization (optional)
+            spatial_norm_dim: Dimension for spatial normalization (optional)
+            out_bias: Whether to use bias in output projection
+            scale_qk: Whether to scale query-key products
+            only_cross_attention: Whether to only perform cross-attention
+            eps: Small epsilon value for numerical stability
+            rescale_output_factor: Factor to rescale output values
+            residual_connection: Whether to use residual connections
+            _from_deprecated_attn_block: Flag for deprecated attention blocks
+            processor: Optional attention processor instance
+            out_dim: Output dimension (optional)
+            out_context_dim: Output context dimension (optional)
+            context_pre_only: Whether to only process context in pre-processing
+            pre_only: Whether to only perform pre-processing
+            elementwise_affine: Whether to use element-wise affine transformations
+            is_causal: Whether to use causal attention masking
+            **kwargs: Additional keyword arguments
+        """
+        super().__init__()
+        AttnUtils.check_pytorch_compatibility()
+
+        # Store common attributes
+        self.pbr_setting = pbr_setting
+        self.n_pbr_tokens = len(self.pbr_setting)
+        self.inner_dim = out_dim if out_dim is not None else dim_head * heads
+        self.inner_kv_dim = self.inner_dim if kv_heads is None else dim_head * kv_heads
+        self.query_dim = query_dim
+        self.use_bias = bias
+        self.is_cross_attention = cross_attention_dim is not None
+        self.cross_attention_dim = cross_attention_dim if cross_attention_dim is not None else query_dim
+        self.upcast_attention = upcast_attention
+        self.upcast_softmax = upcast_softmax
+        self.rescale_output_factor = rescale_output_factor
+        self.residual_connection = residual_connection
+        self.dropout = dropout
+        self.fused_projections = False
+        self.out_dim = out_dim if out_dim is not None else query_dim
+        self.out_context_dim = out_context_dim if out_context_dim is not None else query_dim
+        self.context_pre_only = context_pre_only
+        self.pre_only = pre_only
+        self.is_causal = is_causal
+        self._from_deprecated_attn_block = _from_deprecated_attn_block
+        self.scale_qk = scale_qk
+        self.scale = dim_head**-0.5 if self.scale_qk else 1.0
+        self.heads = out_dim // dim_head if out_dim is not None else heads
+        self.sliceable_head_dim = heads
+        self.added_kv_proj_dim = added_kv_proj_dim
+        self.only_cross_attention = only_cross_attention
+        self.added_proj_bias = added_proj_bias
+
+        # Validation
+        if self.added_kv_proj_dim is None and self.only_cross_attention:
+            raise ValueError(
+                "`only_cross_attention` can only be set to True if `added_kv_proj_dim` is not None."
+                "Make sure to set either `only_cross_attention=False` or define `added_kv_proj_dim`."
+            )
+
+    def register_pbr_modules(self, module_types: List[str], **kwargs):
+        """
+        Generic PBR module registration to eliminate code repetition.
+
+        Dynamically registers PyTorch modules for different PBR material types
+        based on the specified module types and PBR settings.
+
+        Args:
+            module_types: List of module types to register ("qkv", "v_only", "out", "add_kv")
+            **kwargs: Additional arguments for module configuration
+        """
+        for pbr_token in self.pbr_setting:
+            if pbr_token == "albedo":
+                continue
+
+            for module_type in module_types:
+                if module_type == "qkv":
+                    self.register_module(
+                        f"to_q_{pbr_token}", nn.Linear(self.query_dim, self.inner_dim, bias=self.use_bias)
+                    )
+                    self.register_module(
+                        f"to_k_{pbr_token}", nn.Linear(self.cross_attention_dim, self.inner_dim, bias=self.use_bias)
+                    )
+                    self.register_module(
+                        f"to_v_{pbr_token}", nn.Linear(self.cross_attention_dim, self.inner_dim, bias=self.use_bias)
+                    )
+                elif module_type == "v_only":
+                    self.register_module(
+                        f"to_v_{pbr_token}", nn.Linear(self.cross_attention_dim, self.inner_dim, bias=self.use_bias)
+                    )
+                elif module_type == "out":
+                    if not self.pre_only:
+                        self.register_module(
+                            f"to_out_{pbr_token}",
+                            nn.ModuleList(
+                                [
+                                    nn.Linear(self.inner_dim, self.out_dim, bias=kwargs.get("out_bias", True)),
+                                    nn.Dropout(self.dropout),
+                                ]
+                            ),
+                        )
+                    else:
+                        self.register_module(f"to_out_{pbr_token}", None)
+                elif module_type == "add_kv":
+                    if self.added_kv_proj_dim is not None:
+                        self.register_module(
+                            f"add_k_proj_{pbr_token}",
+                            nn.Linear(self.added_kv_proj_dim, self.inner_kv_dim, bias=self.added_proj_bias),
+                        )
+                        self.register_module(
+                            f"add_v_proj_{pbr_token}",
+                            nn.Linear(self.added_kv_proj_dim, self.inner_kv_dim, bias=self.added_proj_bias),
+                        )
+                    else:
+                        self.register_module(f"add_k_proj_{pbr_token}", None)
+                        self.register_module(f"add_v_proj_{pbr_token}", None)
+
+
+# Rotary Position Embedding utilities (specialized for PoseRoPE)
+class RotaryEmbedding:
+    """
+    Rotary position embedding utilities for 3D spatial attention.
+
+    Provides functions to compute and apply rotary position embeddings (RoPE)
+    for 1D, 3D spatial coordinates used in 3D-aware attention mechanisms.
+    """
+
+    @staticmethod
+    def get_1d_rotary_pos_embed(dim: int, pos: torch.Tensor, theta: float = 10000.0, linear_factor=1.0, ntk_factor=1.0):
+        """
+        Compute 1D rotary position embeddings.
+
+        Args:
+            dim: Embedding dimension (must be even)
+            pos: Position tensor
+            theta: Base frequency for rotary embeddings
+            linear_factor: Linear scaling factor
+            ntk_factor: NTK (Neural Tangent Kernel) scaling factor
+
+        Returns:
+            Tuple of (cos_embeddings, sin_embeddings)
+        """
+        assert dim % 2 == 0
+        theta = theta * ntk_factor
+        freqs = (
+            1.0
+            / (theta ** (torch.arange(0, dim, 2, dtype=pos.dtype, device=pos.device)[: (dim // 2)] / dim))
+            / linear_factor
+        )
+        freqs = torch.outer(pos, freqs)
+        freqs_cos = freqs.cos().repeat_interleave(2, dim=1).float()
+        freqs_sin = freqs.sin().repeat_interleave(2, dim=1).float()
+        return freqs_cos, freqs_sin
+
+    @staticmethod
+    def get_3d_rotary_pos_embed(position, embed_dim, voxel_resolution, theta: int = 10000):
+        """
+        Compute 3D rotary position embeddings for spatial coordinates.
+
+        Args:
+            position: 3D position tensor with shape [..., 3]
+            embed_dim: Embedding dimension
+            voxel_resolution: Resolution of the voxel grid
+            theta: Base frequency for rotary embeddings
+
+        Returns:
+            Tuple of (cos_embeddings, sin_embeddings) for 3D positions
+        """
+        assert position.shape[-1] == 3
+        dim_xy = embed_dim // 8 * 3
+        dim_z = embed_dim // 8 * 2
+
+        grid = torch.arange(voxel_resolution, dtype=torch.float32, device=position.device)
+        freqs_xy = RotaryEmbedding.get_1d_rotary_pos_embed(dim_xy, grid, theta=theta)
+        freqs_z = RotaryEmbedding.get_1d_rotary_pos_embed(dim_z, grid, theta=theta)
+
+        xy_cos, xy_sin = freqs_xy
+        z_cos, z_sin = freqs_z
+
+        embed_flattn = position.view(-1, position.shape[-1])
+        x_cos = xy_cos[embed_flattn[:, 0], :]
+        x_sin = xy_sin[embed_flattn[:, 0], :]
+        y_cos = xy_cos[embed_flattn[:, 1], :]
+        y_sin = xy_sin[embed_flattn[:, 1], :]
+        z_cos = z_cos[embed_flattn[:, 2], :]
+        z_sin = z_sin[embed_flattn[:, 2], :]
+
+        cos = torch.cat((x_cos, y_cos, z_cos), dim=-1)
+        sin = torch.cat((x_sin, y_sin, z_sin), dim=-1)
+
+        cos = cos.view(*position.shape[:-1], embed_dim)
+        sin = sin.view(*position.shape[:-1], embed_dim)
+        return cos, sin
+
+    @staticmethod
+    def apply_rotary_emb(x: torch.Tensor, freqs_cis: Union[torch.Tensor, Tuple[torch.Tensor]]):
+        """
+        Apply rotary position embeddings to input tensor.
+
+        Args:
+            x: Input tensor to apply rotary embeddings to
+            freqs_cis: Tuple of (cos_embeddings, sin_embeddings) or single tensor
+
+        Returns:
+            Tensor with rotary position embeddings applied
+        """
+        cos, sin = freqs_cis
+        cos, sin = cos.to(x.device), sin.to(x.device)
+        cos = cos.unsqueeze(1)
+        sin = sin.unsqueeze(1)
+
+        x_real, x_imag = x.reshape(*x.shape[:-1], -1, 2).unbind(-1)
+        x_rotated = torch.stack([-x_imag, x_real], dim=-1).flatten(3)
+
+        out = (x.float() * cos + x_rotated.float() * sin).to(x.dtype)
+        return out
+
+
+# Core attention processing logic (eliminating major duplication)
+class AttnCore:
+    """
+    Core attention processing logic shared across processors.
+
+    This class provides the fundamental attention computation pipeline
+    that can be reused across different attention processor implementations.
+    """
+
+    @staticmethod
+    def process_attention_base(
+        attn: Attention,
+        hidden_states: torch.Tensor,
+        encoder_hidden_states: Optional[torch.Tensor] = None,
+        attention_mask: Optional[torch.Tensor] = None,
+        temb: Optional[torch.Tensor] = None,
+        get_qkv_fn: Callable = None,
+        apply_rope_fn: Optional[Callable] = None,
+        **kwargs,
+    ):
+        """
+        Generic attention processing core shared across different processors.
+
+        This function implements the common attention computation pipeline including:
+        1. Hidden state preprocessing
+        2. Attention mask preparation
+        3. Q/K/V computation via provided function
+        4. Tensor reshaping for multi-head attention
+        5. Optional normalization and RoPE application
+        6. Scaled dot-product attention computation
+
+        Args:
+            attn: Attention module instance
+            hidden_states: Input hidden states tensor
+            encoder_hidden_states: Optional encoder hidden states for cross-attention
+            attention_mask: Optional attention mask tensor
+            temb: Optional temporal embedding tensor
+            get_qkv_fn: Function to compute Q, K, V tensors
+            apply_rope_fn: Optional function to apply rotary position embeddings
+            **kwargs: Additional keyword arguments passed to subfunctions
+
+        Returns:
+            Tuple containing (attention_output, residual, input_ndim, shape_info,
+            batch_size, num_heads, head_dim)
+        """
+        # Prepare hidden states
+        hidden_states, residual, input_ndim, shape_info = AttnUtils.prepare_hidden_states(hidden_states, attn, temb)
+
+        batch_size, sequence_length, _ = (
+            hidden_states.shape if encoder_hidden_states is None else encoder_hidden_states.shape
+        )
+
+        # Prepare attention mask
+        attention_mask = AttnUtils.prepare_attention_mask(attention_mask, attn, sequence_length, batch_size)
+
+        # Get Q, K, V
+        if encoder_hidden_states is None:
+            encoder_hidden_states = hidden_states
+        elif attn.norm_cross:
+            encoder_hidden_states = attn.norm_encoder_hidden_states(encoder_hidden_states)
+
+        query, key, value = get_qkv_fn(attn, hidden_states, encoder_hidden_states, **kwargs)
+
+        # Reshape for attention
+        inner_dim = key.shape[-1]
+        head_dim = inner_dim // attn.heads
+
+        query = AttnUtils.reshape_qkv_for_attention(query, batch_size, attn.heads, head_dim)
+        key = AttnUtils.reshape_qkv_for_attention(key, batch_size, attn.heads, head_dim)
+        value = AttnUtils.reshape_qkv_for_attention(value, batch_size, attn.heads, value.shape[-1] // attn.heads)
+
+        # Apply normalization
+        query, key = AttnUtils.apply_norms(query, key, getattr(attn, "norm_q", None), getattr(attn, "norm_k", None))
+
+        # Apply RoPE if provided
+        if apply_rope_fn is not None:
+            query, key = apply_rope_fn(query, key, head_dim, **kwargs)
+
+        # Compute attention
+        hidden_states = F.scaled_dot_product_attention(
+            query, key, value, attn_mask=attention_mask, dropout_p=0.0, is_causal=False
+        )
+
+        return hidden_states, residual, input_ndim, shape_info, batch_size, attn.heads, head_dim
+
+
+# Specific processor implementations (minimal unique code)
+class PoseRoPEAttnProcessor2_0:
+    """
+    Attention processor with Rotary Position Encoding (RoPE) for 3D spatial awareness.
+
+    This processor extends standard attention with 3D rotary position embeddings
+    to provide spatial awareness for 3D scene understanding tasks.
+    """
+
+    def __init__(self):
+        """Initialize the RoPE attention processor."""
+        AttnUtils.check_pytorch_compatibility()
+
+    def __call__(
+        self,
+        attn: Attention,
+        hidden_states: torch.Tensor,
+        encoder_hidden_states: Optional[torch.Tensor] = None,
+        attention_mask: Optional[torch.Tensor] = None,
+        position_indices: Dict = None,
+        temb: Optional[torch.Tensor] = None,
+        n_pbrs=1,
+        *args,
+        **kwargs,
+    ) -> torch.Tensor:
+        """
+        Apply RoPE-enhanced attention computation.
+
+        Args:
+            attn: Attention module instance
+            hidden_states: Input hidden states tensor
+            encoder_hidden_states: Optional encoder hidden states for cross-attention
+            attention_mask: Optional attention mask tensor
+            position_indices: Dictionary containing 3D position information for RoPE
+            temb: Optional temporal embedding tensor
+            n_pbrs: Number of PBR material types
+            *args: Additional positional arguments
+            **kwargs: Additional keyword arguments
+
+        Returns:
+            Attention output tensor with applied rotary position encodings
+        """
+        AttnUtils.handle_deprecation_warning(args, kwargs)
+
+        def get_qkv(attn, hidden_states, encoder_hidden_states, **kwargs):
+            return attn.to_q(hidden_states), attn.to_k(encoder_hidden_states), attn.to_v(encoder_hidden_states)
+
+        def apply_rope(query, key, head_dim, **kwargs):
+            if position_indices is not None:
+                if head_dim in position_indices:
+                    image_rotary_emb = position_indices[head_dim]
+                else:
+                    image_rotary_emb = RotaryEmbedding.get_3d_rotary_pos_embed(
+                        rearrange(
+                            position_indices["voxel_indices"].unsqueeze(1).repeat(1, n_pbrs, 1, 1),
+                            "b n_pbrs l c -> (b n_pbrs) l c",
+                        ),
+                        head_dim,
+                        voxel_resolution=position_indices["voxel_resolution"],
+                    )
+                    position_indices[head_dim] = image_rotary_emb
+
+                query = RotaryEmbedding.apply_rotary_emb(query, image_rotary_emb)
+                key = RotaryEmbedding.apply_rotary_emb(key, image_rotary_emb)
+            return query, key
+
+        # Core attention processing
+        hidden_states, residual, input_ndim, shape_info, batch_size, heads, head_dim = AttnCore.process_attention_base(
+            attn,
+            hidden_states,
+            encoder_hidden_states,
+            attention_mask,
+            temb,
+            get_qkv_fn=get_qkv,
+            apply_rope_fn=apply_rope,
+            position_indices=position_indices,
+            n_pbrs=n_pbrs,
+        )
+
+        # Finalize output
+        hidden_states = hidden_states.transpose(1, 2).reshape(batch_size, -1, heads * head_dim)
+        hidden_states = hidden_states.to(hidden_states.dtype)
+
+        return AttnUtils.finalize_output(hidden_states, input_ndim, shape_info, attn, residual, attn.to_out)
+
+
+class SelfAttnProcessor2_0(BaseAttnProcessor):
+    """
+    Self-attention processor with PBR (Physically Based Rendering) material support.
+
+    This processor handles multiple PBR material types (e.g., albedo, metallic-roughness)
+    with separate attention computation paths for each material type.
+    """
+
+    def __init__(self, **kwargs):
+        """
+        Initialize self-attention processor with PBR support.
+
+        Args:
+            **kwargs: Arguments passed to BaseAttnProcessor initialization
+        """
+        super().__init__(**kwargs)
+        self.register_pbr_modules(["qkv", "out", "add_kv"], **kwargs)
+
+    def process_single(
+        self,
+        attn: Attention,
+        hidden_states: torch.Tensor,
+        encoder_hidden_states: Optional[torch.Tensor] = None,
+        attention_mask: Optional[torch.Tensor] = None,
+        temb: Optional[torch.Tensor] = None,
+        token: Literal["albedo", "mr"] = "albedo",
+        multiple_devices=False,
+        *args,
+        **kwargs,
+    ):
+        """
+        Process attention for a single PBR material type.
+
+        Args:
+            attn: Attention module instance
+            hidden_states: Input hidden states tensor
+            encoder_hidden_states: Optional encoder hidden states for cross-attention
+            attention_mask: Optional attention mask tensor
+            temb: Optional temporal embedding tensor
+            token: PBR material type to process ("albedo", "mr", etc.)
+            multiple_devices: Whether to use multiple GPU devices
+            *args: Additional positional arguments
+            **kwargs: Additional keyword arguments
+
+        Returns:
+            Processed attention output for the specified PBR material type
+        """
+        target = attn if token == "albedo" else attn.processor
+        token_suffix = "" if token == "albedo" else "_" + token
+
+        # Device management (if needed)
+        if multiple_devices:
+            device = torch.device("cuda:0") if token == "albedo" else torch.device("cuda:1")
+            for attr in [f"to_q{token_suffix}", f"to_k{token_suffix}", f"to_v{token_suffix}", f"to_out{token_suffix}"]:
+                getattr(target, attr).to(device)
+
+        def get_qkv(attn, hidden_states, encoder_hidden_states, **kwargs):
+            return (
+                getattr(target, f"to_q{token_suffix}")(hidden_states),
+                getattr(target, f"to_k{token_suffix}")(encoder_hidden_states),
+                getattr(target, f"to_v{token_suffix}")(encoder_hidden_states),
+            )
+
+        # Core processing using shared logic
+        hidden_states, residual, input_ndim, shape_info, batch_size, heads, head_dim = AttnCore.process_attention_base(
+            attn, hidden_states, encoder_hidden_states, attention_mask, temb, get_qkv_fn=get_qkv
+        )
+
+        # Finalize
+        hidden_states = hidden_states.transpose(1, 2).reshape(batch_size, -1, heads * head_dim)
+        hidden_states = hidden_states.to(hidden_states.dtype)
+
+        return AttnUtils.finalize_output(
+            hidden_states, input_ndim, shape_info, attn, residual, getattr(target, f"to_out{token_suffix}")
+        )
+
+    def __call__(
+        self,
+        attn: Attention,
+        hidden_states: torch.Tensor,
+        encoder_hidden_states: Optional[torch.Tensor] = None,
+        attention_mask: Optional[torch.Tensor] = None,
+        temb: Optional[torch.Tensor] = None,
+        *args,
+        **kwargs,
+    ) -> torch.Tensor:
+        """
+        Apply self-attention with PBR material processing.
+
+        Processes multiple PBR material types sequentially, applying attention
+        computation for each material type separately and combining results.
+
+        Args:
+            attn: Attention module instance
+            hidden_states: Input hidden states tensor with PBR dimension
+            encoder_hidden_states: Optional encoder hidden states for cross-attention
+            attention_mask: Optional attention mask tensor
+            temb: Optional temporal embedding tensor
+            *args: Additional positional arguments
+            **kwargs: Additional keyword arguments
+
+        Returns:
+            Combined attention output for all PBR material types
+        """
+        AttnUtils.handle_deprecation_warning(args, kwargs)
+
+        B = hidden_states.size(0)
+        pbr_hidden_states = torch.split(hidden_states, 1, dim=1)
+
+        # Process each PBR setting
+        results = []
+        for token, pbr_hs in zip(self.pbr_setting, pbr_hidden_states):
+            processed_hs = rearrange(pbr_hs, "b n_pbrs n l c -> (b n_pbrs n) l c").to("cuda:0")
+            result = self.process_single(attn, processed_hs, None, attention_mask, temb, token, False)
+            results.append(result)
+
+        outputs = [rearrange(result, "(b n_pbrs n) l c -> b n_pbrs n l c", b=B, n_pbrs=1) for result in results]
+        return torch.cat(outputs, dim=1)
+
+
+class RefAttnProcessor2_0(BaseAttnProcessor):
+    """
+    Reference attention processor with shared value computation across PBR materials.
+
+    This processor computes query and key once, but uses separate value projections
+    for different PBR material types, enabling efficient multi-material processing.
+    """
+
+    def __init__(self, **kwargs):
+        """
+        Initialize reference attention processor.
+
+        Args:
+            **kwargs: Arguments passed to BaseAttnProcessor initialization
+        """
+        super().__init__(**kwargs)
+        self.pbr_settings = self.pbr_setting  # Alias for compatibility
+        self.register_pbr_modules(["v_only", "out"], **kwargs)
+
+    def __call__(
+        self,
+        attn: Attention,
+        hidden_states: torch.Tensor,
+        encoder_hidden_states: Optional[torch.Tensor] = None,
+        attention_mask: Optional[torch.Tensor] = None,
+        temb: Optional[torch.Tensor] = None,
+        *args,
+        **kwargs,
+    ) -> torch.Tensor:
+        """
+        Apply reference attention with shared Q/K and separate V projections.
+
+        This method computes query and key tensors once and reuses them across
+        all PBR material types, while using separate value projections for each
+        material type to maintain material-specific information.
+
+        Args:
+            attn: Attention module instance
+            hidden_states: Input hidden states tensor
+            encoder_hidden_states: Optional encoder hidden states for cross-attention
+            attention_mask: Optional attention mask tensor
+            temb: Optional temporal embedding tensor
+            *args: Additional positional arguments
+            **kwargs: Additional keyword arguments
+
+        Returns:
+            Stacked attention output for all PBR material types
+        """
+        AttnUtils.handle_deprecation_warning(args, kwargs)
+
+        def get_qkv(attn, hidden_states, encoder_hidden_states, **kwargs):
+            query = attn.to_q(hidden_states)
+            key = attn.to_k(encoder_hidden_states)
+
+            # Concatenate values from all PBR settings
+            value_list = [attn.to_v(encoder_hidden_states)]
+            for token in ["_" + token for token in self.pbr_settings if token != "albedo"]:
+                value_list.append(getattr(attn.processor, f"to_v{token}")(encoder_hidden_states))
+            value = torch.cat(value_list, dim=-1)
+
+            return query, key, value
+
+        # Core processing
+        hidden_states, residual, input_ndim, shape_info, batch_size, heads, head_dim = AttnCore.process_attention_base(
+            attn, hidden_states, encoder_hidden_states, attention_mask, temb, get_qkv_fn=get_qkv
+        )
+
+        # Split and process each PBR setting output
+        hidden_states_list = torch.split(hidden_states, head_dim, dim=-1)
+        output_hidden_states_list = []
+
+        for i, hs in enumerate(hidden_states_list):
+            hs = hs.transpose(1, 2).reshape(batch_size, -1, heads * head_dim).to(hs.dtype)
+            token_suffix = "_" + self.pbr_settings[i] if self.pbr_settings[i] != "albedo" else ""
+            target = attn if self.pbr_settings[i] == "albedo" else attn.processor
+
+            hs = AttnUtils.finalize_output(
+                hs, input_ndim, shape_info, attn, residual, getattr(target, f"to_out{token_suffix}")
+            )
+            output_hidden_states_list.append(hs)
+
+        return torch.stack(output_hidden_states_list, dim=1)

hunyuan3d-paintpbr-v2-1/unet/config.json

@@ -0,0 +1,45 @@
+{
+  "_class_name": "UNet2DConditionModel",
+  "_diffusers_version": "0.10.0.dev0",
+  "act_fn": "silu",
+  "attention_head_dim": [
+    5,
+    10,
+    20,
+    20
+  ],
+  "block_out_channels": [
+    320,
+    640,
+    1280,
+    1280
+  ],
+  "center_input_sample": false,
+  "cross_attention_dim": 1024,
+  "down_block_types": [
+    "CrossAttnDownBlock2D",
+    "CrossAttnDownBlock2D",
+    "CrossAttnDownBlock2D",
+    "DownBlock2D"
+  ],
+  "downsample_padding": 1,
+  "dual_cross_attention": false,
+  "flip_sin_to_cos": true,
+  "freq_shift": 0,
+  "in_channels": 4,
+  "layers_per_block": 2,
+  "mid_block_scale_factor": 1,
+  "norm_eps": 1e-05,
+  "norm_num_groups": 32,
+  "num_class_embeds": null,
+  "only_cross_attention": false,
+  "out_channels": 4,
+  "sample_size": 64,
+  "up_block_types": [
+    "UpBlock2D",
+    "CrossAttnUpBlock2D",
+    "CrossAttnUpBlock2D",
+    "CrossAttnUpBlock2D"
+  ],
+  "use_linear_projection": true
+}

hunyuan3d-paintpbr-v2-1/unet/diffusion_pytorch_model.bin

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

hunyuan3d-paintpbr-v2-1/unet/model.py

@@ -0,0 +1,622 @@
+# Hunyuan 3D is licensed under the TENCENT HUNYUAN NON-COMMERCIAL LICENSE AGREEMENT
+# except for the third-party components listed below.
+# Hunyuan 3D does not impose any additional limitations beyond what is outlined
+# in the repsective licenses of these third-party components.
+# Users must comply with all terms and conditions of original licenses of these third-party
+# components and must ensure that the usage of the third party components adheres to
+# all relevant laws and regulations.
+
+# For avoidance of doubts, Hunyuan 3D means the large language models and
+# their software and algorithms, including trained model weights, parameters (including
+# optimizer states), machine-learning model code, inference-enabling code, training-enabling code,
+# fine-tuning enabling code and other elements of the foregoing made publicly available
+# by Tencent in accordance with TENCENT HUNYUAN COMMUNITY LICENSE AGREEMENT.
+
+import os
+
+# import ipdb
+import numpy as np
+import torch
+import torch.nn as nn
+import torch.nn.functional as F
+import pytorch_lightning as pl
+from tqdm import tqdm
+from torchvision.transforms import v2
+from torchvision.utils import make_grid, save_image
+from einops import rearrange
+
+from diffusers import (
+    DiffusionPipeline,
+    EulerAncestralDiscreteScheduler,
+    DDPMScheduler,
+    UNet2DConditionModel,
+    ControlNetModel,
+)
+
+from .modules import Dino_v2, UNet2p5DConditionModel
+import math
+
+
+def extract_into_tensor(a, t, x_shape):
+    b, *_ = t.shape
+    out = a.gather(-1, t)
+    return out.reshape(b, *((1,) * (len(x_shape) - 1)))
+
+
+class HunyuanPaint(pl.LightningModule):
+    def __init__(
+        self,
+        stable_diffusion_config,
+        control_net_config=None,
+        num_view=6,
+        view_size=320,
+        drop_cond_prob=0.1,
+        with_normal_map=None,
+        with_position_map=None,
+        pbr_settings=["albedo", "mr"],
+        **kwargs,
+    ):
+        """Initializes the HunyuanPaint Lightning Module.
+
+        Args:
+            stable_diffusion_config: Configuration for loading the Stable Diffusion pipeline
+            control_net_config: Configuration for ControlNet (optional)
+            num_view: Number of views to process
+            view_size: Size of input views (height/width)
+            drop_cond_prob: Probability of dropping conditioning input during training
+            with_normal_map: Flag indicating whether normal maps are used
+            with_position_map: Flag indicating whether position maps are used
+            pbr_settings: List of PBR materials to generate (e.g., albedo, metallic-roughness)
+            **kwargs: Additional keyword arguments
+        """
+        super(HunyuanPaint, self).__init__()
+
+        self.num_view = num_view
+        self.view_size = view_size
+        self.drop_cond_prob = drop_cond_prob
+        self.pbr_settings = pbr_settings
+
+        # init modules
+        pipeline = DiffusionPipeline.from_pretrained(**stable_diffusion_config)
+        pipeline.set_pbr_settings(self.pbr_settings)
+        pipeline.scheduler = EulerAncestralDiscreteScheduler.from_config(
+            pipeline.scheduler.config, timestep_spacing="trailing"
+        )
+
+        self.with_normal_map = with_normal_map
+        self.with_position_map = with_position_map
+
+        self.pipeline = pipeline
+
+        self.pipeline.vae.use_slicing = True
+
+        train_sched = DDPMScheduler.from_config(self.pipeline.scheduler.config)
+
+        if isinstance(self.pipeline.unet, UNet2DConditionModel):
+            self.pipeline.unet = UNet2p5DConditionModel(
+                self.pipeline.unet, train_sched, self.pipeline.scheduler, self.pbr_settings
+            )
+        self.train_scheduler = train_sched  # use ddpm scheduler during training
+
+        self.register_schedule()
+
+        pipeline.set_learned_parameters()
+
+        if control_net_config is not None:
+            pipeline.unet = pipeline.unet.bfloat16().requires_grad_(control_net_config.train_unet)
+            self.pipeline.add_controlnet(
+                ControlNetModel.from_pretrained(control_net_config.pretrained_model_name_or_path),
+                conditioning_scale=0.75,
+            )
+
+        self.unet = pipeline.unet
+
+        self.pipeline.set_progress_bar_config(disable=True)
+        self.pipeline.vae = self.pipeline.vae.bfloat16()
+        self.pipeline.text_encoder = self.pipeline.text_encoder.bfloat16()
+
+        if self.unet.use_dino:
+            self.dino_v2 = Dino_v2("facebook/dinov2-giant")
+            self.dino_v2 = self.dino_v2.bfloat16()
+
+        self.validation_step_outputs = []
+
+    def register_schedule(self):
+
+        self.num_timesteps = self.train_scheduler.config.num_train_timesteps
+
+        betas = self.train_scheduler.betas.detach().cpu()
+
+        alphas = 1.0 - betas
+        alphas_cumprod = torch.cumprod(alphas, dim=0)
+        alphas_cumprod_prev = torch.cat([torch.ones(1, dtype=torch.float64), alphas_cumprod[:-1]], 0)
+
+        self.register_buffer("betas", betas.float())
+        self.register_buffer("alphas_cumprod", alphas_cumprod.float())
+        self.register_buffer("alphas_cumprod_prev", alphas_cumprod_prev.float())
+
+        # calculations for diffusion q(x_t | x_{t-1}) and others
+        self.register_buffer("sqrt_alphas_cumprod", torch.sqrt(alphas_cumprod).float())
+        self.register_buffer("sqrt_one_minus_alphas_cumprod", torch.sqrt(1 - alphas_cumprod).float())
+
+        self.register_buffer("sqrt_recip_alphas_cumprod", torch.sqrt(1.0 / alphas_cumprod).float())
+        self.register_buffer("sqrt_recipm1_alphas_cumprod", torch.sqrt(1.0 / alphas_cumprod - 1).float())
+
+    def on_fit_start(self):
+        device = torch.device(f"cuda:{self.local_rank}")
+        self.pipeline.to(device)
+        if self.global_rank == 0:
+            os.makedirs(os.path.join(self.logdir, "images_val"), exist_ok=True)
+
+    def prepare_batch_data(self, batch):
+        """Preprocesses a batch of input data for training/inference.
+
+        Args:
+            batch: Raw input batch dictionary
+
+        Returns:
+            tuple: Contains:
+                - cond_imgs: Primary conditioning images (B, 1, C, H, W)
+                - cond_imgs_another: Secondary conditioning images (B, 1, C, H, W)
+                - target_imgs: Dictionary of target PBR images resized and clamped
+                - images_normal: Preprocessed normal maps (if available)
+                - images_position: Preprocessed position maps (if available)
+        """
+
+        images_cond = batch["images_cond"].to(self.device)  # (B, M, C, H, W), where M is the number of reference images
+        cond_imgs, cond_imgs_another = images_cond[:, 0:1, ...], images_cond[:, 1:2, ...]
+
+        cond_size = self.view_size
+        cond_imgs = v2.functional.resize(cond_imgs, cond_size, interpolation=3, antialias=True).clamp(0, 1)
+        cond_imgs_another = v2.functional.resize(cond_imgs_another, cond_size, interpolation=3, antialias=True).clamp(
+            0, 1
+        )
+
+        target_imgs = {}
+        for pbr_token in self.pbr_settings:
+            target_imgs[pbr_token] = batch[f"images_{pbr_token}"].to(self.device)
+            target_imgs[pbr_token] = v2.functional.resize(
+                target_imgs[pbr_token], self.view_size, interpolation=3, antialias=True
+            ).clamp(0, 1)
+
+        images_normal = None
+        if "images_normal" in batch:
+            images_normal = batch["images_normal"]  # (B, N, C, H, W)
+            images_normal = v2.functional.resize(images_normal, self.view_size, interpolation=3, antialias=True).clamp(
+                0, 1
+            )
+            images_normal = [images_normal]
+
+        images_position = None
+        if "images_position" in batch:
+            images_position = batch["images_position"]  # (B, N, C, H, W)
+            images_position = v2.functional.resize(
+                images_position, self.view_size, interpolation=3, antialias=True
+            ).clamp(0, 1)
+            images_position = [images_position]
+
+        return cond_imgs, cond_imgs_another, target_imgs, images_normal, images_position
+
+    @torch.no_grad()
+    def forward_text_encoder(self, prompts):
+        device = next(self.pipeline.vae.parameters()).device
+        text_embeds = self.pipeline.encode_prompt(prompts, device, 1, False)[0]
+        return text_embeds
+
+    @torch.no_grad()
+    def encode_images(self, images):
+        """Encodes input images into latent representations using the VAE.
+
+        Handles both standard input (B, N, C, H, W) and PBR input (B, N_pbrs, N, C, H, W)
+        Maintains original batch structure in output latents.
+
+        Args:
+            images: Input images tensor
+
+        Returns:
+            torch.Tensor: Latent representations with original batch dimensions preserved
+        """
+
+        B = images.shape[0]
+        image_ndims = images.ndim
+        if image_ndims != 5:
+            N_pbrs, N = images.shape[1:3]
+        images = (
+            rearrange(images, "b n c h w -> (b n) c h w")
+            if image_ndims == 5
+            else rearrange(images, "b n_pbrs n c h w -> (b n_pbrs n) c h w")
+        )
+        dtype = next(self.pipeline.vae.parameters()).dtype
+
+        images = (images - 0.5) * 2.0
+        posterior = self.pipeline.vae.encode(images.to(dtype)).latent_dist
+        latents = posterior.sample() * self.pipeline.vae.config.scaling_factor
+
+        latents = (
+            rearrange(latents, "(b n) c h w -> b n c h w", b=B)
+            if image_ndims == 5
+            else rearrange(latents, "(b n_pbrs n) c h w -> b n_pbrs n c h w", b=B, n_pbrs=N_pbrs)
+        )
+
+        return latents
+
+    def forward_unet(self, latents, t, **cached_condition):
+        """Runs the UNet model to predict noise/latent residuals.
+
+        Args:
+            latents: Noisy latent representations (B, C, H, W)
+            t: Timestep tensor (B,)
+            **cached_condition: Dictionary of conditioning inputs (text embeds, reference images, etc)
+
+        Returns:
+            torch.Tensor: UNet output (predicted noise or velocity)
+        """
+
+        dtype = next(self.unet.parameters()).dtype
+        latents = latents.to(dtype)
+        shading_embeds = cached_condition["shading_embeds"]
+        pred_noise = self.pipeline.unet(latents, t, encoder_hidden_states=shading_embeds, **cached_condition)
+        return pred_noise[0]
+
+    def predict_start_from_z_and_v(self, x_t, t, v):
+        """
+        Predicts clean image (x0) from noisy latents (x_t) and
+        velocity prediction (v) using the v-prediction formula.
+
+        Args:
+            x_t: Noisy latents at timestep t
+            t: Current timestep
+            v: Predicted velocity (v) from UNet
+
+        Returns:
+            torch.Tensor: Predicted clean image (x0)
+        """
+
+        return (
+            extract_into_tensor(self.sqrt_alphas_cumprod, t, x_t.shape) * x_t
+            - extract_into_tensor(self.sqrt_one_minus_alphas_cumprod, t, x_t.shape) * v
+        )
+
+    def get_v(self, x, noise, t):
+        """Computes the target velocity (v) for v-prediction training.
+
+        Args:
+            x: Clean latents (x0)
+            noise: Added noise
+            t: Current timestep
+
+        Returns:
+            torch.Tensor: Target velocity
+        """
+
+        return (
+            extract_into_tensor(self.sqrt_alphas_cumprod, t, x.shape) * noise
+            - extract_into_tensor(self.sqrt_one_minus_alphas_cumprod, t, x.shape) * x
+        )
+
+    def training_step(self, batch, batch_idx):
+        """Performs a single training step with both conditioning paths.
+
+        Implements:
+        1. Dual-conditioning path training (main ref + secondary ref)
+        2. Velocity-prediction with consistency loss
+        3. Conditional dropout for robust learning
+        4. PBR-specific losses (albedo/metallic-roughness)
+
+        Args:
+            batch: Input batch from dataloader
+            batch_idx: Index of current batch
+
+        Returns:
+            torch.Tensor: Combined loss value
+        """
+
+        cond_imgs, cond_imgs_another, target_imgs, normal_imgs, position_imgs = self.prepare_batch_data(batch)
+
+        B, N_ref = cond_imgs.shape[:2]
+        _, N_gen, _, H, W = target_imgs["albedo"].shape
+        N_pbrs = len(self.pbr_settings)
+        t = torch.randint(0, self.num_timesteps, size=(B,)).long().to(self.device)
+        t = t.unsqueeze(-1).repeat(1, N_pbrs, N_gen)
+        t = rearrange(t, "b n_pbrs n -> (b n_pbrs n)")
+
+        all_target_pbrs = []
+        for pbr_token in self.pbr_settings:
+            all_target_pbrs.append(target_imgs[pbr_token])
+        all_target_pbrs = torch.stack(all_target_pbrs, dim=0).transpose(1, 0)
+        gen_latents = self.encode_images(all_target_pbrs)  #! B, N_pbrs N C H W
+        ref_latents = self.encode_images(cond_imgs)  #! B, M, C, H, W
+        ref_latents_another = self.encode_images(cond_imgs_another)  #! B, M, C, H, W
+
+        all_shading_tokens = []
+        for token in self.pbr_settings:
+            if token in ["albedo", "mr"]:
+                all_shading_tokens.append(
+                    getattr(self.unet, f"learned_text_clip_{token}").unsqueeze(dim=0).repeat(B, 1, 1)
+                )
+        shading_embeds = torch.stack(all_shading_tokens, dim=1)
+
+        if self.unet.use_dino:
+            dino_hidden_states = self.dino_v2(cond_imgs[:, :1, ...])
+            dino_hidden_states_another = self.dino_v2(cond_imgs_another[:, :1, ...])
+
+        gen_latents = rearrange(gen_latents, "b n_pbrs n c h w -> (b n_pbrs n) c h w")
+        noise = torch.randn_like(gen_latents).to(self.device)
+        latents_noisy = self.train_scheduler.add_noise(gen_latents, noise, t).to(self.device)
+        latents_noisy = rearrange(latents_noisy, "(b n_pbrs n) c h w -> b n_pbrs n c h w", b=B, n_pbrs=N_pbrs)
+
+        cached_condition = {}
+
+        if normal_imgs is not None:
+            normal_embeds = self.encode_images(normal_imgs[0])
+            cached_condition["embeds_normal"] = normal_embeds  #! B, N, C, H, W
+
+        if position_imgs is not None:
+            position_embeds = self.encode_images(position_imgs[0])
+            cached_condition["embeds_position"] = position_embeds  #! B, N, C, H, W
+            cached_condition["position_maps"] = position_imgs[0]  #! B, N, C, H, W
+
+        for b in range(B):
+            prob = np.random.rand()
+            if prob < self.drop_cond_prob:
+                if "normal_imgs" in cached_condition:
+                    cached_condition["embeds_normal"][b, ...] = torch.zeros_like(
+                        cached_condition["embeds_normal"][b, ...]
+                    )
+                if "position_imgs" in cached_condition:
+                    cached_condition["embeds_position"][b, ...] = torch.zeros_like(
+                        cached_condition["embeds_position"][b, ...]
+                    )
+
+            prob = np.random.rand()
+            if prob < self.drop_cond_prob:
+                if "position_maps" in cached_condition:
+                    cached_condition["position_maps"][b, ...] = torch.zeros_like(
+                        cached_condition["position_maps"][b, ...]
+                    )
+
+            prob = np.random.rand()
+            if prob < self.drop_cond_prob:
+                dino_hidden_states[b, ...] = torch.zeros_like(dino_hidden_states[b, ...])
+            prob = np.random.rand()
+            if prob < self.drop_cond_prob:
+                dino_hidden_states_another[b, ...] = torch.zeros_like(dino_hidden_states_another[b, ...])
+
+        # MVA & Ref Attention
+        prob = np.random.rand()
+        cached_condition["mva_scale"] = 1.0
+        cached_condition["ref_scale"] = 1.0
+        if prob < self.drop_cond_prob:
+            cached_condition["mva_scale"] = 0.0
+            cached_condition["ref_scale"] = 0.0
+        elif prob > 1.0 - self.drop_cond_prob:
+            prob = np.random.rand()
+            if prob < 0.5:
+                cached_condition["mva_scale"] = 0.0
+            else:
+                cached_condition["ref_scale"] = 0.0
+        else:
+            pass
+
+        if self.train_scheduler.config.prediction_type == "v_prediction":
+
+            cached_condition["shading_embeds"] = shading_embeds
+            cached_condition["ref_latents"] = ref_latents
+            cached_condition["dino_hidden_states"] = dino_hidden_states
+            v_pred = self.forward_unet(latents_noisy, t, **cached_condition)
+            v_pred_albedo, v_pred_mr = torch.split(
+                rearrange(
+                    v_pred, "(b n_pbr n) c h w -> b n_pbr n c h w", n_pbr=len(self.pbr_settings), n=self.num_view
+                ),
+                1,
+                dim=1,
+            )
+            v_target = self.get_v(gen_latents, noise, t)
+            v_target_albedo, v_target_mr = torch.split(
+                rearrange(
+                    v_target, "(b n_pbr n) c h w -> b n_pbr n c h w", n_pbr=len(self.pbr_settings), n=self.num_view
+                ),
+                1,
+                dim=1,
+            )
+
+            albedo_loss_1, _ = self.compute_loss(v_pred_albedo, v_target_albedo)
+            mr_loss_1, _ = self.compute_loss(v_pred_mr, v_target_mr)
+
+            cached_condition["ref_latents"] = ref_latents_another
+            cached_condition["dino_hidden_states"] = dino_hidden_states_another
+            v_pred_another = self.forward_unet(latents_noisy, t, **cached_condition)
+            v_pred_another_albedo, v_pred_another_mr = torch.split(
+                rearrange(
+                    v_pred_another,
+                    "(b n_pbr n) c h w -> b n_pbr n c h w",
+                    n_pbr=len(self.pbr_settings),
+                    n=self.num_view,
+                ),
+                1,
+                dim=1,
+            )
+
+            albedo_loss_2, _ = self.compute_loss(v_pred_another_albedo, v_target_albedo)
+            mr_loss_2, _ = self.compute_loss(v_pred_another_mr, v_target_mr)
+
+            consistency_loss, _ = self.compute_loss(v_pred_another, v_pred)
+
+            albedo_loss = (albedo_loss_1 + albedo_loss_2) * 0.5
+            mr_loss = (mr_loss_1 + mr_loss_2) * 0.5
+
+            log_loss_dict = {}
+            log_loss_dict.update({f"train/albedo_loss": albedo_loss})
+            log_loss_dict.update({f"train/mr_loss": mr_loss})
+            log_loss_dict.update({f"train/cons_loss": consistency_loss})
+
+            loss_dict = log_loss_dict
+
+        elif self.train_scheduler.config.prediction_type == "epsilon":
+            e_pred = self.forward_unet(latents_noisy, t, **cached_condition)
+            loss, loss_dict = self.compute_loss(e_pred, noise)
+        else:
+            raise f"No {self.train_scheduler.config.prediction_type}"
+
+        # logging
+        self.log_dict(loss_dict, prog_bar=True, logger=True, on_step=True, on_epoch=True)
+        self.log("global_step", self.global_step, prog_bar=True, logger=True, on_step=True, on_epoch=False)
+        lr = self.optimizers().param_groups[0]["lr"]
+        self.log("lr_abs", lr, prog_bar=True, logger=True, on_step=True, on_epoch=False)
+
+        return 0.85 * (albedo_loss + mr_loss) + 0.15 * consistency_loss
+
+    def compute_loss(self, noise_pred, noise_gt):
+        loss = F.mse_loss(noise_pred, noise_gt)
+        prefix = "train"
+        loss_dict = {}
+        loss_dict.update({f"{prefix}/loss": loss})
+        return loss, loss_dict
+
+    @torch.no_grad()
+    def validation_step(self, batch, batch_idx):
+        """Performs validation on a single batch.
+
+        Generates predicted images using:
+        1. Reference conditioning images
+        2. Optional normal/position maps
+        3. Frozen DINO features (if enabled)
+        4. Text prompt conditioning
+
+        Compares predictions against ground truth targets and prepares visualization.
+        Stores results for epoch-level aggregation.
+
+        Args:
+            batch: Input batch from validation dataloader
+            batch_idx: Index of current batch
+        """
+        # [Validation image generation and comparison logic...]
+        # Key steps:
+        # 1. Preprocess conditioning images to PIL format
+        # 2. Set up conditioning inputs (normal maps, position maps, DINO features)
+        # 3. Run pipeline inference with fixed prompt ("high quality")
+        # 4. Decode latent outputs to image space
+        # 5. Arrange predictions and ground truths for visualization
+
+        cond_imgs_tensor, _, target_imgs, normal_imgs, position_imgs = self.prepare_batch_data(batch)
+        resolution = self.view_size
+        image_pils = []
+        for i in range(cond_imgs_tensor.shape[0]):
+            image_pils.append([])
+            for j in range(cond_imgs_tensor.shape[1]):
+                image_pils[-1].append(v2.functional.to_pil_image(cond_imgs_tensor[i, j, ...]))
+
+        outputs, gts = [], []
+        for idx in range(len(image_pils)):
+            cond_imgs = image_pils[idx]
+
+            cached_condition = dict(num_in_batch=self.num_view, N_pbrs=len(self.pbr_settings))
+            if normal_imgs is not None:
+                cached_condition["images_normal"] = normal_imgs[0][idx, ...].unsqueeze(0)
+            if position_imgs is not None:
+                cached_condition["images_position"] = position_imgs[0][idx, ...].unsqueeze(0)
+            if self.pipeline.unet.use_dino:
+                dino_hidden_states = self.dino_v2([cond_imgs][0])
+                cached_condition["dino_hidden_states"] = dino_hidden_states
+
+            latent = self.pipeline(
+                cond_imgs,
+                prompt="high quality",
+                num_inference_steps=30,
+                output_type="latent",
+                height=resolution,
+                width=resolution,
+                **cached_condition,
+            ).images
+
+            image = self.pipeline.vae.decode(latent / self.pipeline.vae.config.scaling_factor, return_dict=False)[
+                0
+            ]  # [-1, 1]
+            image = (image * 0.5 + 0.5).clamp(0, 1)
+
+            image = rearrange(
+                image, "(b n_pbr n) c h w -> b n_pbr n c h w", n_pbr=len(self.pbr_settings), n=self.num_view
+            )
+            image = torch.cat((torch.ones_like(image[:, :, :1, ...]) * 0.5, image), dim=2)
+            image = rearrange(image, "b n_pbr n c h w -> (b n_pbr n) c h w")
+            image = rearrange(
+                image,
+                "(b n_pbr n) c h w -> b c (n_pbr h) (n w)",
+                b=1,
+                n_pbr=len(self.pbr_settings),
+                n=self.num_view + 1,
+            )
+            outputs.append(image)
+
+        all_target_pbrs = []
+        for pbr_token in self.pbr_settings:
+            all_target_pbrs.append(target_imgs[pbr_token])
+        all_target_pbrs = torch.stack(all_target_pbrs, dim=0).transpose(1, 0)
+        all_target_pbrs = torch.cat(
+            (cond_imgs_tensor.unsqueeze(1).repeat(1, len(self.pbr_settings), 1, 1, 1, 1), all_target_pbrs), dim=2
+        )
+        all_target_pbrs = rearrange(all_target_pbrs, "b n_pbrs n c h w -> b c (n_pbrs h) (n w)")
+        gts = all_target_pbrs
+        outputs = torch.cat(outputs, dim=0).to(self.device)
+        images = torch.cat([gts, outputs], dim=-2)
+        self.validation_step_outputs.append(images)
+
+    @torch.no_grad()
+    def on_validation_epoch_end(self):
+        """Aggregates validation results at epoch end.
+
+        Gathers outputs from all GPUs (if distributed training),
+        creates a unified visualization grid, and saves to disk.
+        Only rank 0 process performs saving.
+        """
+        # [Result aggregation and visualization...]
+        # Key steps:
+        # 1. Gather validation outputs from all processes
+        # 2. Create image grid combining ground truths and predictions
+        # 3. Save visualization with step-numbered filename
+        # 4. Clear memory for next validation cycle
+
+        images = torch.cat(self.validation_step_outputs, dim=0)
+        all_images = self.all_gather(images)
+        all_images = rearrange(all_images, "r b c h w -> (r b) c h w")
+
+        if self.global_rank == 0:
+            grid = make_grid(all_images, nrow=8, normalize=True, value_range=(0, 1))
+            save_image(grid, os.path.join(self.logdir, "images_val", f"val_{self.global_step:07d}.png"))
+
+        self.validation_step_outputs.clear()  # free memory
+
+    def configure_optimizers(self):
+        lr = self.learning_rate
+        optimizer = torch.optim.AdamW(self.unet.parameters(), lr=lr)
+
+        def lr_lambda(step):
+            warm_up_step = 1000
+            T_step = 9000
+            gamma = 0.9
+            min_lr = 0.1 if step >= warm_up_step else 0.0
+            max_lr = 1.0
+            normalized_step = step % (warm_up_step + T_step)
+            current_max_lr = max_lr * gamma ** (step // (warm_up_step + T_step))
+            if current_max_lr < min_lr:
+                current_max_lr = min_lr
+            if normalized_step < warm_up_step:
+                lr_step = min_lr + (normalized_step / warm_up_step) * (current_max_lr - min_lr)
+            else:
+                step_wc_wp = normalized_step - warm_up_step
+                ratio = step_wc_wp / T_step
+                lr_step = min_lr + 0.5 * (current_max_lr - min_lr) * (1 + math.cos(math.pi * ratio))
+            return lr_step
+
+        lr_scheduler = torch.optim.lr_scheduler.LambdaLR(optimizer, lr_lambda)
+
+        lr_scheduler_config = {
+            "scheduler": lr_scheduler,
+            "interval": "step",
+            "frequency": 1,
+            "monitor": "val_loss",
+            "strict": False,
+            "name": None,
+        }
+
+        return {"optimizer": optimizer, "lr_scheduler": lr_scheduler_config}

hunyuan3d-paintpbr-v2-1/unet/modules.py

@@ -0,0 +1,1102 @@
+# Hunyuan 3D is licensed under the TENCENT HUNYUAN NON-COMMERCIAL LICENSE AGREEMENT
+# except for the third-party components listed below.
+# Hunyuan 3D does not impose any additional limitations beyond what is outlined
+# in the repsective licenses of these third-party components.
+# Users must comply with all terms and conditions of original licenses of these third-party
+# components and must ensure that the usage of the third party components adheres to
+# all relevant laws and regulations.
+
+# For avoidance of doubts, Hunyuan 3D means the large language models and
+# their software and algorithms, including trained model weights, parameters (including
+# optimizer states), machine-learning model code, inference-enabling code, training-enabling code,
+# fine-tuning enabling code and other elements of the foregoing made publicly available
+# by Tencent in accordance with TENCENT HUNYUAN COMMUNITY LICENSE AGREEMENT.
+
+import os
+import json
+import copy
+import numpy as np
+import torch
+import torch.nn as nn
+from einops import rearrange
+from typing import Any, Callable, Dict, List, Optional, Union, Tuple, Literal
+import diffusers
+from diffusers.utils import deprecate
+from diffusers import (
+    DDPMScheduler,
+    EulerAncestralDiscreteScheduler,
+    UNet2DConditionModel,
+)
+from diffusers.models import UNet2DConditionModel
+from diffusers.models.attention_processor import Attention, AttnProcessor
+from diffusers.models.transformers.transformer_2d import BasicTransformerBlock
+from .attn_processor import SelfAttnProcessor2_0, RefAttnProcessor2_0, PoseRoPEAttnProcessor2_0
+
+from transformers import AutoImageProcessor, AutoModel
+
+
+class Dino_v2(nn.Module):
+
+    """Wrapper for DINOv2 vision transformer (frozen weights).
+    
+    Provides feature extraction for reference images.
+    
+    Args:
+        dino_v2_path: Custom path to DINOv2 model weights (uses default if None)
+    """
+
+
+    def __init__(self, dino_v2_path):
+        super(Dino_v2, self).__init__()
+        self.dino_processor = AutoImageProcessor.from_pretrained(dino_v2_path)
+        self.dino_v2 = AutoModel.from_pretrained(dino_v2_path)
+
+        for param in self.parameters():
+            param.requires_grad = False
+
+        self.dino_v2.eval()
+
+    def forward(self, images):
+
+        """Processes input images through DINOv2 ViT.
+        
+        Handles both tensor input (B, N, C, H, W) and PIL image lists.
+        Extracts patch embeddings and flattens spatial dimensions.
+        
+        Returns:
+            torch.Tensor: Feature vectors [B, N*(num_patches), feature_dim]
+        """
+
+        if isinstance(images, torch.Tensor):
+            batch_size = images.shape[0]
+            dino_proceesed_images = self.dino_processor(
+                images=rearrange(images, "b n c h w -> (b n) c h w"), return_tensors="pt", do_rescale=False
+            ).pixel_values
+        else:
+            batch_size = 1
+            dino_proceesed_images = self.dino_processor(images=images, return_tensors="pt").pixel_values
+            dino_proceesed_images = torch.stack(
+                [torch.from_numpy(np.array(image)) for image in dino_proceesed_images], dim=0
+            )
+        dino_param = next(self.dino_v2.parameters())
+        dino_proceesed_images = dino_proceesed_images.to(dino_param)
+        dino_hidden_states = self.dino_v2(dino_proceesed_images)[0]
+        dino_hidden_states = rearrange(dino_hidden_states.to(dino_param), "(b n) l c -> b (n l) c", b=batch_size)
+
+        return dino_hidden_states
+
+
+def _chunked_feed_forward(ff: nn.Module, hidden_states: torch.Tensor, chunk_dim: int, chunk_size: int):
+    # "feed_forward_chunk_size" can be used to save memory
+
+    """Memory-efficient feedforward execution via chunking.
+    
+    Divides input along specified dimension for sequential processing.
+    
+    Args:
+        ff: Feedforward module to apply
+        hidden_states: Input tensor
+        chunk_dim: Dimension to split
+        chunk_size: Size of each chunk
+        
+    Returns:
+        torch.Tensor: Reassembled output tensor
+    """
+
+    if hidden_states.shape[chunk_dim] % chunk_size != 0:
+        raise ValueError(
+            f"`hidden_states` dimension to be chunked: {hidden_states.shape[chunk_dim]}"
+            f"has to be divisible by chunk size: {chunk_size}."
+            "Make sure to set an appropriate `chunk_size` when calling `unet.enable_forward_chunking`."
+        )
+
+    num_chunks = hidden_states.shape[chunk_dim] // chunk_size
+    ff_output = torch.cat(
+        [ff(hid_slice) for hid_slice in hidden_states.chunk(num_chunks, dim=chunk_dim)],
+        dim=chunk_dim,
+    )
+    return ff_output
+
+
+@torch.no_grad()
+def compute_voxel_grid_mask(position, grid_resolution=8):
+
+    """Generates view-to-view attention mask based on 3D position similarity.
+    
+    Uses voxel grid downsampling to determine spatially adjacent regions.
+    Mask indicates where features should interact across different views.
+    
+    Args:
+        position: Position maps [B, N, 3, H, W] (normalized 0-1)
+        grid_resolution: Spatial reduction factor
+        
+    Returns:
+        torch.Tensor: Attention mask [B, N*grid_res**2, N*grid_res**2]
+    """
+
+    position = position.half()
+    B, N, _, H, W = position.shape
+    assert H % grid_resolution == 0 and W % grid_resolution == 0
+
+    valid_mask = (position != 1).all(dim=2, keepdim=True)
+    valid_mask = valid_mask.expand_as(position)
+    position[valid_mask == False] = 0
+
+    position = rearrange(
+        position,
+        "b n c (num_h grid_h) (num_w grid_w) -> b n num_h num_w c grid_h grid_w",
+        num_h=grid_resolution,
+        num_w=grid_resolution,
+    )
+    valid_mask = rearrange(
+        valid_mask,
+        "b n c (num_h grid_h) (num_w grid_w) -> b n num_h num_w c grid_h grid_w",
+        num_h=grid_resolution,
+        num_w=grid_resolution,
+    )
+
+    grid_position = position.sum(dim=(-2, -1))
+    count_masked = valid_mask.sum(dim=(-2, -1))
+
+    grid_position = grid_position / count_masked.clamp(min=1)
+    grid_position[count_masked < 5] = 0
+
+    grid_position = grid_position.permute(0, 1, 4, 2, 3)
+    grid_position = rearrange(grid_position, "b n c h w -> b n (h w) c")
+
+    grid_position_expanded_1 = grid_position.unsqueeze(2).unsqueeze(4)  # 形状变为 B, N, 1, L, 1, 3
+    grid_position_expanded_2 = grid_position.unsqueeze(1).unsqueeze(3)  # 形状变为 B, 1, N, 1, L, 3
+
+    # 计算欧氏距离
+    distances = torch.norm(grid_position_expanded_1 - grid_position_expanded_2, dim=-1)  # 形状为 B, N, N, L, L
+
+    weights = distances
+    grid_distance = 1.73 / grid_resolution
+    weights = weights < grid_distance
+
+    return weights
+
+
+def compute_multi_resolution_mask(position_maps, grid_resolutions=[32, 16, 8]):
+
+    """Generates attention masks at multiple spatial resolutions.
+    
+    Creates pyramid of position-based masks for hierarchical attention.
+    
+    Args:
+        position_maps: Position maps [B, N, 3, H, W]
+        grid_resolutions: List of downsampling factors
+        
+    Returns:
+        dict: Resolution-specific masks keyed by flattened dimension size
+    """
+
+    position_attn_mask = {}
+    with torch.no_grad():
+        for grid_resolution in grid_resolutions:
+            position_mask = compute_voxel_grid_mask(position_maps, grid_resolution)
+            position_mask = rearrange(position_mask, "b ni nj li lj -> b (ni li) (nj lj)")
+            position_attn_mask[position_mask.shape[1]] = position_mask
+    return position_attn_mask
+
+
+@torch.no_grad()
+def compute_discrete_voxel_indice(position, grid_resolution=8, voxel_resolution=128):
+
+    """Quantizes position maps to discrete voxel indices.
+    
+    Creates sparse 3D coordinate representations for efficient hashing.
+    
+    Args:
+        position: Position maps [B, N, 3, H, W]
+        grid_resolution: Spatial downsampling factor
+        voxel_resolution: Quantization resolution
+        
+    Returns:
+        torch.Tensor: Voxel indices [B, N, grid_res, grid_res, 3]
+    """
+
+    position = position.half()
+    B, N, _, H, W = position.shape
+    assert H % grid_resolution == 0 and W % grid_resolution == 0
+
+    valid_mask = (position != 1).all(dim=2, keepdim=True)
+    valid_mask = valid_mask.expand_as(position)
+    position[valid_mask == False] = 0
+
+    position = rearrange(
+        position,
+        "b n c (num_h grid_h) (num_w grid_w) -> b n num_h num_w c grid_h grid_w",
+        num_h=grid_resolution,
+        num_w=grid_resolution,
+    )
+    valid_mask = rearrange(
+        valid_mask,
+        "b n c (num_h grid_h) (num_w grid_w) -> b n num_h num_w c grid_h grid_w",
+        num_h=grid_resolution,
+        num_w=grid_resolution,
+    )
+
+    grid_position = position.sum(dim=(-2, -1))
+    count_masked = valid_mask.sum(dim=(-2, -1))
+
+    grid_position = grid_position / count_masked.clamp(min=1)
+    voxel_mask_thres = (H // grid_resolution) * (W // grid_resolution) // (4 * 4)
+    grid_position[count_masked < voxel_mask_thres] = 0
+
+    grid_position = grid_position.permute(0, 1, 4, 2, 3).clamp(0, 1)  # B N C H W
+    voxel_indices = grid_position * (voxel_resolution - 1)
+    voxel_indices = torch.round(voxel_indices).long()
+    return voxel_indices
+
+
+def calc_multires_voxel_idxs(position_maps, grid_resolutions=[64, 32, 16, 8], voxel_resolutions=[512, 256, 128, 64]):
+
+    """Generates multi-resolution voxel indices for position encoding.
+    
+    Creates pyramid of quantized position representations.
+    
+    Args:
+        position_maps: Input position maps
+        grid_resolutions: Spatial resolution levels
+        voxel_resolutions: Quantization levels
+        
+    Returns:
+        dict: Voxel indices keyed by flattened dimension size, with resolution metadata
+    """
+
+    voxel_indices = {}
+    with torch.no_grad():
+        for grid_resolution, voxel_resolution in zip(grid_resolutions, voxel_resolutions):
+            voxel_indice = compute_discrete_voxel_indice(position_maps, grid_resolution, voxel_resolution)
+            voxel_indice = rearrange(voxel_indice, "b n c h w -> b (n h w) c")
+            voxel_indices[voxel_indice.shape[1]] = {"voxel_indices": voxel_indice, "voxel_resolution": voxel_resolution}
+    return voxel_indices
+
+
+class Basic2p5DTransformerBlock(torch.nn.Module):
+
+
+    """Enhanced transformer block for multiview 2.5D image generation.
+    
+    Extends standard transformer blocks with:
+    - Material-specific attention (MDA)
+    - Multiview attention (MA)
+    - Reference attention (RA)
+    - DINO feature integration
+    
+    Args:
+        transformer: Base transformer block
+        layer_name: Identifier for layer
+        use_ma: Enable multiview attention
+        use_ra: Enable reference attention
+        use_mda: Enable material-aware attention
+        use_dino: Enable DINO feature integration
+        pbr_setting: List of PBR materials
+    """
+
+    def __init__(
+        self,
+        transformer: BasicTransformerBlock,
+        layer_name,
+        use_ma=True,
+        use_ra=True,
+        use_mda=True,
+        use_dino=True,
+        pbr_setting=None,
+    ) -> None:
+        
+        """
+        Initialization:
+        1. Material-Dimension Attention (MDA):
+           - Processes each PBR material with separate projection weights
+           - Uses custom SelfAttnProcessor2_0 with material awareness
+           
+        2. Multiview Attention (MA):
+           - Adds cross-view attention with PoseRoPE
+           - Initialized as zero-initialized residual pathway
+           
+        3. Reference Attention (RA):
+           - Conditions on reference view features
+           - Uses RefAttnProcessor2_0 for material-specific conditioning
+           
+        4. DINO Attention:
+           - Incorporates DINO-ViT features
+           - Initialized as zero-initialized residual pathway
+        """
+
+        super().__init__()
+        self.transformer = transformer
+        self.layer_name = layer_name
+        self.use_ma = use_ma
+        self.use_ra = use_ra
+        self.use_mda = use_mda
+        self.use_dino = use_dino
+        self.pbr_setting = pbr_setting
+
+        if self.use_mda:
+            self.attn1.set_processor(
+                SelfAttnProcessor2_0(
+                    query_dim=self.dim,
+                    heads=self.num_attention_heads,
+                    dim_head=self.attention_head_dim,
+                    dropout=self.dropout,
+                    bias=self.attention_bias,
+                    cross_attention_dim=None,
+                    upcast_attention=self.attn1.upcast_attention,
+                    out_bias=True,
+                    pbr_setting=self.pbr_setting,
+                )
+            )
+
+        # multiview attn
+        if self.use_ma:
+            self.attn_multiview = Attention(
+                query_dim=self.dim,
+                heads=self.num_attention_heads,
+                dim_head=self.attention_head_dim,
+                dropout=self.dropout,
+                bias=self.attention_bias,
+                cross_attention_dim=None,
+                upcast_attention=self.attn1.upcast_attention,
+                out_bias=True,
+                processor=PoseRoPEAttnProcessor2_0(),
+            )
+
+        # ref attn
+        if self.use_ra:
+            self.attn_refview = Attention(
+                query_dim=self.dim,
+                heads=self.num_attention_heads,
+                dim_head=self.attention_head_dim,
+                dropout=self.dropout,
+                bias=self.attention_bias,
+                cross_attention_dim=None,
+                upcast_attention=self.attn1.upcast_attention,
+                out_bias=True,
+                processor=RefAttnProcessor2_0(
+                    query_dim=self.dim,
+                    heads=self.num_attention_heads,
+                    dim_head=self.attention_head_dim,
+                    dropout=self.dropout,
+                    bias=self.attention_bias,
+                    cross_attention_dim=None,
+                    upcast_attention=self.attn1.upcast_attention,
+                    out_bias=True,
+                    pbr_setting=self.pbr_setting,
+                ),
+            )
+
+        # dino attn
+        if self.use_dino:
+            self.attn_dino = Attention(
+                query_dim=self.dim,
+                heads=self.num_attention_heads,
+                dim_head=self.attention_head_dim,
+                dropout=self.dropout,
+                bias=self.attention_bias,
+                cross_attention_dim=self.cross_attention_dim,
+                upcast_attention=self.attn2.upcast_attention,
+                out_bias=True,
+            )
+
+        self._initialize_attn_weights()
+
+    def _initialize_attn_weights(self):
+
+        """Initializes specialized attention heads with base weights.
+        
+        Uses weight sharing strategy:
+        - Copies base transformer weights to specialized heads
+        - Initializes newly-added parameters to zero
+        """
+
+        if self.use_mda:
+            for token in self.pbr_setting:
+                if token == "albedo":
+                    continue
+                getattr(self.attn1.processor, f"to_q_{token}").load_state_dict(self.attn1.to_q.state_dict())
+                getattr(self.attn1.processor, f"to_k_{token}").load_state_dict(self.attn1.to_k.state_dict())
+                getattr(self.attn1.processor, f"to_v_{token}").load_state_dict(self.attn1.to_v.state_dict())
+                getattr(self.attn1.processor, f"to_out_{token}").load_state_dict(self.attn1.to_out.state_dict())
+
+        if self.use_ma:
+            self.attn_multiview.load_state_dict(self.attn1.state_dict(), strict=False)
+            with torch.no_grad():
+                for layer in self.attn_multiview.to_out:
+                    for param in layer.parameters():
+                        param.zero_()
+
+        if self.use_ra:
+            self.attn_refview.load_state_dict(self.attn1.state_dict(), strict=False)
+            for token in self.pbr_setting:
+                if token == "albedo":
+                    continue
+                getattr(self.attn_refview.processor, f"to_v_{token}").load_state_dict(
+                    self.attn_refview.to_q.state_dict()
+                )
+                getattr(self.attn_refview.processor, f"to_out_{token}").load_state_dict(
+                    self.attn_refview.to_out.state_dict()
+                )
+            with torch.no_grad():
+                for layer in self.attn_refview.to_out:
+                    for param in layer.parameters():
+                        param.zero_()
+                for token in self.pbr_setting:
+                    if token == "albedo":
+                        continue
+                    for layer in getattr(self.attn_refview.processor, f"to_out_{token}"):
+                        for param in layer.parameters():
+                            param.zero_()
+
+        if self.use_dino:
+            self.attn_dino.load_state_dict(self.attn2.state_dict(), strict=False)
+            with torch.no_grad():
+                for layer in self.attn_dino.to_out:
+                    for param in layer.parameters():
+                        param.zero_()
+
+        if self.use_dino:
+            self.attn_dino.load_state_dict(self.attn2.state_dict(), strict=False)
+            with torch.no_grad():
+                for layer in self.attn_dino.to_out:
+                    for param in layer.parameters():
+                        param.zero_()
+
+    def __getattr__(self, name: str):
+        try:
+            return super().__getattr__(name)
+        except AttributeError:
+            return getattr(self.transformer, name)
+
+    def forward(
+        self,
+        hidden_states: torch.Tensor,
+        attention_mask: Optional[torch.Tensor] = None,
+        encoder_hidden_states: Optional[torch.Tensor] = None,
+        encoder_attention_mask: Optional[torch.Tensor] = None,
+        timestep: Optional[torch.LongTensor] = None,
+        cross_attention_kwargs: Dict[str, Any] = None,
+        class_labels: Optional[torch.LongTensor] = None,
+        added_cond_kwargs: Optional[Dict[str, torch.Tensor]] = None,
+    ) -> torch.Tensor:
+
+        """Forward pass with multi-mechanism attention.
+        
+        Processing stages:
+        1. Material-aware self-attention (MDA)
+        2. Reference attention (RA)
+        3. Multiview attention (MA) with position-aware attention
+        4. Text conditioning (base attention)
+        5. DINO feature conditioning (optional)
+        6. Position-aware conditioning
+        7. Feed-forward network
+        
+        Args:
+            hidden_states: Input features [B * N_materials * N_views, Seq_len, Feat_dim]
+            See base transformer for other parameters
+            
+        Returns:
+            torch.Tensor: Output features
+        """
+        # [Full multi-mechanism processing pipeline...]
+        # Key processing stages:
+        # 1. Material-aware self-attention (handles albedo/mr separation)
+        # 2. Reference attention (conditioned on reference features)
+        # 3. View-to-view attention with geometric constraints
+        # 4. Text-to-image cross-attention
+        # 5. DINO feature fusion (when enabled)
+        # 6. Positional conditioning (RoPE-style)
+        # 7. Feed-forward network with conditional normalization
+
+        # Notice that normalization is always applied before the real computation in the following blocks.
+        # 0. Self-Attention
+        batch_size = hidden_states.shape[0]
+
+        cross_attention_kwargs = cross_attention_kwargs.copy() if cross_attention_kwargs is not None else {}
+        num_in_batch = cross_attention_kwargs.pop("num_in_batch", 1)
+        mode = cross_attention_kwargs.pop("mode", None)
+        mva_scale = cross_attention_kwargs.pop("mva_scale", 1.0)
+        ref_scale = cross_attention_kwargs.pop("ref_scale", 1.0)
+        condition_embed_dict = cross_attention_kwargs.pop("condition_embed_dict", None)
+        dino_hidden_states = cross_attention_kwargs.pop("dino_hidden_states", None)
+        position_voxel_indices = cross_attention_kwargs.pop("position_voxel_indices", None)
+        N_pbr = len(self.pbr_setting) if self.pbr_setting is not None else 1
+
+        if self.norm_type == "ada_norm":
+            norm_hidden_states = self.norm1(hidden_states, timestep)
+        elif self.norm_type == "ada_norm_zero":
+            norm_hidden_states, gate_msa, shift_mlp, scale_mlp, gate_mlp = self.norm1(
+                hidden_states, timestep, class_labels, hidden_dtype=hidden_states.dtype
+            )
+        elif self.norm_type in ["layer_norm", "layer_norm_i2vgen"]:
+            norm_hidden_states = self.norm1(hidden_states)
+        elif self.norm_type == "ada_norm_continuous":
+            norm_hidden_states = self.norm1(hidden_states, added_cond_kwargs["pooled_text_emb"])
+        elif self.norm_type == "ada_norm_single":
+            shift_msa, scale_msa, gate_msa, shift_mlp, scale_mlp, gate_mlp = (
+                self.scale_shift_table[None] + timestep.reshape(batch_size, 6, -1)
+            ).chunk(6, dim=1)
+            norm_hidden_states = self.norm1(hidden_states)
+            norm_hidden_states = norm_hidden_states * (1 + scale_msa) + shift_msa
+        else:
+            raise ValueError("Incorrect norm used")
+
+        if self.pos_embed is not None:
+            norm_hidden_states = self.pos_embed(norm_hidden_states)
+
+        # 1. Prepare GLIGEN inputs
+        cross_attention_kwargs = cross_attention_kwargs.copy() if cross_attention_kwargs is not None else {}
+        gligen_kwargs = cross_attention_kwargs.pop("gligen", None)
+
+        if self.use_mda:
+            mda_norm_hidden_states = rearrange(
+                norm_hidden_states, "(b n_pbr n) l c -> b n_pbr n l c", n=num_in_batch, n_pbr=N_pbr
+            )
+            attn_output = self.attn1(
+                mda_norm_hidden_states,
+                encoder_hidden_states=encoder_hidden_states if self.only_cross_attention else None,
+                attention_mask=attention_mask,
+                **cross_attention_kwargs,
+            )
+            attn_output = rearrange(attn_output, "b n_pbr n l c -> (b n_pbr n) l c")
+        else:
+            attn_output = self.attn1(
+                norm_hidden_states,
+                encoder_hidden_states=encoder_hidden_states if self.only_cross_attention else None,
+                attention_mask=attention_mask,
+                **cross_attention_kwargs,
+            )
+
+        if self.norm_type == "ada_norm_zero":
+            attn_output = gate_msa.unsqueeze(1) * attn_output
+        elif self.norm_type == "ada_norm_single":
+            attn_output = gate_msa * attn_output
+
+        hidden_states = attn_output + hidden_states
+        if hidden_states.ndim == 4:
+            hidden_states = hidden_states.squeeze(1)
+
+        # 1.2 Reference Attention
+        if "w" in mode:
+            condition_embed_dict[self.layer_name] = rearrange(
+                norm_hidden_states, "(b n) l c -> b (n l) c", n=num_in_batch
+            )  # B, (N L), C
+
+        if "r" in mode and self.use_ra:
+            condition_embed = condition_embed_dict[self.layer_name]
+
+            #! Only using albedo features for reference attention
+            ref_norm_hidden_states = rearrange(
+                norm_hidden_states, "(b n_pbr n) l c -> b n_pbr (n l) c", n=num_in_batch, n_pbr=N_pbr
+            )[:, 0, ...]
+
+            attn_output = self.attn_refview(
+                ref_norm_hidden_states,
+                encoder_hidden_states=condition_embed,
+                attention_mask=None,
+                **cross_attention_kwargs,
+            )  # b (n l) c
+            attn_output = rearrange(attn_output, "b n_pbr (n l) c -> (b n_pbr n) l c", n=num_in_batch, n_pbr=N_pbr)
+
+            ref_scale_timing = ref_scale
+            if isinstance(ref_scale, torch.Tensor):
+                ref_scale_timing = ref_scale.unsqueeze(1).repeat(1, num_in_batch * N_pbr).view(-1)
+                for _ in range(attn_output.ndim - 1):
+                    ref_scale_timing = ref_scale_timing.unsqueeze(-1)
+            hidden_states = ref_scale_timing * attn_output + hidden_states
+            if hidden_states.ndim == 4:
+                hidden_states = hidden_states.squeeze(1)
+
+        # 1.3 Multiview Attention
+        if num_in_batch > 1 and self.use_ma:
+            multivew_hidden_states = rearrange(
+                norm_hidden_states, "(b n_pbr n) l c -> (b n_pbr) (n l) c", n_pbr=N_pbr, n=num_in_batch
+            )
+            position_indices = None
+            if position_voxel_indices is not None:
+                if multivew_hidden_states.shape[1] in position_voxel_indices:
+                    position_indices = position_voxel_indices[multivew_hidden_states.shape[1]]
+
+            attn_output = self.attn_multiview(
+                multivew_hidden_states,
+                encoder_hidden_states=multivew_hidden_states,
+                position_indices=position_indices,
+                n_pbrs=N_pbr,
+                **cross_attention_kwargs,
+            )
+
+            attn_output = rearrange(attn_output, "(b n_pbr) (n l) c -> (b n_pbr n) l c", n_pbr=N_pbr, n=num_in_batch)
+
+            hidden_states = mva_scale * attn_output + hidden_states
+            if hidden_states.ndim == 4:
+                hidden_states = hidden_states.squeeze(1)
+
+        # 1.2 GLIGEN Control
+        if gligen_kwargs is not None:
+            hidden_states = self.fuser(hidden_states, gligen_kwargs["objs"])
+
+        # 3. Cross-Attention
+        if self.attn2 is not None:
+            if self.norm_type == "ada_norm":
+                norm_hidden_states = self.norm2(hidden_states, timestep)
+            elif self.norm_type in ["ada_norm_zero", "layer_norm", "layer_norm_i2vgen"]:
+                norm_hidden_states = self.norm2(hidden_states)
+            elif self.norm_type == "ada_norm_single":
+                # For PixArt norm2 isn't applied here:
+                # https://github.com/PixArt-alpha/PixArt-alpha/blob/0f55e922376d8b797edd44d25d0e7464b260dcab/diffusion/model/nets/PixArtMS.py#L70C1-L76C103
+                norm_hidden_states = hidden_states
+            elif self.norm_type == "ada_norm_continuous":
+                norm_hidden_states = self.norm2(hidden_states, added_cond_kwargs["pooled_text_emb"])
+            else:
+                raise ValueError("Incorrect norm")
+
+            if self.pos_embed is not None and self.norm_type != "ada_norm_single":
+                norm_hidden_states = self.pos_embed(norm_hidden_states)
+
+            attn_output = self.attn2(
+                norm_hidden_states,
+                encoder_hidden_states=encoder_hidden_states,
+                attention_mask=encoder_attention_mask,
+                **cross_attention_kwargs,
+            )
+            hidden_states = attn_output + hidden_states
+
+            # dino attn
+            if self.use_dino:
+                dino_hidden_states = dino_hidden_states.unsqueeze(1).repeat(1, N_pbr * num_in_batch, 1, 1)
+                dino_hidden_states = rearrange(dino_hidden_states, "b n l c -> (b n) l c")
+                attn_output = self.attn_dino(
+                    norm_hidden_states,
+                    encoder_hidden_states=dino_hidden_states,
+                    attention_mask=None,
+                    **cross_attention_kwargs,
+                )
+
+                hidden_states = attn_output + hidden_states
+
+        # 4. Feed-forward
+        # i2vgen doesn't have this norm 🤷‍♂️
+        if self.norm_type == "ada_norm_continuous":
+            norm_hidden_states = self.norm3(hidden_states, added_cond_kwargs["pooled_text_emb"])
+        elif not self.norm_type == "ada_norm_single":
+            norm_hidden_states = self.norm3(hidden_states)
+
+        if self.norm_type == "ada_norm_zero":
+            norm_hidden_states = norm_hidden_states * (1 + scale_mlp[:, None]) + shift_mlp[:, None]
+
+        if self.norm_type == "ada_norm_single":
+            norm_hidden_states = self.norm2(hidden_states)
+            norm_hidden_states = norm_hidden_states * (1 + scale_mlp) + shift_mlp
+
+        if self._chunk_size is not None:
+            # "feed_forward_chunk_size" can be used to save memory
+            ff_output = _chunked_feed_forward(self.ff, norm_hidden_states, self._chunk_dim, self._chunk_size)
+        else:
+            ff_output = self.ff(norm_hidden_states)
+
+        if self.norm_type == "ada_norm_zero":
+            ff_output = gate_mlp.unsqueeze(1) * ff_output
+        elif self.norm_type == "ada_norm_single":
+            ff_output = gate_mlp * ff_output
+
+        hidden_states = ff_output + hidden_states
+        if hidden_states.ndim == 4:
+            hidden_states = hidden_states.squeeze(1)
+
+        return hidden_states
+
+
+class ImageProjModel(torch.nn.Module):
+
+    """Projects image embeddings into cross-attention space.
+    
+    Transforms CLIP embeddings into additional context tokens for conditioning.
+    
+    Args:
+        cross_attention_dim: Dimension of attention space
+        clip_embeddings_dim: Dimension of input CLIP embeddings
+        clip_extra_context_tokens: Number of context tokens to generate
+    """
+
+    def __init__(self, cross_attention_dim=1024, clip_embeddings_dim=1024, clip_extra_context_tokens=4):
+        super().__init__()
+
+        self.generator = None
+        self.cross_attention_dim = cross_attention_dim
+        self.clip_extra_context_tokens = clip_extra_context_tokens
+        self.proj = torch.nn.Linear(clip_embeddings_dim, self.clip_extra_context_tokens * cross_attention_dim)
+        self.norm = torch.nn.LayerNorm(cross_attention_dim)
+
+    def forward(self, image_embeds):
+
+        """Projects image embeddings to cross-attention context tokens.
+        
+        Args:
+            image_embeds: Input embeddings [B, N, C] or [B, C]
+            
+        Returns:
+            torch.Tensor: Context tokens [B, N*clip_extra_context_tokens, cross_attention_dim]
+        """
+
+        embeds = image_embeds
+        num_token = 1
+        if embeds.dim() == 3:
+            num_token = embeds.shape[1]
+            embeds = rearrange(embeds, "b n c -> (b n) c")
+
+        clip_extra_context_tokens = self.proj(embeds).reshape(
+            -1, self.clip_extra_context_tokens, self.cross_attention_dim
+        )
+        clip_extra_context_tokens = self.norm(clip_extra_context_tokens)
+
+        clip_extra_context_tokens = rearrange(clip_extra_context_tokens, "(b nt) n c -> b (nt n) c", nt=num_token)
+
+        return clip_extra_context_tokens
+
+
+class UNet2p5DConditionModel(torch.nn.Module):
+
+    """2.5D UNet extension for multiview PBR generation.
+    
+    Enhances standard 2D UNet with:
+    - Multiview attention mechanisms
+    - Material-aware processing
+    - Position-aware conditioning
+    - Dual-stream reference processing
+    
+    Args:
+        unet: Base 2D UNet model
+        train_sched: Training scheduler (DDPM)
+        val_sched: Validation scheduler (EulerAncestral)
+    """
+
+    def __init__(
+        self,
+        unet: UNet2DConditionModel,
+        train_sched: DDPMScheduler = None,
+        val_sched: EulerAncestralDiscreteScheduler = None,
+    ) -> None:
+        super().__init__()
+        self.unet = unet
+        self.train_sched = train_sched
+        self.val_sched = val_sched
+
+        self.use_ma = True
+        self.use_ra = True
+        self.use_mda = True
+        self.use_dino = True
+        self.use_position_rope = True
+        self.use_learned_text_clip = True
+        self.use_dual_stream = True
+        self.pbr_setting = ["albedo", "mr"]
+        self.pbr_token_channels = 77
+
+        if self.use_dual_stream and self.use_ra:
+            self.unet_dual = copy.deepcopy(unet)
+            self.init_attention(self.unet_dual)
+
+        self.init_attention(
+            self.unet,
+            use_ma=self.use_ma,
+            use_ra=self.use_ra,
+            use_dino=self.use_dino,
+            use_mda=self.use_mda,
+            pbr_setting=self.pbr_setting,
+        )
+        self.init_condition(use_dino=self.use_dino)
+
+    @staticmethod
+    def from_pretrained(pretrained_model_name_or_path, **kwargs):
+        torch_dtype = kwargs.pop("torch_dtype", torch.float32)
+        config_path = os.path.join(pretrained_model_name_or_path, "config.json")
+        unet_ckpt_path = os.path.join(pretrained_model_name_or_path, "diffusion_pytorch_model.bin")
+        with open(config_path, "r", encoding="utf-8") as file:
+            config = json.load(file)
+        unet = UNet2DConditionModel(**config)
+        unet_2p5d = UNet2p5DConditionModel(unet)
+        unet_2p5d.unet.conv_in = torch.nn.Conv2d(
+            12,
+            unet.conv_in.out_channels,
+            kernel_size=unet.conv_in.kernel_size,
+            stride=unet.conv_in.stride,
+            padding=unet.conv_in.padding,
+            dilation=unet.conv_in.dilation,
+            groups=unet.conv_in.groups,
+            bias=unet.conv_in.bias is not None,
+        )
+        unet_ckpt = torch.load(unet_ckpt_path, map_location="cpu", weights_only=True)
+        unet_2p5d.load_state_dict(unet_ckpt, strict=True)
+        unet_2p5d = unet_2p5d.to(torch_dtype)
+        return unet_2p5d
+
+    def init_condition(self, use_dino):
+
+        """Initializes conditioning mechanisms for multiview PBR generation.
+        
+        Sets up:
+        1. Learned text embeddings: Material-specific tokens (albedo, mr) initialized to zeros
+        2. DINO projector: Model to process DINO-ViT features for cross-attention
+        
+        Args:
+            use_dino: Flag to enable DINO feature integration
+        """
+
+        if self.use_learned_text_clip:
+            for token in self.pbr_setting:
+                self.unet.register_parameter(
+                    f"learned_text_clip_{token}", nn.Parameter(torch.zeros(self.pbr_token_channels, 1024))
+                )
+            self.unet.learned_text_clip_ref = nn.Parameter(torch.zeros(self.pbr_token_channels, 1024))
+
+        if use_dino:
+            self.unet.image_proj_model_dino = ImageProjModel(
+                cross_attention_dim=self.unet.config.cross_attention_dim,
+                clip_embeddings_dim=1536,
+                clip_extra_context_tokens=4,
+            )
+
+    def init_attention(self, unet, use_ma=False, use_ra=False, use_mda=False, use_dino=False, pbr_setting=None):
+
+        """Recursively replaces standard transformers with enhanced 2.5D blocks.
+        
+        Processes UNet architecture:
+        1. Downsampling blocks: Replaces transformers in attention layers
+        2. Middle block: Upgrades central transformers
+        3. Upsampling blocks: Modifies decoder transformers
+        
+        Args:
+            unet: UNet model to enhance
+            use_ma: Enable multiview attention
+            use_ra: Enable reference attention
+            use_mda: Enable material-specific attention
+            use_dino: Enable DINO feature integration
+            pbr_setting: List of PBR materials
+        """
+
+        for down_block_i, down_block in enumerate(unet.down_blocks):
+            if hasattr(down_block, "has_cross_attention") and down_block.has_cross_attention:
+                for attn_i, attn in enumerate(down_block.attentions):
+                    for transformer_i, transformer in enumerate(attn.transformer_blocks):
+                        if isinstance(transformer, BasicTransformerBlock):
+                            attn.transformer_blocks[transformer_i] = Basic2p5DTransformerBlock(
+                                transformer,
+                                f"down_{down_block_i}_{attn_i}_{transformer_i}",
+                                use_ma,
+                                use_ra,
+                                use_mda,
+                                use_dino,
+                                pbr_setting,
+                            )
+
+        if hasattr(unet.mid_block, "has_cross_attention") and unet.mid_block.has_cross_attention:
+            for attn_i, attn in enumerate(unet.mid_block.attentions):
+                for transformer_i, transformer in enumerate(attn.transformer_blocks):
+                    if isinstance(transformer, BasicTransformerBlock):
+                        attn.transformer_blocks[transformer_i] = Basic2p5DTransformerBlock(
+                            transformer, f"mid_{attn_i}_{transformer_i}", use_ma, use_ra, use_mda, use_dino, pbr_setting
+                        )
+
+        for up_block_i, up_block in enumerate(unet.up_blocks):
+            if hasattr(up_block, "has_cross_attention") and up_block.has_cross_attention:
+                for attn_i, attn in enumerate(up_block.attentions):
+                    for transformer_i, transformer in enumerate(attn.transformer_blocks):
+                        if isinstance(transformer, BasicTransformerBlock):
+                            attn.transformer_blocks[transformer_i] = Basic2p5DTransformerBlock(
+                                transformer,
+                                f"up_{up_block_i}_{attn_i}_{transformer_i}",
+                                use_ma,
+                                use_ra,
+                                use_mda,
+                                use_dino,
+                                pbr_setting,
+                            )
+
+    def __getattr__(self, name: str):
+        try:
+            return super().__getattr__(name)
+        except AttributeError:
+            return getattr(self.unet, name)
+
+    def forward(
+        self,
+        sample,
+        timestep,
+        encoder_hidden_states,
+        *args,
+        added_cond_kwargs=None,
+        cross_attention_kwargs=None,
+        down_intrablock_additional_residuals=None,
+        down_block_res_samples=None,
+        mid_block_res_sample=None,
+        **cached_condition,
+    ):
+
+        """Forward pass with multiview/material conditioning.
+        
+        Key stages:
+        1. Input preparation (concat normal/position maps)
+        2. Reference feature extraction (dual-stream)
+        3. Position encoding (voxel indices)
+        4. DINO feature projection
+        5. Main UNet processing with attention conditioning
+        
+        Args:
+            sample: Input latents [B, N_pbr, N_gen, C, H, W]
+            cached_condition: Dictionary containing:
+                - embeds_normal: Normal map embeddings
+                - embeds_position: Position map embeddings
+                - ref_latents: Reference image latents
+                - dino_hidden_states: DINO features
+                - position_maps: 3D position maps
+                - mva_scale: Multiview attention scale
+                - ref_scale: Reference attention scale
+                
+        Returns:
+            torch.Tensor: Output features
+        """
+
+        B, N_pbr, N_gen, _, H, W = sample.shape
+        assert H == W
+
+        if "cache" not in cached_condition:
+            cached_condition["cache"] = {}
+
+        sample = [sample]
+        if "embeds_normal" in cached_condition:
+            sample.append(cached_condition["embeds_normal"].unsqueeze(1).repeat(1, N_pbr, 1, 1, 1, 1))
+        if "embeds_position" in cached_condition:
+            sample.append(cached_condition["embeds_position"].unsqueeze(1).repeat(1, N_pbr, 1, 1, 1, 1))
+        sample = torch.cat(sample, dim=-3)
+
+        sample = rearrange(sample, "b n_pbr n c h w -> (b n_pbr n) c h w")
+
+        encoder_hidden_states_gen = encoder_hidden_states.unsqueeze(-3).repeat(1, 1, N_gen, 1, 1)
+        encoder_hidden_states_gen = rearrange(encoder_hidden_states_gen, "b n_pbr n l c -> (b n_pbr n) l c")
+
+        if added_cond_kwargs is not None:
+            text_embeds_gen = added_cond_kwargs["text_embeds"].unsqueeze(1).repeat(1, N_gen, 1)
+            text_embeds_gen = rearrange(text_embeds_gen, "b n c -> (b n) c")
+            time_ids_gen = added_cond_kwargs["time_ids"].unsqueeze(1).repeat(1, N_gen, 1)
+            time_ids_gen = rearrange(time_ids_gen, "b n c -> (b n) c")
+            added_cond_kwargs_gen = {"text_embeds": text_embeds_gen, "time_ids": time_ids_gen}
+        else:
+            added_cond_kwargs_gen = None
+
+        if self.use_position_rope:
+            if "position_voxel_indices" in cached_condition["cache"]:
+                position_voxel_indices = cached_condition["cache"]["position_voxel_indices"]
+            else:
+                if "position_maps" in cached_condition:
+                    position_voxel_indices = calc_multires_voxel_idxs(
+                        cached_condition["position_maps"],
+                        grid_resolutions=[H, H // 2, H // 4, H // 8],
+                        voxel_resolutions=[H * 8, H * 4, H * 2, H],
+                    )
+                    cached_condition["cache"]["position_voxel_indices"] = position_voxel_indices
+        else:
+            position_voxel_indices = None
+
+        if self.use_dino:
+            if "dino_hidden_states_proj" in cached_condition["cache"]:
+                dino_hidden_states = cached_condition["cache"]["dino_hidden_states_proj"]
+            else:
+                assert "dino_hidden_states" in cached_condition
+                dino_hidden_states = cached_condition["dino_hidden_states"]
+                dino_hidden_states = self.image_proj_model_dino(dino_hidden_states)
+                cached_condition["cache"]["dino_hidden_states_proj"] = dino_hidden_states
+        else:
+            dino_hidden_states = None
+
+        if self.use_ra:
+            if "condition_embed_dict" in cached_condition["cache"]:
+                condition_embed_dict = cached_condition["cache"]["condition_embed_dict"]
+            else:
+                condition_embed_dict = {}
+                ref_latents = cached_condition["ref_latents"]
+                N_ref = ref_latents.shape[1]
+
+                if not self.use_dual_stream:
+                    ref_latents = [ref_latents]
+                    if "embeds_normal" in cached_condition:
+                        ref_latents.append(torch.zeros_like(ref_latents[0]))
+                    if "embeds_position" in cached_condition:
+                        ref_latents.append(torch.zeros_like(ref_latents[0]))
+                    ref_latents = torch.cat(ref_latents, dim=2)
+
+                ref_latents = rearrange(ref_latents, "b n c h w -> (b n) c h w")
+
+                encoder_hidden_states_ref = self.unet.learned_text_clip_ref.repeat(B, N_ref, 1, 1)
+
+                encoder_hidden_states_ref = rearrange(encoder_hidden_states_ref, "b n l c -> (b n) l c")
+
+                if added_cond_kwargs is not None:
+                    text_embeds_ref = added_cond_kwargs["text_embeds"].unsqueeze(1).repeat(1, N_ref, 1)
+                    text_embeds_ref = rearrange(text_embeds_ref, "b n c -> (b n) c")
+                    time_ids_ref = added_cond_kwargs["time_ids"].unsqueeze(1).repeat(1, N_ref, 1)
+                    time_ids_ref = rearrange(time_ids_ref, "b n c -> (b n) c")
+                    added_cond_kwargs_ref = {
+                        "text_embeds": text_embeds_ref,
+                        "time_ids": time_ids_ref,
+                    }
+                else:
+                    added_cond_kwargs_ref = None
+
+                noisy_ref_latents = ref_latents
+                timestep_ref = 0
+                if self.use_dual_stream:
+                    unet_ref = self.unet_dual
+                else:
+                    unet_ref = self.unet
+                unet_ref(
+                    noisy_ref_latents,
+                    timestep_ref,
+                    encoder_hidden_states=encoder_hidden_states_ref,
+                    class_labels=None,
+                    added_cond_kwargs=added_cond_kwargs_ref,
+                    # **kwargs
+                    return_dict=False,
+                    cross_attention_kwargs={
+                        "mode": "w",
+                        "num_in_batch": N_ref,
+                        "condition_embed_dict": condition_embed_dict,
+                    },
+                )
+                cached_condition["cache"]["condition_embed_dict"] = condition_embed_dict
+        else:
+            condition_embed_dict = None
+
+        mva_scale = cached_condition.get("mva_scale", 1.0)
+        ref_scale = cached_condition.get("ref_scale", 1.0)
+
+        return self.unet(
+            sample,
+            timestep,
+            encoder_hidden_states_gen,
+            *args,
+            class_labels=None,
+            added_cond_kwargs=added_cond_kwargs_gen,
+            down_intrablock_additional_residuals=(
+                [sample.to(dtype=self.unet.dtype) for sample in down_intrablock_additional_residuals]
+                if down_intrablock_additional_residuals is not None
+                else None
+            ),
+            down_block_additional_residuals=(
+                [sample.to(dtype=self.unet.dtype) for sample in down_block_res_samples]
+                if down_block_res_samples is not None
+                else None
+            ),
+            mid_block_additional_residual=(
+                mid_block_res_sample.to(dtype=self.unet.dtype) if mid_block_res_sample is not None else None
+            ),
+            return_dict=False,
+            cross_attention_kwargs={
+                "mode": "r",
+                "num_in_batch": N_gen,
+                "dino_hidden_states": dino_hidden_states,
+                "condition_embed_dict": condition_embed_dict,
+                "mva_scale": mva_scale,
+                "ref_scale": ref_scale,
+                "position_voxel_indices": position_voxel_indices,
+            },
+        )

hunyuan3d-paintpbr-v2-1/vae/config.json

@@ -0,0 +1,29 @@
+{
+  "_class_name": "AutoencoderKL",
+  "_diffusers_version": "0.10.0.dev0",
+  "act_fn": "silu",
+  "block_out_channels": [
+    128,
+    256,
+    512,
+    512
+  ],
+  "down_block_types": [
+    "DownEncoderBlock2D",
+    "DownEncoderBlock2D",
+    "DownEncoderBlock2D",
+    "DownEncoderBlock2D"
+  ],
+  "in_channels": 3,
+  "latent_channels": 4,
+  "layers_per_block": 2,
+  "norm_num_groups": 32,
+  "out_channels": 3,
+  "sample_size": 768,
+  "up_block_types": [
+    "UpDecoderBlock2D",
+    "UpDecoderBlock2D",
+    "UpDecoderBlock2D",
+    "UpDecoderBlock2D"
+  ]
+}

hunyuan3d-paintpbr-v2-1/vae/diffusion_pytorch_model.bin

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

hunyuan3d-vae-v2-1/config.yaml

@@ -0,0 +1,19 @@
+target: hy3dshape.models.ShapeVAE
+params:
+  num_latents: 4096
+  embed_dim: 64
+  num_freqs: 8
+  include_pi: false
+  heads: 16
+  width: 1024
+  num_encoder_layers: 8
+  num_decoder_layers: 16
+  qkv_bias: false
+  qk_norm: true
+  scale_factor: 1.0039506158752403
+  geo_decoder_mlp_expand_ratio: 4
+  geo_decoder_downsample_ratio: 1
+  geo_decoder_ln_post: true
+  point_feats: 4
+  pc_size: 81920
+  pc_sharpedge_size: 0

hunyuan3d-vae-v2-1/model.fp16.ckpt

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

hy3dpaint/textureGenPipeline.py

@@ -0,0 +1,192 @@
+# Hunyuan 3D is licensed under the TENCENT HUNYUAN NON-COMMERCIAL LICENSE AGREEMENT
+# except for the third-party components listed below.
+# Hunyuan 3D does not impose any additional limitations beyond what is outlined
+# in the repsective licenses of these third-party components.
+# Users must comply with all terms and conditions of original licenses of these third-party
+# components and must ensure that the usage of the third party components adheres to
+# all relevant laws and regulations.
+
+# For avoidance of doubts, Hunyuan 3D means the large language models and
+# their software and algorithms, including trained model weights, parameters (including
+# optimizer states), machine-learning model code, inference-enabling code, training-enabling code,
+# fine-tuning enabling code and other elements of the foregoing made publicly available
+# by Tencent in accordance with TENCENT HUNYUAN COMMUNITY LICENSE AGREEMENT.
+
+import os
+import torch
+import copy
+import trimesh
+import numpy as np
+from PIL import Image
+from typing import List
+from DifferentiableRenderer.MeshRender import MeshRender
+from utils.simplify_mesh_utils import remesh_mesh
+from utils.multiview_utils import multiviewDiffusionNet
+from utils.pipeline_utils import ViewProcessor
+from utils.image_super_utils import imageSuperNet
+from utils.uvwrap_utils import mesh_uv_wrap
+from DifferentiableRenderer.mesh_utils import convert_obj_to_glb
+import warnings
+
+warnings.filterwarnings("ignore")
+from diffusers.utils import logging as diffusers_logging
+
+diffusers_logging.set_verbosity(50)
+
+
+class Hunyuan3DPaintConfig:
+    def __init__(self, max_num_view, resolution):
+        self.device = "cuda"
+
+        self.multiview_cfg_path = "cfgs/hunyuan-paint-pbr.yaml"
+        self.custom_pipeline = "hunyuanpaintpbr"
+        self.multiview_pretrained_path = "tencent/Hunyuan3D-2.1"
+        self.dino_ckpt_path = "facebook/dinov2-giant"
+        self.realesrgan_ckpt_path = "ckpt/RealESRGAN_x4plus.pth"
+
+        self.raster_mode = "cr"
+        self.bake_mode = "back_sample"
+        self.render_size = 1024 * 2
+        self.texture_size = 1024 * 4
+        self.max_selected_view_num = max_num_view
+        self.resolution = resolution
+        self.bake_exp = 4
+        self.merge_method = "fast"
+
+        # view selection
+        self.candidate_camera_azims = [0, 90, 180, 270, 0, 180]
+        self.candidate_camera_elevs = [0, 0, 0, 0, 90, -90]
+        self.candidate_view_weights = [1, 0.1, 0.5, 0.1, 0.05, 0.05]
+
+        for azim in range(0, 360, 30):
+            self.candidate_camera_azims.append(azim)
+            self.candidate_camera_elevs.append(20)
+            self.candidate_view_weights.append(0.01)
+
+            self.candidate_camera_azims.append(azim)
+            self.candidate_camera_elevs.append(-20)
+            self.candidate_view_weights.append(0.01)
+
+
+class Hunyuan3DPaintPipeline:
+
+    def __init__(self, config=None) -> None:
+        self.config = config if config is not None else Hunyuan3DPaintConfig()
+        self.models = {}
+        self.stats_logs = {}
+        self.render = MeshRender(
+            default_resolution=self.config.render_size,
+            texture_size=self.config.texture_size,
+            bake_mode=self.config.bake_mode,
+            raster_mode=self.config.raster_mode,
+        )
+        self.view_processor = ViewProcessor(self.config, self.render)
+        self.load_models()
+
+    def load_models(self):
+        torch.cuda.empty_cache()
+        self.models["super_model"] = imageSuperNet(self.config)
+        self.models["multiview_model"] = multiviewDiffusionNet(self.config)
+        print("Models Loaded.")
+
+    @torch.no_grad()
+    def __call__(self, mesh_path=None, image_path=None, output_mesh_path=None, use_remesh=True, save_glb=True):
+        """Generate texture for 3D mesh using multiview diffusion"""
+        # Ensure image_prompt is a list
+        if isinstance(image_path, str):
+            image_prompt = Image.open(image_path)
+        elif isinstance(image_path, Image.Image):
+            image_prompt = image_path
+        if not isinstance(image_prompt, List):
+            image_prompt = [image_prompt]
+        else:
+            image_prompt = image_path
+
+        # Process mesh
+        path = os.path.dirname(mesh_path)
+        if use_remesh:
+            processed_mesh_path = os.path.join(path, "white_mesh_remesh.obj")
+            remesh_mesh(mesh_path, processed_mesh_path)
+        else:
+            processed_mesh_path = mesh_path
+
+        # Output path
+        if output_mesh_path is None:
+            output_mesh_path = os.path.join(path, f"textured_mesh.obj")
+
+        # Load mesh
+        mesh = trimesh.load(processed_mesh_path)
+        mesh = mesh_uv_wrap(mesh)
+        self.render.load_mesh(mesh=mesh)
+
+        ########### View Selection #########
+        selected_camera_elevs, selected_camera_azims, selected_view_weights = self.view_processor.bake_view_selection(
+            self.config.candidate_camera_elevs,
+            self.config.candidate_camera_azims,
+            self.config.candidate_view_weights,
+            self.config.max_selected_view_num,
+        )
+
+        normal_maps = self.view_processor.render_normal_multiview(
+            selected_camera_elevs, selected_camera_azims, use_abs_coor=True
+        )
+        position_maps = self.view_processor.render_position_multiview(selected_camera_elevs, selected_camera_azims)
+
+        ##########  Style  ###########
+        image_caption = "high quality"
+        image_style = []
+        for image in image_prompt:
+            image = image.resize((512, 512))
+            if image.mode == "RGBA":
+                white_bg = Image.new("RGB", image.size, (255, 255, 255))
+                white_bg.paste(image, mask=image.getchannel("A"))
+                image = white_bg
+            image_style.append(image)
+        image_style = [image.convert("RGB") for image in image_style]
+
+        ###########  Multiview  ##########
+        multiviews_pbr = self.models["multiview_model"](
+            image_style,
+            normal_maps + position_maps,
+            prompt=image_caption,
+            custom_view_size=self.config.resolution,
+            resize_input=True,
+        )
+        ###########  Enhance  ##########
+        enhance_images = {}
+        enhance_images["albedo"] = copy.deepcopy(multiviews_pbr["albedo"])
+        enhance_images["mr"] = copy.deepcopy(multiviews_pbr["mr"])
+
+        for i in range(len(enhance_images["albedo"])):
+            enhance_images["albedo"][i] = self.models["super_model"](enhance_images["albedo"][i])
+            enhance_images["mr"][i] = self.models["super_model"](enhance_images["mr"][i])
+
+        ###########  Bake  ##########
+        for i in range(len(enhance_images)):
+            enhance_images["albedo"][i] = enhance_images["albedo"][i].resize(
+                (self.config.render_size, self.config.render_size)
+            )
+            enhance_images["mr"][i] = enhance_images["mr"][i].resize((self.config.render_size, self.config.render_size))
+        texture, mask = self.view_processor.bake_from_multiview(
+            enhance_images["albedo"], selected_camera_elevs, selected_camera_azims, selected_view_weights
+        )
+        mask_np = (mask.squeeze(-1).cpu().numpy() * 255).astype(np.uint8)
+        texture_mr, mask_mr = self.view_processor.bake_from_multiview(
+            enhance_images["mr"], selected_camera_elevs, selected_camera_azims, selected_view_weights
+        )
+        mask_mr_np = (mask_mr.squeeze(-1).cpu().numpy() * 255).astype(np.uint8)
+
+        ##########  inpaint  ###########
+        texture = self.view_processor.texture_inpaint(texture, mask_np)
+        self.render.set_texture(texture, force_set=True)
+        if "mr" in enhance_images:
+            texture_mr = self.view_processor.texture_inpaint(texture_mr, mask_mr_np)
+            self.render.set_texture_mr(texture_mr)
+
+        self.render.save_mesh(output_mesh_path, downsample=True)
+
+        if save_glb:
+            convert_obj_to_glb(output_mesh_path, output_mesh_path.replace(".obj", ".glb"))
+            output_glb_path = output_mesh_path.replace(".obj", ".glb")
+
+        return output_mesh_path

hy3dpaint/utils/multiview_utils.py

@@ -0,0 +1,128 @@
+# Hunyuan 3D is licensed under the TENCENT HUNYUAN NON-COMMERCIAL LICENSE AGREEMENT
+# except for the third-party components listed below.
+# Hunyuan 3D does not impose any additional limitations beyond what is outlined
+# in the repsective licenses of these third-party components.
+# Users must comply with all terms and conditions of original licenses of these third-party
+# components and must ensure that the usage of the third party components adheres to
+# all relevant laws and regulations.
+
+# For avoidance of doubts, Hunyuan 3D means the large language models and
+# their software and algorithms, including trained model weights, parameters (including
+# optimizer states), machine-learning model code, inference-enabling code, training-enabling code,
+# fine-tuning enabling code and other elements of the foregoing made publicly available
+# by Tencent in accordance with TENCENT HUNYUAN COMMUNITY LICENSE AGREEMENT.
+
+import os
+import torch
+import random
+import numpy as np
+from PIL import Image
+from typing import List
+import huggingface_hub
+from omegaconf import OmegaConf
+from diffusers import DiffusionPipeline
+from diffusers import EulerAncestralDiscreteScheduler, DDIMScheduler, UniPCMultistepScheduler
+
+
+class multiviewDiffusionNet:
+    def __init__(self, config) -> None:
+        self.device = config.device
+
+        cfg_path = config.multiview_cfg_path
+        custom_pipeline = config.custom_pipeline
+        cfg = OmegaConf.load(cfg_path)
+        self.cfg = cfg
+        self.mode = self.cfg.model.params.stable_diffusion_config.custom_pipeline[2:]
+
+        model_path = huggingface_hub.snapshot_download(
+            repo_id=config.multiview_pretrained_path,
+            allow_patterns=["hunyuan3d-paintpbr-v2-1/*"],
+        )
+
+        model_path = os.path.join(model_path, "hunyuan3d-paintpbr-v2-1")
+        pipeline = DiffusionPipeline.from_pretrained(
+            model_path,
+            custom_pipeline=custom_pipeline, 
+            torch_dtype=torch.float16
+        )
+
+        pipeline.scheduler = UniPCMultistepScheduler.from_config(pipeline.scheduler.config, timestep_spacing="trailing")
+        pipeline.set_progress_bar_config(disable=True)
+        pipeline.eval()
+        setattr(pipeline, "view_size", cfg.model.params.get("view_size", 320))
+        self.pipeline = pipeline.to(self.device)
+
+        if hasattr(self.pipeline.unet, "use_dino") and self.pipeline.unet.use_dino:
+            from hunyuanpaintpbr.unet.modules import Dino_v2
+            self.dino_v2 = Dino_v2(config.dino_ckpt_path).to(torch.float16)
+            self.dino_v2 = self.dino_v2.to(self.device)
+
+    def seed_everything(self, seed):
+        random.seed(seed)
+        np.random.seed(seed)
+        torch.manual_seed(seed)
+        os.environ["PL_GLOBAL_SEED"] = str(seed)
+
+    @torch.no_grad()
+    def __call__(self, images, conditions, prompt=None, custom_view_size=None, resize_input=False):
+        pils = self.forward_one(
+            images, conditions, prompt=prompt, custom_view_size=custom_view_size, resize_input=resize_input
+        )
+        return pils
+
+    def forward_one(self, input_images, control_images, prompt=None, custom_view_size=None, resize_input=False):
+        self.seed_everything(0)
+        custom_view_size = custom_view_size if custom_view_size is not None else self.pipeline.view_size
+        if not isinstance(input_images, List):
+            input_images = [input_images]
+        if not resize_input:
+            input_images = [
+                input_image.resize((self.pipeline.view_size, self.pipeline.view_size)) for input_image in input_images
+            ]
+        else:
+            input_images = [input_image.resize((custom_view_size, custom_view_size)) for input_image in input_images]
+        for i in range(len(control_images)):
+            control_images[i] = control_images[i].resize((custom_view_size, custom_view_size))
+            if control_images[i].mode == "L":
+                control_images[i] = control_images[i].point(lambda x: 255 if x > 1 else 0, mode="1")
+        kwargs = dict(generator=torch.Generator(device=self.pipeline.device).manual_seed(0))
+
+        num_view = len(control_images) // 2
+        normal_image = [[control_images[i] for i in range(num_view)]]
+        position_image = [[control_images[i + num_view] for i in range(num_view)]]
+
+        kwargs["width"] = custom_view_size
+        kwargs["height"] = custom_view_size
+        kwargs["num_in_batch"] = num_view
+        kwargs["images_normal"] = normal_image
+        kwargs["images_position"] = position_image
+
+        if hasattr(self.pipeline.unet, "use_dino") and self.pipeline.unet.use_dino:
+            dino_hidden_states = self.dino_v2(input_images[0])
+            kwargs["dino_hidden_states"] = dino_hidden_states
+
+        sync_condition = None
+
+        infer_steps_dict = {
+            "EulerAncestralDiscreteScheduler": 30,
+            "UniPCMultistepScheduler": 15,
+            "DDIMScheduler": 50,
+            "ShiftSNRScheduler": 15,
+        }
+
+        mvd_image = self.pipeline(
+            input_images[0:1],
+            num_inference_steps=infer_steps_dict[self.pipeline.scheduler.__class__.__name__],
+            prompt=prompt,
+            sync_condition=sync_condition,
+            guidance_scale=3.0,
+            **kwargs,
+        ).images
+
+        if "pbr" in self.mode:
+            mvd_image = {"albedo": mvd_image[:num_view], "mr": mvd_image[num_view:]}
+            # mvd_image = {'albedo':mvd_image[:num_view]}
+        else:
+            mvd_image = {"hdr": mvd_image}
+
+        return mvd_image