readme

.gitattributes

@@ -33,3 +33,6 @@ saved_model/**/* filter=lfs diff=lfs merge=lfs -text
 *.zip filter=lfs diff=lfs merge=lfs -text
 *.zst filter=lfs diff=lfs merge=lfs -text
 *tfevents* filter=lfs diff=lfs merge=lfs -text
+*.png filter=lfs diff=lfs merge=lfs -text
+*.jpg filter=lfs diff=lfs merge=lfs -text
+*.jpeg filter=lfs diff=lfs merge=lfs -text

README.md

@@ -2,7 +2,89 @@
 license: apache-2.0
 ---
 
-# Step1X-3D
 
- - Step1X-Geometry
- - Step1X-Texture
+<h1 align="center"> Step1X-3D: Towards High-Fidelity and Controllable<br>Generation of Textured 3D Assets</h1>
+
+<p align="center">
+  <img src="assets/stepfun_illusions_logo.jpeg" width="100%">
+</p>
+
+<div align="center">
+<img width="" alt="demo" src="assets/step1x-3d-teaser.png">
+</div>
+
+<div align="left">
+<p><b>Step1X-3D demonstrates the capability to generate 3D assets with high-fidelity geometry and versatile texture maps, while maintaining exceptional alignment between surface geometry and texture mapping. From left to right, we sequentially present: the base geometry (untextured), followed by cartoon-style, sketch-style, and photorealistic 3D asset generation results.</b></p>
+</div>
+
+
+## 🔥🔥🔥 Latest News!!
+* May 13, 2025: 👋 Step1X-3D online demo is available on huggingface-enjoy yourself with generated 3D assets! [Huggingface web live](https://huggingface.co/spaces/stepfun-ai/Step1X-3D)
+* May 13, 2025: 👋 We release the 800K uids of high quality 3D assets (excluding self-collected assets) obtained with our rigorous data curation pipeline for both training 3D geometry and synthesis. [Huggingface dataset](https://huggingface.co/datasets/stepfun-ai/Step1X-3D-obj-data/tree/main)
+* May 13, 2025: 👋 We have also release the training code of both Step1X-3D geometry generation and texture synthesis. 
+* May 13, 2025: 👋 We have released the inference code and model weights of Step1X-3D geometry and Step1X-3D texture.
+* May 13, 2025: 👋 We have released Step1X-3D [technical report]() as open source.
+
+## Introduction
+While generative artificial intelligence has advanced significantly across text, image, audio, and video domains, 3D generation remains comparatively underdeveloped due to fundamental challenges such as data scarcity, algorithmic limitations, and ecosystem fragmentation. 
+To this end, we present Step1X-3D, an open framework addressing these challenges through: 
+(1) a rigorous data curation pipeline processing >5M assets to create a 2M high-quality dataset with standardized geometric and textural properties; 
+(2) a two-stage 3D-native architecture combining a hybrid VAE-DiT geometry generator 
+with an SD-XL-based texture synthesis module; and (3) the full open-source release of models, training code, and adaptation modules. For geometry generation, the hybrid VAE-DiT component produces watertight TSDF representations by employing perceiver-based latent encoding with sharp edge sampling for detail preservation. The SD-XL-based texture synthesis module then ensures cross-view consistency through geometric conditioning and latent-space synchronization.
+Benchmark results demonstrate state-of-the-art performance that exceeds existing open-source methods, while also achieving competitive quality with proprietary solutions. 
+Notebly, the framework uniquely bridges 2D and 3D generation paradigms by supporting direct transfer of 2D control techniques~(e.g., LoRA) to 3D synthesis.
+By simultaneously advancing data quality, algorithmic fidelity, and reproducibility, Step1X-3D aims to establish new standards for open research in controllable 3D asset generation.
+<img width="" alt="framework" src="assets/step1x-3d-framework-overall.jpg">
+
+
+## Usage
+
+```python
+# Stage 1: 3D geometry generation
+from step1x3d_geometry.models.pipelines.pipeline import Step1X3DGeometryPipeline
+
+# define the pipeline
+geometry_pipeline = Step1X3DGeometryPipeline.from_pretrained("stepfun-ai/Step1X-3D", subfolder='Step1X-3D-Geometry-1300m'
+).to("cuda")
+
+# input image
+input_image_path = "examples/test.png"
+
+# run pipeline and obtain the untextured mesh 
+generator = torch.Generator(device=geometry_pipeline.device).manual_seed(2025)
+out = geometry_pipeline(input_image_path，guidance_scale=7.5, num_inference_steps=50)
+
+# export untextured mesh as .glb format
+out.mesh[0].export("untexture_mesh.glb")
+
+
+# Stage 2: 3D texure synthsis
+from step1x3d_texture.pipelines.step1x_3d_texture_synthesis_pipeline import (
+    Step1X3DTexturePipeline,
+)
+from step1x3d_geometry.models.pipelines.pipeline_utils import reduce_face, remove_degenerate_face
+import trimesh
+
+# load untextured mesh
+untexture_mesh = trimesh.load("untexture_mesh.glb")
+
+# define texture_pipeline
+texture_pipeline = Step1X3DTexturePipeline.from_pretrained("stepfun-ai/Step1X-3D", subfolder="Step1X-3D-Texture")
+
+# reduce face
+untexture_mesh = remove_degenerate_face(untexture_mesh)
+untexture_mesh = reduce_face(untexture_mesh)
+
+# texture mapping
+textured_mesh = texture_pipeline(input_image_path, untexture_mesh)
+
+# export textured mesh as .glb format
+textured_mesh.export("textured_mesh.glb")
+```
+
+## Citation
+If you find our work helpful, please cite us
+
+```
+
+```