This project implements an InceptionV4-based deep learning model for predicting the stability of block towers. Using the ShapeStacks dataset, the model performs binary classification to determine whether a block tower will collapse (stable vs. unstable).
The project is herited from original codes, and is adapted for tensorflow 2+.
Predicting structural stability is a critical challenge in architecture, robotics, and disaster prevention. Humans can quickly judge stability through visual intuition and experience—a skill rooted in implicit physical knowledge and causal reasoning. This project aims to replicate this capability using deep learning, bridging the gap between visual perception and physical reasoning.
- InceptionV4 Architecture: State-of-the-art CNN for image classification
- Binary Classification: Predicts whether a tower is stable (0) or unstable (1)
- ShapeStacks Dataset: Synthetic block tower images with stability annotations
- Data Augmentation: Extensive augmentation pipeline for robust training
- TensorBoard Integration: Real-time training monitoring and visualization
Stability-Predictor/
├── data_provider/
│ └── shapestacks_provider.py # Data loading and preprocessing
├── tf_models/
│ └── inception/
│ ├── inception_v4.py # InceptionV4 architecture
│ └── inception_model.py # Model definition and training logic
├── intuitive_physics/
│ └── stability_predictor/
│ ├── train_inception_v4_shapestacks.py # Training script
│ └── test_inception_v4_shapestacks.py # Testing script
├── dataset/ # This should be downloaded mannually
│ └── shapestacks/ # Dataset directory
│ ├── recordings/ # Image data
│ ├── splits/ # Train/eval/test splits
│ │ └── ccs_all/
│ │ ├── train.txt
│ │ ├── eval.txt
│ │ ├── test.txt
│ │ └── *_bgr_mean.npy
│ ├── mjcf/ # MuJoCo simulation files
│ └── meta/ # Metadata and blacklists
├── output_ccs_all/ # Training output directory
│ ├── snapshots/ # Best model checkpoints
│ └── events.out.tfevents.* # TensorBoard logs
└── README.md
- Python 3.8+
- CUDA 11.0+ (for GPU support)
- cuDNN 8.0+
- tensorflow 2.0.0+
Following is performed on Nvidia A100, 80G.
# Create conda environment compatible with A100
conda create -n stability_predictor python=3.8
conda activate stability_predictor
conda install -c conda-forge cudatoolkit=11.2 cudnn=8.1 -y
# Install TensorFlow (GPU version)
pip install tensorflow==2.8.0
# Install other dependencies
pip install numpy matplotlib PillowDownload the ShapeStacks dataset from the provided link and extract it to lab3_dataset/shapestacks/.
shapestacks/
├── recordings/ # RGB images of block towers
│ └── env_*/
│ ├── rgb-*.png
│ ├── log.txt # Contains "Stack collapse: True/False"
│ └── depth_log.txt
├── splits/
│ └── ccs_all/ # Data split configuration
│ ├── train.txt # Training scenarios
│ ├── eval.txt # Validation scenarios
│ ├── test.txt # Test scenarios
│ └── *_bgr_mean.npy # Mean values for normalization
└── mjcf/ # MuJoCo configuration files
- Label 0: Stable tower (Stack collapse: False)
- Label 1: Unstable tower (Stack collapse: True)
Following is how to train and test this model quickly. You can view detailed command-line instructions in run.sh.
export SHAPESTACKS_CODE_HOME=./# Basic training
export CUDA_VISIBLE_DEVICES=0 # Use single GPU, you can modify it
# use ccs_all split data
python intuitive_physics/stability_predictor/train_inception_v4_shapestacks.py \
--data_dir /path/to/lab3_dataset/shapestacks \
--model_dir ./output_ccs_all \
--split_name ccs_all \
--train_epochs 40 \
--batch_size 32
# use blocks_all split data
python intuitive_physics/stability_predictor/train_inception_v4_shapestacks.py \
--data_dir /path/to/lab3_dataset/shapestacks \
--model_dir ./output_blocks_all \
--split_name blocks_all \
--train_epochs 40 \
--batch_size 32
# or choose to run in background with logging
nohup python intuitive_physics/stability_predictor/train_inception_v4_shapestacks.py \
--data_dir /path/to/lab3_dataset/shapestacks \
--model_dir ./output_ccs_all \
--split_name ccs_all \
--train_epochs 40 \
--batch_size 32 > train_ccs.log 2>&1 &
nohup python intuitive_physics/stability_predictor/train_inception_v4_shapestacks.py \
--data_dir /data1/shuyang/lab3_dataset/shapestacks \
--model_dir ./output_blocks_all \
--split_name blocks_all \
--train_epochs 40 \
--batch_size 32 > train_blocks.log 2>&1 &# Monitor log file
tail -f train_ccs.log
tail -f train_blocks.log
# Monitor GPU usage
watch -n 1 nvidia-smi
# Start TensorBoard
tensorboard --logdir=./output_ccs_all --port=6006
# Open browser: http://localhost:6006python intuitive_physics/stability_predictor/test_inception_v4_shapestacks.py \
--data_dir /path/to/lab3_dataset/shapestacks \
--model_dir ./output_ccs_all \
--split_name ccs_all \
--batch_size 32
python intuitive_physics/stability_predictor/test_inception_v4_shapestacks.py \
--data_dir /data1/shuyang/lab3_dataset/shapestacks \
--model_dir ./output_blocks_all \
--split_name blocks_all \
--batch_size 32| Parameter | Default | Description |
|---|---|---|
--data_dir |
Required | Path to ShapeStacks dataset |
--model_dir |
Required | Directory for model outputs |
--split_name |
ccs_all |
Dataset split to use |
--train_epochs |
40 |
Total training epochs |
--epochs_per_eval |
1 |
Evaluation frequency |
--batch_size |
32 |
Training batch size |
--n_best_eval |
5 |
Number of best checkpoints to keep |
--memcap |
0.8 |
GPU memory fraction to use |
--n_prefetch |
32 |
Number of batches to prefetch |
Default augmentations applied during training:
- Random cropping and resizing
- Random horizontal flip
- Random rotation (±2 degrees)
- Color jittering (brightness, saturation, hue, contrast)
- Gaussian noise
- Value clipping
# Customize augmentation
python train_inception_v4_shapestacks.py \
--augment crop flip recolour clip \
...Epoch 1/40
INFO:tensorflow:loss = 0.693147, step = 1
INFO:tensorflow:loss = 0.682340, step = 100
...
Evaluation results:
accuracy: 0.652341
global_step: 5000
loss: 0.621234
Top-5 models so far:
Accuracy: 0.652341 - eval=0.652341
Available metrics:
- Loss: Training and validation loss curves
- Accuracy: Training and validation accuracy
- Learning Rate: RMSProp learning rate schedule
- Images: Sample input images (if
--display_inputs > 0)
output_ccs_all/
├── model.ckpt-* # Latest checkpoint
├── checkpoint # Checkpoint metadata
├── events.out.tfevents.* # TensorBoard logs
├── graph.pbtxt # Model graph
├── snapshots/ # Best models
│ ├── eval=0.850000/
│ │ ├── model.ckpt-*
│ │ └── checkpoint
│ └── ...
└── info_*.txt # Training configuration
Modify inception_model.py:
# Add learning rate decay
global_step = tf.train.get_global_step()
learning_rate = tf.train.exponential_decay(
learning_rate=_START_LEARNING_RATE,
global_step=global_step,
decay_steps=1000,
decay_rate=0.9,
staircase=True
)
optimizer = tf.train.RMSPropOptimizer(
learning_rate=learning_rate,
decay=_DECAY,
epsilon=_EPSILON
)
# Log learning rate
tf.summary.scalar('learning_rate', learning_rate)Training automatically resumes from the latest checkpoint if model_dir contains previous checkpoints:
# Will resume from existing checkpoint
python train_inception_v4_shapestacks.py \
--model_dir ./output_ccs_all \
...- InceptionV4 Paper: Inception-v4, Inception-ResNet and the Impact of Residual Connections on Learning
- ShapeStacks Dataset: ShapeStacks: Learning Vision-Based Physical Intuition for Generalised Object Stacking
- TensorFlow Estimator API: TensorFlow Estimator Guide
If you find this project insightful and helpful, or if you find there exist bugs in the project, feel free to email: shuyoung@stanford.edu