Upload README.md with huggingface_hub

README.md

@@ -1,108 +1,113 @@
-# DeepFracture: A Generative Approach for Predicting Brittle Fractures with Neural Discrete Representation Learning
+# Model Card for DeepFracture
 
-This is a collection of pre-trained models for deepfracture: a conditional vq-vae model for predicting fracture pattern from impulse code, trained on the [Break4Models](https://huggingface.co/datasets/nikoloside/break4models) dataset created by [FractureRB](https://github.com/david-hahn/FractureRB).
+## Model Description
 
+- **Model type**: 3D Fracture Pattern Prediction via impulse-code conditional VQ-VAE models
+- **Language(s)**: Python
+- **License**: Apache-2.0
+- **Finetuned from model**: Custom architecture
 
-📖 **For more details, please visit:**
-- [GitHub Repository](https://github.com/nikoloside/TEBP)
-- [Project Page](https://nikoloside.graphics/deepfracture/)
+### Model Sources
 
-## Overview
+- **Repository**: https://github.com/nikoloside/TEBP
+- **Paper**: https://doi.org/10.1111/cgf.70002
+- **Demo**: [WIP]
 
-These models are designed to predict fracture patterns based on impact conditions. Each model is trained on a specific target shape and can be used for real-time physics simulation and computer graphics applications.
+## Uses
 
-## Model Architecture
+### Direct Use
 
-The models use an encoder-decoder architecture:
-- **Encoder**: Processes input impulse conditions and generates latent representations
-- **Decoder**: Reconstructs GS-SDF(Geometrically-Segmented Signed Distance Fields) from latent representations
-- **Training**: Supervised learning on physics simulation data
+These models are designed for:
+- Computer graphics applications
+- Game development
+- Virtual reality environments
+- Paper code release
 
-## Available Models
+### Out-of-Scope Use
 
-```
-pre-trained-v2/
-├── base/           # Base object model
-├── pot/            # Pot object model
-├── squirrel/       # Squirrel object model
-├── bunny/          # Bunny object model
-├── lion/           # Lion object model
-└── README.md       # This file
-```
+- Medical applications
+- Safety-critical systems
+- High-precision engineering simulations
 
-Each model directory contains:
-- `{shape}.obj` - Reference original 3D mesh file
-- `{shape}-encoder.pt` - Encoder weights
-- `{shape}-decoder.pt` - Decoder weights
-- `{shape}-1000-encoder.pt` - Encoder weights (1000 epoch version)
-- `{shape}-1000-decoder.pt` - Decoder weights (1000 epoch version)
+## Bias, Risks, and Limitations
 
-## Usage
+### Bias
 
-### Loading Models
+The models are trained on synthetic simulation data and may not generalize well to real-world scenarios with different material properties or environmental conditions.
 
-```python
-import torch
-from your_model_architecture import Encoder, Decoder
+### Risks
 
-# Load encoder
-encoder = Encoder()
-encoder.load_state_dict(torch.load('base/base-encoder.pt'))
-encoder.eval()
+- Models may produce unrealistic deformations under extreme conditions
+- Performance may significantly different from training data
+- No guarantees for physical accuracy in safety-critical applications
 
-# Load decoder  
-decoder = Decoder()
-decoder.load_state_dict(torch.load('base/base-decoder.pt'))
-decoder.eval()
+### Limitations
 
-# Load reference mesh
-import trimesh
-reference_mesh = trimesh.load('base/base.obj')
-```
+- Limited to the specific one target shape and object categories in the training dataset
+- Be able to reach real-time inference in network, but need resconstruction within 2-10 seconds
 
-### Inference
+## Training Details
 
-[Example](https://github.com/nikoloside/TEBP/blob/main/04.Run-time/predict-runtime.py)
-[Details](https://github.com/nikoloside/TEBP/blob/main/04.Run-time/MorphoImageJ.py#L34)
+### Training Data
 
-```python
-# Prepare input conditions
-input_conditions = prepare_impact_conditions(impact_point, velocity, impulse_strength)
+- **Dataset**: Break4Model dataset
+- **Training samples**: Varies by model (277-433 samples per category)
+- **Validation samples**: 20% of training data
+- **Data preprocessing**: Normalized impact conditions and geometry of GS-SDF
 
-# Encode
-with torch.no_grad():
-    latent = encoder(input_conditions)
-    
-# Decode
-deformed_geometry = decoder(latent)
+### Training Procedure
 
-# Apply to reference mesh
-result_mesh = processCagedSDFSeg(ri, work_path, obj_path, isBig = False, maxValue = 1.0)
-```
+- **Training regime**: Supervised learning
+- **Optimizer**: Adam
+- **Learning rate**: 1e-3 - 1e-5
+- **Batch size**: 1
+- **Training epochs**: 1000
+- **Hardware**: NVIDIA RTX 3090 GPU
+- **Training time**: ~24 hours per model
 
-## Model Performance
+### Training Results
 
-Each model has been trained and validated on the corresponding object category:
+(metrics and performance)[https://doi.org/10.1111/cgf.70002]
 
-| Model | Training Samples | Validation Accuracy | Inference Time |
-|-------|------------------|-------------------|----------------|
-| base | 277 | 94.2% | ~5ms |
-| pot | 433 | 91.8% | ~6ms |
-| squirrel | [TBD] | [TBD] | [TBD] |
-| bunny | [TBD] | [TBD] | [TBD] |
-| lion | [TBD] | [TBD] | [TBD] |
+## Evaluation
 
-## Training Details
+### Testing Data
+
+- **Dataset**: Break4Models
+- **Metrics**: Geometric accuracy, Fragment size, Inference time, Fragment distribution, Surface normals, MPCD (Multiple-Phase Charmfer Distance)
 
+### Results
+
+The models achieve high accuracy in predicting fracture patterns while maintaining nearly real-time performance suitable for interactive applications.
+
+## Environmental Impact
+
+- **Hardware Type**: GPU
+- **Hours used**: ~24 hours per model
 - **Dataset**: Break4Model dataset
 - **Framework**: PyTorch
 - **Optimizer**: Adam
 - **Loss Function**: L2 Loss
 - **Training Time**: ~24 hours per model on NVIDIA RTX 3090
 
-## Citation
+## Technical Specifications
+
+### Model Architecture
 
-If you use these models in your research, please cite:
+- **Encoder**: SIREN Layer
+- **Decoder**: CNN
+- **Parameters**: ~2M parameters per model
+- **Input**: Impact conditions (position, velocity, impulse strength) from Bullet3
+- **Output**: GS-SDF (Geometrically-Segmented Signed Distance Fields)
+
+### Compute Requirements
+
+- **Training**: NVIDIA RTX 3090 or equivalent
+- **Inference**: CPU or GPU
+- **Memory**: 8GB RAM minimum
+- **Storage**: ~200MB per model
+
+## Citation
 
 ```bibtex
 @article{huang2025deepfracture,
@@ -118,10 +123,10 @@ eprint = {https://onlinelibrary.wiley.com/doi/pdf/10.1111/cgf.70002}
 }
 ```
 
-## License
+## Data Card Authors
 
-APACHE 2.0
+Huang Niko(nikoloside), Fang Chaowei(fangsunjian)
 
-## Contact
+## Data Card Contact
 
-For questions or issues, please open an issue on the Hugging Face model page.
+https://github.com/nikoloside/TEBP