Upload 30 files

.dockerignore

@@ -0,0 +1,47 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+*.egg-info/
+dist/
+build/
+
+# Virtual environments
+venv/
+env/
+ENV/
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+
+# Git
+.git/
+.gitignore
+
+# Output directories (will be mounted as volumes)
+output/
+temp_output/
+
+# Documentation
+*.md
+README.md
+DOCKER.md
+
+# Docker files (don't need in image)
+docker-compose.yml
+Dockerfile
+.dockerignore
+
+# Large data files - NOTE: We NEED these for Blender to work
+# *.blend
+# data/shapes/
+# data/materials/
+
+# OS files
+.DS_Store
+Thumbs.db

.gitattributes

@@ -1,35 +1,37 @@
-*.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
+*.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
+*.blend filter=lfs diff=lfs merge=lfs -text
+scripts/__pycache__/generate_questions_mapping.cpython-312.pyc filter=lfs diff=lfs merge=lfs -text

.gitignore

@@ -0,0 +1,46 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+env/
+venv/
+ENV/
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+
+
+# Output directory (generated scenes and images)
+output/
+
+# Blender temp files
+temp_output/
+temp_scenes/
+render_images_patched.py
+render_patched.py
+*.blend1
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+
+# OS
+.DS_Store
+Thumbs.db

DOCKER.md

@@ -0,0 +1,147 @@
+# Docker Setup for Counterfactual Image Generator
+
+This project includes Docker support for easy deployment and consistent environments.
+
+**Windows Note:** This Dockerfile uses a Linux container (Ubuntu), which works perfectly on Windows. Docker Desktop on Windows runs Linux containers by default. The containerized environment is Linux, so Windows-specific code paths in the application won't apply inside the container.
+
+## Building the Docker Image
+
+```bash
+docker build -t counterfactual-generator .
+```
+
+## Running with Docker
+
+### Basic Usage
+
+**Linux/macOS:**
+```bash
+# Run with default command (shows help)
+docker run --rm counterfactual-generator
+
+# Generate 10 scenes with 5 objects each
+docker run --rm -v $(pwd)/output:/app/output counterfactual-generator \
+  python3 pipeline.py --num_scenes 10 --num_objects 5 --run_name docker_test
+
+# With GPU support (requires nvidia-docker)
+docker run --rm --gpus all -v $(pwd)/output:/app/output counterfactual-generator \
+  python3 pipeline.py --num_scenes 10 --num_objects 5 --use_gpu 1
+```
+
+**Windows (PowerShell):**
+```powershell
+# Run with default command (shows help)
+docker run --rm counterfactual-generator
+
+# Generate 10 scenes with 5 objects each
+docker run --rm -v ${PWD}/output:/app/output counterfactual-generator `
+  python3 pipeline.py --num_scenes 10 --num_objects 5 --run_name docker_test
+
+# With GPU support (requires WSL2 and nvidia-docker)
+docker run --rm --gpus all -v ${PWD}/output:/app/output counterfactual-generator `
+  python3 pipeline.py --num_scenes 10 --num_objects 5 --use_gpu 1
+```
+
+**Windows (Command Prompt):**
+```cmd
+docker run --rm -v "%CD%/output:/app/output" counterfactual-generator ^
+  python3 pipeline.py --num_scenes 10 --num_objects 5 --run_name docker_test
+```
+
+### Using Docker Compose
+
+```bash
+# Build and run with docker-compose
+docker-compose up
+
+# Run in detached mode
+docker-compose up -d
+
+# View logs
+docker-compose logs -f
+
+# Stop the container
+docker-compose down
+```
+
+### Customize the Command
+
+Edit `docker-compose.yml` to change the default command:
+
+```yaml
+command: python3 pipeline.py --num_scenes 10 --num_objects 5 --use_gpu 1 --run_name my_experiment
+```
+
+## Volume Mounting
+
+The output directory is mounted to `./output` on your host machine, so generated scenes and images will persist after the container stops.
+
+## GPU Support
+
+For GPU rendering support, ensure you have:
+1. NVIDIA Docker runtime installed
+2. Use `--gpus all` flag with `docker run` or add to `docker-compose.yml`:
+
+```yaml
+deploy:
+  resources:
+    reservations:
+      devices:
+        - driver: nvidia
+          count: all
+          capabilities: [gpu]
+```
+
+## Windows-Specific Notes
+
+1. **Docker Desktop Required**: Install Docker Desktop for Windows from [docker.com](https://www.docker.com/products/docker-desktop)
+
+2. **Path Format**: Use forward slashes or PowerShell variables:
+   - PowerShell: `-v ${PWD}/output:/app/output`
+   - CMD: `-v "%CD%/output:/app/output"`
+   - Or use absolute paths: `-v C:/path/to/output:/app/output`
+
+3. **WSL2**: Docker Desktop on Windows uses WSL2. Make sure WSL2 is enabled in Windows features.
+
+4. **GPU Support on Windows**: Requires:
+   - WSL2 with NVIDIA GPU driver
+   - nvidia-docker installed in WSL2
+   - May not work on all Windows setups
+
+## Troubleshooting
+
+### Blender Not Found
+If you get errors about Blender not being found, verify the installation:
+```bash
+# Linux/macOS
+docker run --rm counterfactual-generator blender --version
+
+# Windows PowerShell
+docker run --rm counterfactual-generator blender --version
+```
+
+### Permission Issues
+**Linux/macOS:**
+```bash
+sudo chown -R $USER:$USER output/
+```
+
+**Windows:** Usually not an issue, but if you encounter permission errors, run Docker Desktop as Administrator or adjust folder permissions.
+
+### Interactive Shell
+**Linux/macOS:**
+```bash
+docker run --rm -it -v $(pwd)/output:/app/output counterfactual-generator /bin/bash
+```
+
+**Windows (PowerShell):**
+```powershell
+docker run --rm -it -v ${PWD}/output:/app/output counterfactual-generator /bin/bash
+```
+
+## Notes
+
+- The image includes Blender 4.3, which is compatible with the codebase
+- Credentials and tokens are excluded from the Docker image for security
+- Output files are stored in the mounted volume to persist data
+

Dockerfile

@@ -0,0 +1,71 @@
+# Use Python 3.9 slim image for smaller size
+FROM python:3.9-slim
+
+# 1. Install system dependencies including Xvfb for headless rendering
+# We install these as root before switching users
+RUN apt-get update && apt-get install -y \
+    wget \
+    xz-utils \
+    xvfb \
+    libx11-6 \
+    libxxf86vm1 \
+    libgl1 \
+    libglu1-mesa \
+    libxi6 \
+    libxrender1 \
+    libxfixes3 \
+    libfontconfig1 \
+    libxinerama1 \
+    libxkbcommon0 \
+    && rm -rf /var/lib/apt/lists/*
+
+# 2. Set up a non-root user (Critical for Hugging Face Spaces)
+# Spaces run as user ID 1000. If we don't do this, we get permission errors.
+RUN useradd -m -u 1000 user
+USER user
+ENV HOME=/home/user \
+    PATH=/home/user/.local/bin:$PATH
+
+# Set working directory to the new user's home
+WORKDIR $HOME/app
+
+# 3. Install Blender (User-level install)
+# Downloading to a folder the user owns
+RUN wget -q https://download.blender.org/release/Blender3.6/blender-3.6.8-linux-x64.tar.xz -O /tmp/blender.tar.xz && \
+    tar -xf /tmp/blender.tar.xz -C /tmp && \
+    mkdir -p $HOME/blender && \
+    mv /tmp/blender-3.6.8-linux-x64/* $HOME/blender/ && \
+    rm -rf /tmp/blender.tar.xz /tmp/blender-3.6.8-linux-x64 && \
+    # Add Blender to PATH so we can just type 'blender'
+    echo 'export PATH="$HOME/blender:$PATH"' >> $HOME/.bashrc
+
+# Update PATH for this session as well
+ENV PATH="$HOME/blender:$PATH"
+
+# Verify Blender installation
+RUN blender --version
+
+# 4. Install Python dependencies
+COPY --chown=user requirements.txt .
+RUN pip install --no-cache-dir -r requirements.txt
+
+# 5. Copy application code with correct ownership
+COPY --chown=user . .
+
+# Create output directories that the user can write to
+RUN mkdir -p $HOME/app/output $HOME/app/temp_output
+
+# 6. Configuration for Hugging Face Spaces
+# Spaces expect the app to listen on port 7860
+ENV PORT=7860
+EXPOSE 7860
+
+# Healthcheck to ensure the container doesn't get killed
+HEALTHCHECK --interval=30s --timeout=30s --start-period=5s --retries=3 \
+    CMD wget --no-verbose --tries=1 --spider http://localhost:7860/_stcore/health || exit 1
+
+# Set up Xvfb for headless rendering
+ENV DISPLAY=:99
+
+# 7. Run Streamlit on port 7860
+CMD ["sh", "-c", "xvfb-run -a -s '-screen 0 1024x768x24' streamlit run app.py --server.port=7860 --server.address=0.0.0.0 --server.headless=true"]

README.md

@@ -1,12 +1,418 @@
----
-title: MMIB Counterfactual Image Generation Tool
-emoji: 🏢
-colorFrom: indigo
-colorTo: red
-sdk: docker
-pinned: false
-license: mit
-short_description: Counterfactual image generation tool
----
-
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+---
+title: MMB Counterfactual Image Tool
+colorFrom: blue
+colorTo: indigo
+sdk: docker
+pinned: false
+license: mit
+arxiv: 2401.xxxxx
+---
+
+A Python-based pipeline for CLEVR-style scenes with counterfactual variants and Blender rendering. Configurable object counts, counterfactual types, and automated questions and answers.
+
+**Key Features:**
+- 17 different counterfactual types (9 image CFs + 8 negative CFs)
+- Automated Blender rendering with GPU support
+- Question-answer datasets
+- Resume support for interrupted jobs
+- Streamlit web interface
+- Examples for all counterfactual types
+
+## Hugging Face Spaces Deployment
+
+This app is configured to run on Hugging Face Spaces using Docker. The Dockerfile includes Blender installation and all necessary dependencies for scenes and rendering.
+
+## Features
+
+- **Scenes**: Multiple scene sets with configurable object counts and properties
+- **Counterfactual Variants**: Create multiple counterfactual variations per scene (color, shape, material, size changes)
+- **Blender Rendering**: Automated rendering of scenes to PNG images using Blender's Cycles engine
+- **Questions**: Counterfactual questions and answers for each scene set
+- **Resume Support**: Resume interrupted rendering jobs
+
+## Requirements
+
+### Python Dependencies
+
+Install Python dependencies using:
+
+```bash
+pip install -r requirements.txt
+```
+
+### Blender
+
+Blender must be installed separately as it's not available via pip. The scripts are designed to run inside Blender's Python environment using:
+
+```bash
+blender --background --python <script.py> -- [arguments]
+```
+
+The pipeline will attempt to auto-detect Blender on your system, or you can specify the path manually.
+
+## Installation
+
+1. Clone this repository:
+```bash
+git clone <repository-url>
+cd code
+```
+
+2. Install Python dependencies:
+```bash
+pip install -r requirements.txt
+```
+
+3. Ensure Blender is installed and accessible in your PATH, or note the path for manual specification.
+
+## Usage
+
+### Quick Start
+
+```bash
+# Install dependencies
+pip install -r requirements.txt
+
+# Generate 5 scene sets with 5 objects each
+python pipeline.py --num_scenes 5 --num_objects 5 --run_name my_first_run
+
+# Generate examples of all counterfactual types
+python scripts/generate_examples.py --render
+```
+
+### Web Interface (Streamlit)
+
+Run the Streamlit web interface for an interactive experience:
+
+```bash
+streamlit run app.py
+```
+
+The web interface provides:
+- Interactive parameter configuration
+- Real-time progress
+- Visual output preview
+- Downloadable results as ZIP files
+
+### 1. Generate and Render (Combined)
+
+Use `python pipeline.py` to generate scene JSON files and render PNG images in one step:
+
+```bash
+python pipeline.py --num_scenes 10 --num_objects 5 --run_name experiment1
+```
+
+### 2. Generate Only (Skip Rendering)
+
+Generate scenes without rendering:
+
+```bash
+python pipeline.py --num_scenes 10 --num_objects 5 --run_name experiment1 --skip_render
+```
+
+### 4. Render Existing Scenes Only
+
+Render previously generated scene JSON files:
+
+```bash
+# Render scenes from a specific run
+python pipeline.py --render_only --run_name experiment1
+
+# Auto-detect latest run
+python pipeline.py --render_only --auto_latest
+
+# Use GPU rendering
+python pipeline.py --render_only --run_name experiment1 --use_gpu 1
+```
+
+This allows you to:
+- Generate scenes on one machine, render on another
+- Generate many scenes, then render them in batches
+- Re-render scenes with different settings (GPU/CPU, samples, resolution) without regenerating
+
+### 5. Generating Scenes and Images (Full Options)
+
+#### Arguments
+
+| Argument                  | Default       | Description                                                                  |
+| ------------------------- | ------------- | ---------------------------------------------------------------------------- |
+| `--num_scenes`            | 5             | Number of scene sets to generate                                             |
+| `--num_objects`           | None          | Fixed number of objects per scene (overrides min/max)                        |
+| `--min_objects`           | 3             | Minimum object count (if `num_objects` not given)                            |
+| `--max_objects`           | 7             | Maximum object count (if `num_objects` not given)                            |
+| `--num_counterfactuals`   | 2             | Number of counterfactual variants per scene                                  |
+| `--blender_path`          | auto-detected | Path to Blender executable                                                   |
+| `--output_dir`            | `output`      | Base directory for all runs (each run gets a timestamped/named subfolder)    |
+| `--run_name`              | None          | Optional custom name for this run (creates `output/run_name/`)               |
+| `--use_gpu`               | 0             | 1 = enable GPU rendering, 0 = CPU rendering                                  |
+| `--samples`               | 512           | Cycles sampling rate (higher = better quality, slower)                       |
+| `--width`                 | 320           | Image width in pixels                                                        |
+| `--height`                | 240           | Image height in pixels                                                       |
+| `--skip_render`           | False         | Generate scenes only (JSON only, no PNG rendering)                           |
+| `--render_only`           | False         | Only render existing scene JSON files. Requires --run_dir, --run_name, or --auto_latest |
+| `--run_dir`               | None          | Run directory containing scenes/ folder (for --render_only mode)             |
+| `--auto_latest`           | False         | Automatically use the latest run in output_dir (for --render_only mode)      |
+| `--resume`                | False         | Resume from where it stopped in an existing run                              |
+| `--cf_types`              | None          | Explicitly choose which counterfactual types are used (order is respected; cycles if needed) |
+| `--same_cf_type`          | False         | Use the same counterfactual type for all variants (first in `--cf_types`, or one random if unset) |
+| `--list_cf_types`         | False         | Print available counterfactual types and exit                                |
+| `--min_cf_change_score`   | 1.0           | Minimum heuristic change score (retries CF until it’s “noticeable” enough) |
+| `--max_cf_attempts`       | 10            | Max retries per counterfactual to reach `--min_cf_change_score`               |
+
+#### Examples
+
+```bash
+# Generate 10 scene sets with 5 objects each
+python3 pipeline.py --num_scenes 10 --num_objects 5 --run_name experiment1
+
+# Generate 10 scene sets with 3-7 objects, using GPU
+python3 pipeline.py --num_scenes 10 --min_objects 3 --max_objects 7 --use_gpu 1
+
+# Resume from where it stopped
+python3 pipeline.py --num_scenes 100 --run_name experiment1 --resume
+
+# Generate scenes only (no rendering)
+python3 pipeline.py --num_scenes 10 --skip_render
+
+# List available counterfactual types
+python3 pipeline.py --list_cf_types
+
+# Force specific counterfactual types in order (CF1 then CF2)
+python3 pipeline.py --num_scenes 10 --num_counterfactuals 2 --cf_types change_color add_noise
+# All counterfactuals same type (e.g. both change_color):
+python3 pipeline.py --num_scenes 10 --num_counterfactuals 2 --cf_types change_color --same_cf_type
+
+# Make counterfactuals more noticeable (stricter threshold + more retries)
+python3 pipeline.py --num_scenes 10 --min_cf_change_score 1.5 --max_cf_attempts 25
+```
+
+#### Counterfactual Types
+
+The pipeline supports 17 different counterfactual types, divided into two categories:
+
+**Image Counterfactuals** (Should change VQA answers - 10 types):
+- `change_color` - Change the color of a random object (e.g., red → blue)
+- `change_shape` - Change the shape of a random object (cube/sphere/cylinder)
+- `change_size` - Change the size of a random object (small ↔ large)
+- `change_material` - Change the material of a random object (metal ↔ rubber)
+- `change_position` - Move a random object to a different location (with collision detection)
+- `add_object` - Add a new random object to the scene
+- `remove_object` - Remove a random object from the scene
+- `replace_object` - Replace an object with a different one (keeping position)
+- `swap_attribute` - Swap an attribute (e.g. color) between two objects
+- `relational_flip` - Move object from left of X to right of X
+
+**Negative Counterfactuals** (Should NOT change VQA answers - 8 types):
+- `change_background` - Change the background/ground color
+- `change_lighting` - Change lighting conditions (bright/dim/warm/cool/dramatic)
+- `add_noise` - Add image noise/grain (light/medium/heavy levels)
+- `occlusion_change` - Move object to partially hide another (visual only; answers unchanged)
+- `apply_fisheye` - Apply fisheye lens distortion effect
+- `apply_blur` - Apply Gaussian blur filter
+- `apply_vignette` - Apply vignette effect (edge darkening)
+- `apply_chromatic_aberration` - Apply chromatic aberration (color fringing)
+
+**Default Behavior**: If `--cf_types` is not specified, the pipeline uses a default mix of 1 image counterfactual + 1 negative counterfactual per scene.
+
+**Usage Examples**:
+```bash
+# List all available counterfactual types
+python3 pipeline.py --list_cf_types
+
+# Use specific counterfactual types (order is respected; cycles if needed)
+python3 pipeline.py --num_scenes 10 --num_counterfactuals 2 --cf_types change_color change_position
+
+# Mix image and negative counterfactuals
+python3 pipeline.py --num_scenes 10 --cf_types change_shape change_lighting add_noise
+
+# Use only negative counterfactuals
+python3 pipeline.py --num_scenes 10 --cf_types change_background add_noise apply_blur
+
+# Use only image counterfactuals
+python3 pipeline.py --num_scenes 10 --cf_types change_color change_shape change_position
+```
+
+### 2. Generating Example Counterfactuals
+
+Generate examples of all counterfactual types applied to a base scene:
+
+```bash
+# Generate scene JSON files only
+python scripts/generate_examples.py
+
+# Generate and render to images
+python scripts/generate_examples.py --render
+
+# Customize output directory and number of objects
+python scripts/generate_examples.py --render --output_dir output/my_examples --num_objects 7
+
+# Use GPU rendering
+python scripts/generate_examples.py --render --use_gpu 1
+```
+
+This creates one example of each counterfactual type in `output/counterfactual_examples/`:
+- Original scene
+- 9 image counterfactual examples
+- 8 negative counterfactual examples
+
+### 3. Generating Question Mappings
+
+Use `scripts/generate_questions_mapping.py` to create a CSV with counterfactual questions and answers.
+
+#### Arguments
+
+| Argument               | Default                            | Description                                                                      |
+| ---------------------- | ---------------------------------- | -------------------------------------------------------------------------------- |
+| `--output_dir`         | `output`                           | Run directory or base output directory                                           |
+| `--auto_latest`        | False                              | Automatically find and use the latest run in `output_dir`                        |
+| `--csv_name`           | `image_mapping_with_questions.csv` | Name of the generated CSV file                                                   |
+| `--generate_questions` | False                              | Generate questions and answers (without this flag, only outputs image filenames) |
+| `--long_format`        | False                              | Also output a long-format QA dataset CSV (one row per image-question pair)       |
+| `--long_csv_name`      | `qa_dataset.csv`                   | Filename for the long-format QA dataset CSV                                      |
+
+#### Examples
+
+```bash
+# Generate questions for a specific run
+python scripts/generate_questions_mapping.py --output_dir output/experiment1 --generate_questions
+
+# Auto-detect latest run and generate questions
+python scripts/generate_questions_mapping.py --output_dir output --auto_latest --generate_questions
+
+# Also generate a long-format QA dataset (includes correct answer labels/ids)
+python scripts/generate_questions_mapping.py --output_dir output --auto_latest --generate_questions --long_format --long_csv_name qa_dataset.csv
+```
+
+#### Ensuring counterfactual answers differ
+
+For evaluation and datasets, the **counterfactual image’s answer to its counterfactual question** should differ from the **original image’s answer to the original question**. The pipeline does this in two ways:
+
+1. **Automatic retries**  
+   When generating questions (with `--generate_questions`), the script retries up to **`MAX_CF_ANSWER_RETRIES`** (default 50) per scene. For each attempt it picks new counterfactual questions (with different randomness). It keeps a pair only when both CF1 and CF2 answers differ from the original answer (after normalizing, e.g. case and whitespace). If after all retries they still match, the scene is still included and a warning is printed.
+
+2. **CF-specific question templates**  
+   Counterfactual questions are chosen from templates that target the **changed** attribute or count, so the answer on the counterfactual image is different by design:
+   - **Count-changing CFs** (e.g. `add_object`, `remove_object`): questions like “How many objects are in the scene?” or “Are there more than N objects?” so the count/yes-no differs.
+   - **Attribute-changing CFs** (e.g. `change_color`, `change_shape`): questions about the **new** value (e.g. “How many red objects?” when an object was changed to red), so the count on the CF image differs from the original.
+
+**What you need to do:**
+
+- Run question generation **after** scenes and images exist (either as part of the pipeline with `--generate_questions`, or later on a run directory):
+
+  ```bash
+  # As part of a full run (ensures answers differ for that run’s scenes)
+  python pipeline.py --num_scenes 10 --num_objects 5 --run_name my_run --generate_questions
+
+  # Or later, on an existing run
+  python scripts/generate_questions_mapping.py --output_dir output/my_run --generate_questions
+  ```
+
+- **Optional:** To allow more attempts per scene, edit `scripts/generate_questions_mapping.py` and increase **`MAX_CF_ANSWER_RETRIES`** (e.g. from 50 to 100). No CLI flag is exposed for this.
+
+**720p dataset with different answers (distinct CF types per scene):**
+
+- Scenes use **two distinct counterfactual types** per scene (no duplicate CF type for CF1 and CF2). To generate a 720p (1280×720) set with question/answer validation and optional removal of scenes where the CF answer matches the original:
+
+  ```bash
+  python pipeline.py --num_scenes 1000 --output_dir output --run_name dataset_720p_diff --width 1280 --height 720 --semantic_only --num_counterfactuals 2 --generate_questions --filter_same_answer
+  ```
+
+- This produces `output/dataset_720p_diff/` with scene sets where CF1 and CF2 use different types, questions are validated (original + CFs), and rows where the CF image’s answer to the CF question matches the original are removed. Increase `MAX_CF_ANSWER_RETRIES` in `scripts/generate_questions_mapping.py` if you want fewer “could not find valid questions” warnings.
+
+
+## Project Structure
+
+```
+.
+├── pipeline.py                     # Main pipeline and rendering (supports --render_only)
+├── app.py                         # Streamlit web interface
+├── requirements.txt                # Python dependencies
+├── data/                           # Scene assets
+│   ├── base_scene.blend           # Base Blender scene
+│   ├── CoGenT_A.json              # Scene configuration A
+│   ├── CoGenT_B.json              # Scene configuration B
+│   ├── properties.json            # Object properties configuration
+│   ├── materials/                 # Material definitions
+│   └── shapes/                    # 3D shape definitions
+├── scripts/                        # Scripts directory
+│   ├── render.py                  # Blender rendering script (run by pipeline)
+│   ├── generate_scenes.py         # Generate scene JSON files only (alternative to --skip_render)
+│   ├── generate_examples.py       # Generate example counterfactuals
+│   └── generate_questions_mapping.py  # Generate question-answer datasets
+├── output/                         # Output directory (generated)
+│   └── counterfactual_examples/    # Example counterfactuals (from generate_examples.py)
+├── .gitignore                     # Git ignore rules
+└── README.md                      # This file
+
+**Note**: The pipeline dynamically generates temporary files during execution:
+- `render_images_patched.py` - Patched rendering script
+- `temp_output/<run_id>/` - Temporary output per run (e.g. `temp_output/2025-01-29_12-30-45/images` and `.../scenes`), so different runs use separate directories and do not overwrite each other.
+
+These files are automatically created when needed, cleaned up after use, and are ignored by git.
+```
+
+## Output Structure
+
+Each run creates a directory structure like:
+
+```
+output/
+└── <run_name_or_timestamp>/
+    ├── checkpoint.json
+    ├── run_metadata.json
+    ├── scenes/
+    │   ├── scene_0000_original.json
+    │   ├── scene_0000_cf1.json
+    │   ├── scene_0000_cf2.json
+    │   └── ...
+    ├── images/
+    │   ├── scene_0000_original.png
+    │   ├── scene_0000_cf1.png
+    │   ├── scene_0000_cf2.png
+    │   └── ...
+    ├── image_mapping_with_questions*.csv
+    └── qa_dataset*.csv (if generated with --long_format)
+```
+
+### Dataset columns (high level)
+
+**Wide Format CSV** (default with `--generate_questions`):
+- **Image columns**: `original_image`, `counterfactual1_image`, `counterfactual2_image`
+- **Question columns**: `original_question`, `counterfactual1_question`, `counterfactual2_question`
+- **Answer matrix columns** (9 total, showing each image's answer to each question):
+  - `original_image_answer_to_original_question`
+  - `original_image_answer_to_cf1_question`
+  - `original_image_answer_to_cf2_question`
+  - `cf1_image_answer_to_original_question`
+  - `cf1_image_answer_to_cf1_question`
+  - `cf1_image_answer_to_cf2_question`
+  - `cf2_image_answer_to_original_question`
+  - `cf2_image_answer_to_cf1_question`
+  - `cf2_image_answer_to_cf2_question`
+
+**Basic Format CSV** (without `--generate_questions`):
+- Only image columns: `original_image`, `counterfactual1_image`, `counterfactual2_image`
+
+## Code Style
+
+The codebase follows a clean, consistent style:
+- No multiline docstrings (removed for brevity)
+- Consistent spacing and formatting
+- Single blank lines between functions
+- Clear, concise function names
+
+## License
+
+MIT License
+
+## Contributing
+
+Contributions are welcome! Please ensure:
+- Code follows the existing style (no multiline docstrings, consistent spacing)
+- All tests pass
+- Documentation is updated as needed
+
+## Acknowledgments
+
+This project is inspired by the CLEVR dataset and uses Blender for 3D scene rendering.
+

analyze_semantic_failures.py

@@ -0,0 +1,43 @@
+import csv
+from pathlib import Path
+
+
+def main() -> None:
+    base_dir = Path(__file__).resolve().parent
+
+    rel_path = base_dir / "output" / "200samples_mmib_rel" / "image_mapping_with_questions_200_rel.csv"
+    sem_path = base_dir / "output" / "200samples_mmib_rel" / "image_mapping_with_questions_200_semantic.csv"
+
+    with rel_path.open(newline="", encoding="utf-8") as f:
+        rel_reader = csv.DictReader(f)
+        rel_rows = list(rel_reader)
+
+    with sem_path.open(newline="", encoding="utf-8") as f:
+        sem_reader = csv.DictReader(f)
+        sem_rows = list(sem_reader)
+
+    # Keys identifying a CF pair
+    def key_from_rel(row: dict) -> tuple[str, str]:
+        return row["original_image"], row["counterfactual_image"]
+
+    def key_from_sem(row: dict) -> tuple[str, str]:
+        return row["original_image"], row["counterfactual_image"]
+
+    sem_keys = {key_from_sem(r) for r in sem_rows}
+
+    missing = [r for r in rel_rows if key_from_rel(r) not in sem_keys]
+
+    print(f"Total rel rows: {len(rel_rows)}")
+    print(f"Total semantic rows: {len(sem_rows)}")
+    print(f"Missing (failed) pairs: {len(missing)}\n")
+
+    for r in missing:
+        print(
+            f"{r['original_image']} -> {r['counterfactual_image']} | "
+            f"type={r.get('counterfactual_type','')} | desc={r.get('counterfactual_description','')}"
+        )
+
+
+if __name__ == "__main__":
+    main()
+

app.py

@@ -0,0 +1,1058 @@
+import streamlit as st
+import os
+import sys
+import tempfile
+import zipfile
+import json
+import random
+import math
+import csv
+from pathlib import Path
+from datetime import datetime
+import time
+
+sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+
+script_dir = os.path.join(os.path.dirname(os.path.abspath(__file__)), 'scripts')
+sys.path.insert(0, script_dir)
+
+try:
+    from pipeline import (
+        generate_counterfactuals,
+        generate_base_scene,
+        save_scene,
+        render_scene,
+        create_patched_render_script,
+        IMAGE_COUNTERFACTUALS,
+        NEGATIVE_COUNTERFACTUALS
+    )
+    try:
+        import sys
+        script_dir = os.path.dirname(os.path.abspath(__file__))
+        scripts_path = os.path.join(script_dir, 'scripts')
+        if scripts_path not in sys.path:
+            sys.path.insert(0, scripts_path)
+        from generate_questions_mapping import (
+            load_scene,
+            generate_question_for_scene as _generate_question_for_scene_file,
+            answer_question_for_scene,
+            generate_mapping_with_questions
+        )
+    except ImportError:
+        def load_scene(scene_file):
+            with open(scene_file, 'r') as f:
+                return json.load(f)
+        def answer_question_for_scene(question, scene):
+            objects = scene.get('objects', [])
+            return len(objects)
+        _generate_question_for_scene_file = None
+        generate_mapping_with_questions = None
+    PIPELINE_AVAILABLE = True
+except ImportError as e:
+    print(f"Warning: Error importing pipeline functions: {e}")
+    PIPELINE_AVAILABLE = False
+    answer_question_for_scene = None
+    load_scene = None
+    _generate_question_for_scene_file = None
+
+st.set_page_config(
+    page_title="Counterfactual Image Generator",
+    page_icon="🎨",
+    layout="wide",
+    initial_sidebar_state="expanded"
+)
+
+st.markdown("""
+    <style>
+    .main-header {
+        font-size: 2.5rem;
+        font-weight: bold;
+        color: #1f77b4;
+        text-align: center;
+        margin-bottom: 2rem;
+    }
+    .stButton>button {
+        width: 100%;
+        height: 3.5rem;
+        font-size: 1.2rem;
+        font-weight: bold;
+        background-color: #1f77b4;
+        color: white;
+        border-radius: 0.5rem;
+    }
+    .stButton>button:hover {
+        background-color: #1565c0;
+    }
+    .info-box {
+        padding: 1rem;
+        border-radius: 0.5rem;
+        background-color: #f0f2f6;
+        margin: 1rem 0;
+    }
+    </style>
+""", unsafe_allow_html=True)
+
+def create_zip_file(output_dir, zip_path):
+    with zipfile.ZipFile(zip_path, 'w', zipfile.ZIP_DEFLATED) as zipf:
+        for root, dirs, files in os.walk(output_dir):
+            for file in files:
+                file_path = os.path.join(root, file)
+                arcname = os.path.relpath(file_path, output_dir)
+                zipf.write(file_path, arcname)
+
+
+def generate_fallback_scene(num_objects, scene_idx):
+    script_dir = os.path.dirname(os.path.abspath(__file__))
+    props_path = os.path.join(script_dir, 'data', 'properties.json')
+    
+    try:
+        with open(props_path, 'r') as f:
+            properties = json.load(f)
+    except:
+        properties = {
+            'shapes': {'cube': 'SmoothCube_v2', 'sphere': 'Sphere', 'cylinder': 'SmoothCylinder'},
+            'colors': {'gray': [87, 87, 87], 'red': [173, 35, 35], 'blue': [42, 75, 215], 
+                      'green': [29, 105, 20], 'brown': [129, 74, 25], 'purple': [129, 38, 192],
+                      'cyan': [41, 208, 208], 'yellow': [255, 238, 51]},
+            'materials': {'rubber': 'Rubber', 'metal': 'MyMetal'},
+            'sizes': {'large': 0.7, 'small': 0.35}
+        }
+    
+    shapes = list(properties['shapes'].keys())
+    colors = list(properties['colors'].keys())
+    materials = list(properties['materials'].keys())
+    sizes = list(properties['sizes'].keys())
+    
+    scene_num = scene_idx + 1
+    scene = {
+        'split': 'fallback',
+        'image_index': scene_num,
+        'image_filename': f'scene_{scene_num:04d}_original.png',
+        'objects': [],
+        'directions': {
+            'behind': (0.0, -1.0, 0.0),
+            'front': (0.0, 1.0, 0.0),
+            'left': (-1.0, 0.0, 0.0),
+            'right': (1.0, 0.0, 0.0),
+            'above': (0.0, 0.0, 1.0),
+            'below': (0.0, 0.0, -1.0)
+        }
+    }
+    
+    positions = []
+    min_dist = 0.25
+    
+    for i in range(num_objects):
+        max_attempts = 100
+        placed = False
+        
+        for attempt in range(max_attempts):
+            x = random.uniform(-3, 3)
+            y = random.uniform(-3, 3)
+            z = random.uniform(0.35, 0.7)
+            
+            collision = False
+            size = random.choice(sizes)
+            r = properties['sizes'][size]
+            
+            for (px, py, pz, pr) in positions:
+                dist = math.sqrt((x - px)**2 + (y - py)**2)
+                if dist < (r + pr + min_dist):
+                    collision = True
+                    break
+            
+            if not collision:
+                positions.append((x, y, z, r))
+                placed = True
+                break
+        
+        if not placed:
+            x = random.uniform(-3, 3)
+            y = random.uniform(-3, 3)
+            z = random.uniform(0.35, 0.7)
+            size = random.choice(sizes)
+            r = properties['sizes'][size]
+            positions.append((x, y, z, r))
+        
+        shape = random.choice(shapes)
+        color = random.choice(colors)
+        material = random.choice(materials)
+        
+        obj = {
+            'shape': shape,
+            'size': size,
+            'material': material,
+            '3d_coords': [x, y, z],
+            'rotation': random.uniform(0, 360),
+            'pixel_coords': [0, 0, 0],
+            'color': color
+        }
+        
+        scene['objects'].append(obj)
+    
+    return scene
+
+
+def generate_question_for_scene_dict(scene):
+    if _generate_question_for_scene_file is None:
+        objects = scene.get('objects', [])
+        if len(objects) == 0:
+            return "How many objects are in the scene?", {}
+        
+        colors = list(set(obj.get('color') for obj in objects if obj.get('color')))
+        shapes = list(set(obj.get('shape') for obj in objects if obj.get('shape')))
+        
+        if colors:
+            return f"How many {random.choice(colors)} objects are there?", {'color': random.choice(colors)}
+        else:
+            return "How many objects are in the scene?", {}
+    
+    with tempfile.NamedTemporaryFile(mode='w', suffix='.json', delete=False) as tmp_file:
+        json.dump(scene, tmp_file)
+        tmp_path = tmp_file.name
+    
+    try:
+        question, params = _generate_question_for_scene_file(tmp_path)
+        return question, params
+    finally:
+        try:
+            os.unlink(tmp_path)
+        except:
+            pass
+
+
+def generate_counterfactual_scenes(num_scenes, num_objects, min_objects, max_objects, num_counterfactuals, 
+                                    cf_types, same_cf_type, min_change_score, max_cf_attempts, min_noise_level,
+                                    output_dir, blender_path=None, use_gpu=0, samples=512, 
+                                    width=320, height=240, skip_render=False, generate_questions=False):
+    if not PIPELINE_AVAILABLE:
+        return {
+            'success': False,
+            'error': 'Pipeline functions not available. Please ensure pipeline.py is accessible.'
+        }
+    
+    scenes_dir = os.path.join(output_dir, 'scenes')
+    images_dir = os.path.join(output_dir, 'images')
+    os.makedirs(scenes_dir, exist_ok=True)
+    os.makedirs(images_dir, exist_ok=True)
+    
+    script_dir = os.path.dirname(os.path.abspath(__file__))
+    cwd = os.getcwd()
+    import shutil
+    import time
+    
+    temp_output_dir = os.path.join(cwd, 'temp_output')
+    if os.path.exists(temp_output_dir):
+        for attempt in range(3):
+            try:
+                shutil.rmtree(temp_output_dir)
+                break
+            except Exception as e:
+                if attempt < 2:
+                    time.sleep(0.3)
+                else:
+                    print(f"Warning: Could not remove temp_output after 3 attempts: {e}")
+    
+    render_patched_path = os.path.join(cwd, 'render_images_patched.py')
+    if os.path.exists(render_patched_path):
+        for attempt in range(3):
+            try:
+                time.sleep(0.2)
+                if os.path.exists(render_patched_path):
+                    os.remove(render_patched_path)
+                break
+            except Exception as e:
+                if attempt < 2:
+                    time.sleep(0.3)
+                else:
+                    print(f"Warning: Could not remove render_images_patched.py after 3 attempts: {e}")
+    
+    blender_available = False
+    if blender_path is None:
+        try:
+            from pipeline import find_blender
+            blender_path = find_blender()
+        except:
+            blender_path = 'blender'
+    
+    if blender_path and blender_path != 'blender':
+        blender_available = os.path.exists(blender_path)
+    else:
+        try:
+            import subprocess
+            test_path = blender_path if blender_path and blender_path != 'blender' else 'blender'
+            env = os.environ.copy()
+            result = subprocess.run([test_path, '--version'], capture_output=True, timeout=5, env=env)
+            blender_available = (result.returncode == 0)
+        except:
+            blender_available = False
+    
+    successful_scenes = 0
+    successful_renders = 0
+    error_messages = []
+    
+    try:
+        for scene_idx in range(num_scenes):
+            if num_objects is not None:
+                scene_num_objects = num_objects
+            else:
+                scene_num_objects = random.randint(min_objects, max_objects)
+            
+            base_scene = None
+            
+            if blender_available:
+                scene_error = None
+                for retry in range(3):
+                    try:
+                        import io
+                        import contextlib
+                        output_buffer = io.StringIO()
+                        with contextlib.redirect_stdout(output_buffer), contextlib.redirect_stderr(output_buffer):
+                            base_scene = generate_base_scene(
+                                scene_num_objects,
+                                blender_path,
+                                scene_idx
+                            )
+                        blender_output = output_buffer.getvalue()
+                        if blender_output and retry == 2:
+                            st.text(f"Blender output for scene {scene_idx + 1} (last 1000 chars):")
+                            st.code(blender_output[-1000:] if len(blender_output) > 1000 else blender_output)
+                        
+                        if base_scene and len(base_scene.get('objects', [])) > 0:
+                            break
+                        elif base_scene is None:
+                            if retry == 2:
+                                scene_error = f"generate_base_scene returned None - Blender may have failed (check output above)"
+                                error_messages.append(f"Scene {scene_idx + 1}: {scene_error}")
+                        elif len(base_scene.get('objects', [])) == 0:
+                            if retry == 2:
+                                scene_error = f"Scene has 0 objects - Blender may have hit max_retries (check output above)"
+                                error_messages.append(f"Scene {scene_idx + 1}: {scene_error}")
+                    except FileNotFoundError as e:
+                        scene_error = f"Blender not found: {e}"
+                        error_messages.append(f"Scene {scene_idx + 1}: {scene_error}")
+                        blender_available = False
+                        break
+                    except Exception as e:
+                        import traceback
+                        scene_error = f"Error generating base scene: {str(e)}"
+                        print(f"Error generating base scene (retry {retry + 1}/3): {e}")
+                        print(f"  Traceback: {traceback.format_exc()}")
+                        if retry == 2:
+                            full_error = f"Scene {scene_idx + 1}: {scene_error} (Blender path: {blender_path})"
+                            error_messages.append(full_error)
+                            blender_available = False
+                            continue
+            else:
+                print(f"Scene {scene_idx + 1} (Blender not available)...")
+                base_scene = generate_fallback_scene(scene_num_objects, scene_idx)
+            
+            if not base_scene or len(base_scene.get('objects', [])) == 0:
+                error_detail = f"Scene {scene_idx + 1}: Failed to generate"
+                if blender_available:
+                    error_detail += f" (Blender was available at {blender_path} but returned empty scene)"
+                else:
+                    error_detail += " (Blender not available, fallback scene also failed)"
+                print(f"Failed to generate scene {scene_idx + 1}")
+                print(f"  Blender available: {blender_available}")
+                print(f"  Blender path: {blender_path}")
+                print(f"  Base scene: {base_scene is not None}")
+                if base_scene:
+                    print(f"  Objects in scene: {len(base_scene.get('objects', []))}")
+                error_messages.append(error_detail)
+                continue
+            
+            successful_scenes += 1
+            
+            counterfactuals = generate_counterfactuals(
+                base_scene,
+                num_counterfactuals=num_counterfactuals,
+                cf_types=cf_types,
+                same_cf_type=same_cf_type,
+                min_change_score=min_change_score,
+                max_cf_attempts=max_cf_attempts,
+                min_noise_level='light',
+                semantic_only=semantic_only,
+                negative_only=negative_only
+            )
+            
+            scene_num = scene_idx + 1
+            scene_prefix = f"scene_{scene_num:04d}"
+            
+            base_scene['cf_metadata'] = {
+                'variant': 'original',
+                'is_counterfactual': False,
+                'cf_index': None,
+                'cf_category': 'original',
+                'cf_type': None,
+                'cf_description': None,
+                'source_scene': scene_prefix,
+            }
+            original_scene_path = os.path.join(scenes_dir, f"{scene_prefix}_original.json")
+            save_scene(base_scene, original_scene_path)
+            
+            for idx, cf in enumerate(counterfactuals):
+                cf_name = f"cf{idx+1}"
+                cf_scene = cf['scene']
+                cf_scene['cf_metadata'] = {
+                    'variant': cf_name,
+                    'is_counterfactual': True,
+                    'cf_index': idx + 1,
+                    'cf_category': cf.get('cf_category', 'unknown'),
+                    'cf_type': cf.get('type', None),
+                    'cf_description': cf.get('description', None),
+                    'change_score': cf.get('change_score', None),
+                    'change_attempts': cf.get('change_attempts', None),
+                    'source_scene': scene_prefix,
+                }
+                cf_scene_path = os.path.join(scenes_dir, f"{scene_prefix}_{cf_name}.json")
+                save_scene(cf_scene, cf_scene_path)
+            
+            render_success = 0
+            total_to_render = len(counterfactuals) + 1
+            
+            if not skip_render:
+                if blender_path and blender_available:
+                    original_image_path = os.path.join(images_dir, f"{scene_prefix}_original.png")
+                    if render_scene(
+                        blender_path,
+                        original_scene_path,
+                        original_image_path,
+                        use_gpu=use_gpu,
+                        samples=samples,
+                        width=width,
+                        height=height
+                    ):
+                        render_success += 1
+                    
+                    for idx, cf in enumerate(counterfactuals):
+                        cf_name = f"cf{idx+1}"
+                        cf_scene_path = os.path.join(scenes_dir, f"{scene_prefix}_{cf_name}.json")
+                        cf_image_path = os.path.join(images_dir, f"{scene_prefix}_{cf_name}.png")
+                        
+                        if render_scene(
+                            blender_path,
+                            cf_scene_path,
+                            cf_image_path,
+                            use_gpu=use_gpu,
+                            samples=samples,
+                            width=width,
+                            height=height
+                        ):
+                            render_success += 1
+                    
+                    if render_success == total_to_render:
+                        successful_renders += 1
+                else:
+                    print("Blender not available - skipping image rendering. Scene JSON files will still be generated.")
+        
+        csv_filename = 'image_mapping_with_questions.csv' if generate_questions else 'image_mapping.csv'
+        csv_path = os.path.join(output_dir, csv_filename)
+        
+        try:
+            if generate_mapping_with_questions is not None:
+                generate_mapping_with_questions(
+                    run_dir=output_dir,
+                    csv_filename=csv_filename,
+                    generate_questions=generate_questions,
+                    with_links=False,
+                    strict_question_validation=True
+                )
+                csv_created = os.path.exists(csv_path)
+            else:
+                csv_created = False
+        except Exception:
+            import traceback
+            traceback.print_exc()
+            csv_created = False
+        
+        scene_files = list(Path(scenes_dir).glob("*.json")) if os.path.exists(scenes_dir) else []
+        image_files = list(Path(images_dir).glob("*.png")) if os.path.exists(images_dir) else []
+        
+        statistics = {
+            'scenes_generated': successful_scenes,
+            'scenes_rendered': successful_renders,
+            'total_scene_files': len(scene_files),
+            'total_image_files': len(image_files),
+            'num_counterfactuals': num_counterfactuals,
+            'cf_types_used': cf_types if cf_types else 'default',
+            'csv_created': csv_created,
+            'csv_path': csv_path if csv_created else None
+        }
+        
+        script_dir = os.path.dirname(os.path.abspath(__file__))
+        cwd = os.getcwd()
+        import shutil
+        import time
+        
+        temp_output_dir = os.path.join(cwd, 'temp_output')
+        if os.path.exists(temp_output_dir):
+            for attempt in range(3):
+                try:
+                    shutil.rmtree(temp_output_dir)
+                    break
+                except Exception as e:
+                    if attempt < 2:
+                        time.sleep(0.3)
+                    else:
+                        print(f"Warning: Could not remove temp_output after 3 attempts: {e}")
+        
+        render_patched_path = os.path.join(cwd, 'render_images_patched.py')
+        if os.path.exists(render_patched_path):
+            for attempt in range(3):
+                try:
+                    time.sleep(0.2)
+                    if os.path.exists(render_patched_path):
+                        os.remove(render_patched_path)
+                    break
+                except Exception as e:
+                    if attempt < 2:
+                        time.sleep(0.3)
+                    else:
+                        print(f"Warning: Could not remove render_images_patched.py after 3 attempts: {e}")
+        
+        if successful_scenes == 0 and error_messages:
+            error_summary = "Scenes failed. Common reasons:\n"
+            error_summary += "- Blender is not installed or not in PATH\n"
+            error_summary += "- Blender executable not found\n"
+            error_summary += f"\nFirst error: {error_messages[0] if error_messages else 'Unknown error'}"
+            
+            return {
+                'success': False,
+                'error': error_summary,
+                'num_scenes': successful_scenes,
+                'output_dir': output_dir,
+                'error_messages': error_messages
+            }
+        
+        return {
+            'success': True,
+            'num_scenes': successful_scenes,
+            'output_dir': output_dir,
+            'statistics': statistics,
+            'error_messages': error_messages if error_messages else None
+        }
+    
+    except Exception as e:
+        import traceback
+        error_msg = f"Error: {str(e)}\n{traceback.format_exc()}"
+        print(error_msg)
+        return {
+            'success': False,
+            'error': error_msg,
+            'num_scenes': successful_scenes,
+            'output_dir': output_dir,
+            'error_messages': error_messages if 'error_messages' in locals() else []
+        }
+
+def main():
+    st.markdown('<p class="main-header">Counterfactual Image Generator</p>', unsafe_allow_html=True)
+    
+    if 'output_dir' not in st.session_state:
+        st.session_state.output_dir = None
+    
+    if 'generation_complete' not in st.session_state:
+        st.session_state.generation_complete = False
+    
+    with st.sidebar:
+        st.header("Configuration")
+        
+        st.subheader("Scene Settings")
+        num_scenes = st.number_input(
+            "Number of Scenes",
+            min_value=1,
+            max_value=10000,
+            value=5,
+            help="Number of scene sets to generate"
+        )
+        
+        use_fixed_objects = st.checkbox("Use Fixed Number of Objects", value=True)
+        
+        if use_fixed_objects:
+            num_objects = st.number_input(
+                "Number of Objects per Scene",
+                min_value=1,
+                max_value=15,
+                value=5,
+                help="Fixed number of objects per scene"
+            )
+            min_objects = None
+            max_objects = None
+        else:
+            num_objects = None
+            min_objects = st.number_input(
+                "Min Objects per Scene",
+                min_value=1,
+                max_value=15,
+                value=3,
+                help="Minimum objects per scene"
+            )
+            max_objects = st.number_input(
+                "Max Objects per Scene",
+                min_value=1,
+                max_value=15,
+                value=7,
+                help="Maximum objects per scene"
+            )
+            if min_objects > max_objects:
+                st.error("Min objects must be <= Max objects")
+                return
+        
+        st.subheader("Counterfactual Settings")
+        num_counterfactuals = st.number_input(
+            "Number of Counterfactuals",
+            min_value=1,
+            max_value=10,
+            value=2,
+            help="Number of counterfactual variants per scene"
+        )
+        
+        st.markdown("**Counterfactual Types**")
+        st.caption("Leave all unchecked to use default behavior (1 Image CF + 1 Negative CF)")
+        semantic_only = st.checkbox(
+            "Semantic only",
+            value=False,
+            help="Generate only Semantic/Image counterfactuals (Change Color, Add Object, etc.); no Negative CFs"
+        )
+        negative_only = st.checkbox(
+            "Negative only",
+            value=False,
+            help="Generate only Negative counterfactuals (Change Lighting, Add Noise, Occlusion Change, etc.); no Semantic CFs"
+        )
+        same_cf_type = st.checkbox(
+            "Same CF type for all",
+            value=False,
+            help="Use the same counterfactual type for every variant (first selected type, or one random if none selected)"
+        )
+        with st.expander("Image CFs (change answers)", expanded=True):
+            use_change_color = st.checkbox("Change Color", value=False)
+            use_change_shape = st.checkbox("Change Shape", value=False)
+            use_change_size = st.checkbox("Change Size", value=False)
+            use_change_material = st.checkbox("Change Material", value=False)
+            use_change_position = st.checkbox("Change Position", value=False)
+            use_add_object = st.checkbox("Add Object", value=False)
+            use_remove_object = st.checkbox("Remove Object", value=False)
+            use_replace_object = st.checkbox("Replace Object", value=False)
+            use_swap_attribute = st.checkbox("Swap Attribute", value=False)
+            use_relational_flip = st.checkbox("Relational Flip", value=False)
+        
+        with st.expander("Negative CFs (don't change answers)", expanded=False):
+            use_change_background = st.checkbox("Change Background", value=False)
+            use_change_lighting = st.checkbox("Change Lighting", value=False)
+            use_add_noise = st.checkbox("Add Noise", value=False)
+            use_occlusion_change = st.checkbox("Occlusion Change", value=False)
+            use_apply_fisheye = st.checkbox("Apply Fisheye", value=False)
+            use_apply_blur = st.checkbox("Apply Blur", value=False)
+            use_apply_vignette = st.checkbox("Apply Vignette", value=False)
+            use_apply_chromatic_aberration = st.checkbox("Apply Chromatic Aberration", value=False)
+        
+        with st.expander("Advanced Settings", expanded=False):
+            min_change_score = st.slider(
+                "Minimum Change Score",
+                min_value=0.5,
+                max_value=5.0,
+                value=1.0,
+                step=0.1,
+                help="Minimum heuristic change score for counterfactuals"
+            )
+            
+            max_cf_attempts = st.number_input(
+                "Max CF Attempts",
+                min_value=1,
+                max_value=50,
+                value=10,
+                help="Maximum retries per counterfactual"
+            )
+            
+            min_noise_level = st.selectbox(
+                "Min Noise Level (for add_noise CF)",
+                options=['light', 'medium', 'heavy'],
+                index=0,
+                help="Minimum noise level when using add_noise counterfactual"
+            )
+            
+            st.markdown("---")
+            st.markdown("**Rendering Settings**")
+            
+            use_gpu = st.checkbox("Use GPU Rendering", value=False)
+            use_gpu_int = 1 if use_gpu else 0
+            
+            samples = st.number_input(
+                "Render Samples",
+                min_value=64,
+                max_value=2048,
+                value=512,
+                step=64,
+                help="Cycles sampling rate (higher = better quality, slower)"
+            )
+            
+            image_width = st.number_input(
+                "Image Width",
+                min_value=160,
+                max_value=1920,
+                value=320,
+                step=80
+            )
+            
+            image_height = st.number_input(
+                "Image Height",
+                min_value=120,
+                max_value=1080,
+                value=240,
+                step=60
+            )
+        
+        st.markdown("**CSV Options**")
+        generate_questions = st.checkbox(
+            "Generate Questions in CSV",
+            value=False,
+            help="Include question and answer columns in the CSV file"
+        )
+        
+        cf_types = []
+        if use_change_color:
+            cf_types.append('change_color')
+        if use_change_shape:
+            cf_types.append('change_shape')
+        if use_change_size:
+            cf_types.append('change_size')
+        if use_change_material:
+            cf_types.append('change_material')
+        if use_change_position:
+            cf_types.append('change_position')
+        if use_add_object:
+            cf_types.append('add_object')
+        if use_remove_object:
+            cf_types.append('remove_object')
+        if use_replace_object:
+            cf_types.append('replace_object')
+        if use_swap_attribute:
+            cf_types.append('swap_attribute')
+        if use_relational_flip:
+            cf_types.append('relational_flip')
+        if use_change_background:
+            cf_types.append('change_background')
+        if use_change_lighting:
+            cf_types.append('change_lighting')
+        if use_add_noise:
+            cf_types.append('add_noise')
+        if use_occlusion_change:
+            cf_types.append('occlusion_change')
+        if use_apply_fisheye:
+            cf_types.append('apply_fisheye')
+        if use_apply_blur:
+            cf_types.append('apply_blur')
+        if use_apply_vignette:
+            cf_types.append('apply_vignette')
+        if use_apply_chromatic_aberration:
+            cf_types.append('apply_chromatic_aberration')
+        
+        if not cf_types:
+            cf_types = None
+    
+    col1, col2 = st.columns([2, 1])
+    
+    with col1:
+        st.header("Generate Counterfactual Images")
+        
+        if st.button("Generate Counterfactual", use_container_width=True, key="generate_button"):
+            st.session_state.generation_complete = False
+            st.session_state.generating = True
+            
+            if num_scenes < 1:
+                st.error("Please specify at least 1 scene to generate.")
+                return
+            
+            if use_fixed_objects and num_objects < 1:
+                st.error("Please specify at least 1 object per scene.")
+                return
+            if not use_fixed_objects and (min_objects < 1 or max_objects < 1 or min_objects > max_objects):
+                st.error("Invalid min/max objects configuration.")
+                return
+            
+            if os.path.exists('/tmp'):
+                base_dir = '/tmp'
+            else:
+                base_dir = tempfile.gettempdir()
+            
+            timestamp = datetime.now().strftime("%Y%m%d_%H%M%S")
+            output_dir = os.path.join(base_dir, f"counterfactual_output_{timestamp}")
+            os.makedirs(output_dir, exist_ok=True)
+            st.session_state.output_dir = output_dir
+            
+            import shutil
+            import time
+            script_dir = os.path.dirname(os.path.abspath(__file__))
+            cwd = os.getcwd()
+            
+            temp_output_dir = os.path.join(cwd, 'temp_output')
+            if os.path.exists(temp_output_dir):
+                for attempt in range(3):
+                    try:
+                        shutil.rmtree(temp_output_dir)
+                        break
+                    except Exception as e:
+                        if attempt < 2:
+                            time.sleep(0.3)
+                        else:
+                            print(f"Warning: Could not remove temp_output after 3 attempts: {e}")
+            
+            render_patched_path = os.path.join(cwd, 'render_images_patched.py')
+            if os.path.exists(render_patched_path):
+                for attempt in range(3):
+                    try:
+                        time.sleep(0.2)
+                        if os.path.exists(render_patched_path):
+                            os.remove(render_patched_path)
+                        break
+                    except Exception as e:
+                        if attempt < 2:
+                            time.sleep(0.3)
+                        else:
+                            print(f"Warning: Could not remove render_images_patched.py after 3 attempts: {e}")
+            
+            try:
+                from pipeline import create_patched_render_script
+                create_patched_render_script()
+            except Exception as e:
+                st.warning(f"Could not create patched render script: {e}")
+            
+            params = {
+                'num_scenes': num_scenes,
+                'num_objects': num_objects,
+                'num_counterfactuals': num_counterfactuals,
+                'cf_types': cf_types if cf_types else None,
+                'same_cf_type': same_cf_type,
+                'min_change_score': min_change_score,
+                'max_cf_attempts': max_cf_attempts,
+                'width': image_width,
+                'height': image_height,
+                'output_dir': output_dir
+            }
+            
+            progress_bar = st.progress(0)
+            status_text = st.empty()
+            
+            try:
+                if not PIPELINE_AVAILABLE:
+                    st.error("Pipeline functions are not available. Please check your installation.")
+                    return
+                
+                status_text.text("Initializing generator...")
+                progress_bar.progress(10)
+                
+                if use_fixed_objects:
+                    status_text.text(f"Generating {num_scenes} scenes with {num_objects} objects each...")
+                else:
+                    status_text.text(f"Generating {num_scenes} scenes with {min_objects}-{max_objects} objects each...")
+                progress_bar.progress(30)
+                
+                result = generate_counterfactual_scenes(
+                    num_scenes=num_scenes,
+                    num_objects=num_objects,
+                    min_objects=min_objects,
+                    max_objects=max_objects,
+                    num_counterfactuals=num_counterfactuals,
+                    cf_types=cf_types,
+                    same_cf_type=same_cf_type,
+                    min_change_score=min_change_score,
+                    max_cf_attempts=max_cf_attempts,
+                    min_noise_level=min_noise_level,
+                    output_dir=output_dir,
+                    use_gpu=use_gpu_int,
+                    samples=samples,
+                    width=image_width,
+                    height=image_height,
+                    skip_render=False,
+                    generate_questions=generate_questions
+                )
+                
+                progress_bar.progress(80)
+                status_text.text("Preparing output...")
+                
+                if result and result.get('success', False):
+                    num_scenes_generated = result.get('num_scenes', 0)
+                    
+                    if num_scenes_generated == 0:
+                        st.warning("No scenes were created. Blender is required and is not available in this environment.")
+                        st.info("**To use this application:**\n"
+                               "1. Run it locally with Blender installed\n"
+                               "2. Use the command-line `pipeline.py` script\n"
+                               "3. Install Blender and ensure it's in your system PATH")
+                        st.session_state.generation_complete = False
+                    else:
+                        st.session_state.generation_complete = True
+                        progress_bar.progress(100)
+                        status_text.text("Done.")
+                        
+                        st.success(f"Successfully generated {num_scenes_generated} scene sets!")
+                        st.info(f"Output directory: {output_dir}")
+                        
+                        if 'statistics' in result and result['statistics'].get('csv_created'):
+                            csv_path = result['statistics'].get('csv_path')
+                            if csv_path:
+                                st.success(f"CSV file created: `{os.path.basename(csv_path)}`")
+                    
+                    if 'statistics' in result:
+                        stats = result['statistics']
+                        st.json(stats)
+                else:
+                    error_msg = result.get('error', 'Unknown error occurred') if result else 'Failed'
+                    st.error(f"Generation failed: {error_msg}")
+                    
+                    if 'blender' in error_msg.lower() or 'Blender' in error_msg or result.get('num_scenes', 0) == 0:
+                        st.warning("**Important:** This application requires Blender to generate scenes. Blender is not available on Hugging Face Spaces.")
+                        st.info("**To use this application:**\n"
+                               "1. Run it locally with Blender installed\n"
+                               "2. Use the command-line `pipeline.py` script\n"
+                               "3. Install Blender and ensure it's in your system PATH")
+                    
+                    st.session_state.generation_complete = False
+                    st.session_state.generating = False
+                    
+            except Exception as e:
+                st.error(f"Error during generation: {str(e)}")
+                st.exception(e)
+                st.session_state.generation_complete = False
+                st.session_state.generating = False
+                progress_bar.progress(0)
+                status_text.text("Failed")
+    
+    with col2:
+        st.header("Output")
+        
+        if st.session_state.generation_complete and st.session_state.output_dir:
+            output_dir = st.session_state.output_dir
+            
+            if os.path.exists(output_dir):
+                images_dir = os.path.join(output_dir, 'images')
+                scenes_dir = os.path.join(output_dir, 'scenes')
+                
+                scene_files = list(Path(scenes_dir).glob("*.json")) if os.path.exists(scenes_dir) else []
+                image_files = list(Path(images_dir).glob("*.png")) if os.path.exists(images_dir) else []
+                csv_files = list(Path(output_dir).rglob("*.csv"))
+                
+                st.success("Complete!")
+                st.metric("Scene Files", len(scene_files))
+                st.metric("CSV Files", len(csv_files))
+                st.metric("Image Files", len(image_files))
+                
+                if image_files:
+                    st.markdown("---")
+                    st.subheader("Generated Images")
+                    
+                    def get_counterfactual_type_from_scene(scene_file):
+                        try:
+                            with open(scene_file, 'r') as f:
+                                scene_data = json.load(f)
+                                cf_metadata = scene_data.get('cf_metadata', {})
+                                cf_type = cf_metadata.get('cf_type', '')
+                                if cf_type:
+                                    return cf_type.replace('_', ' ').title()
+                        except Exception as e:
+                            pass
+                        return "Counterfactual"
+                    
+                    scene_sets = {}
+                    for img_file in image_files:
+                        filename = img_file.name
+                        if filename.startswith('scene_'):
+                            parts = filename.replace('.png', '').split('_')
+                            if len(parts) >= 3:
+                                scene_num = parts[1]
+                                scene_type = parts[2]
+                                
+                                if scene_num not in scene_sets:
+                                    scene_sets[scene_num] = {}
+                                
+                                scene_sets[scene_num][scene_type] = {
+                                    'image_path': str(img_file),
+                                    'filename': filename
+                                }
+                    
+                    sorted_scenes = sorted(scene_sets.keys())[:3]
+                    
+                    for scene_idx, scene_num in enumerate(sorted_scenes):
+                        scene_data = scene_sets[scene_num]
+                        
+                        if 'original' not in scene_data:
+                            continue
+                        
+                        st.markdown(f"### Scene {scene_num}")
+                        
+                        cols = st.columns(3)
+                        
+                        with cols[0]:
+                            original = scene_data['original']
+                            st.image(original['image_path'], use_container_width=True, caption="Original")
+                        
+                        cf_count = 0
+                        for cf_key in ['cf1', 'cf2']:
+                            if cf_key in scene_data and cf_count < 2:
+                                cf_data = scene_data[cf_key]
+                                cf_scene_file = os.path.join(scenes_dir, cf_data['filename'].replace('.png', '.json'))
+                                cf_type = get_counterfactual_type_from_scene(cf_scene_file) if os.path.exists(cf_scene_file) else f"Counterfactual {cf_count + 1}"
+                                
+                                with cols[cf_count + 1]:
+                                    st.image(cf_data['image_path'], use_container_width=True, caption=cf_type)
+                                
+                                cf_count += 1
+                        
+                        if scene_idx < len(sorted_scenes) - 1:
+                            st.markdown("---")
+                
+                st.markdown("---")
+                st.subheader("Download Output")
+                
+                zip_filename = f"counterfactual_output_{datetime.now().strftime('%Y%m%d_%H%M%S')}.zip"
+                zip_path = os.path.join(tempfile.gettempdir(), zip_filename)
+                
+                try:
+                    create_zip_file(output_dir, zip_path)
+                    
+                    file_size = os.path.getsize(zip_path) / (1024 * 1024)
+                    
+                    with open(zip_path, 'rb') as f:
+                        st.download_button(
+                            label=f"Download as ZIP ({file_size:.2f} MB)",
+                            data=f.read(),
+                            file_name=zip_filename,
+                            mime="application/zip",
+                            use_container_width=True
+                        )
+                    
+                    with st.expander("Output Structure"):
+                        st.text(f"Output directory: {output_dir}")
+                        if scene_files:
+                            st.text(f"\nScene files: {len(scene_files)}")
+                            st.text("Sample files:")
+                            for f in scene_files[:5]:
+                                st.text(f"  - {f.name}")
+                        if csv_files:
+                            st.text(f"\nCSV files: {len(csv_files)}")
+                            for f in csv_files:
+                                st.text(f"  - {f.name}")
+                        if image_files:
+                            st.text(f"\nImage files: {len(image_files)}")
+                            st.text("Sample files:")
+                            for f in image_files[:5]:
+                                st.text(f"  - {f.name}")
+                
+                except Exception as e:
+                    st.error(f"Error creating zip file: {str(e)}")
+            else:
+                st.warning("Output directory not found.")
+        else:
+            st.info("Configure parameters and click 'Generate Counterfactual' to start.")
+    
+    st.markdown("---")
+    st.markdown(
+        "<div style='text-align: center; color: #666; padding: 1rem;'>"
+        "Counterfactual Image Tool | Built with Streamlit"
+        "</div>",
+        unsafe_allow_html=True
+    )
+
+if __name__ == "__main__":
+    main()
+

data/CoGenT_A.json

@@ -0,0 +1,11 @@
+{
+  "cube": [
+    "gray", "blue", "brown", "yellow"
+  ],
+  "cylinder": [
+    "red", "green", "purple", "cyan"
+  ],
+  "sphere": [
+    "gray", "red", "blue", "green", "brown", "purple", "cyan", "yellow"
+  ]
+}

data/CoGenT_B.json

@@ -0,0 +1,11 @@
+{
+  "cube": [
+    "red", "green", "purple", "cyan"
+  ],
+  "cylinder": [
+    "gray", "blue", "brown", "yellow"
+  ],
+  "sphere": [
+    "gray", "red", "blue", "green", "brown", "purple", "cyan", "yellow"  
+  ]
+}

data/base_scene.blend

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

data/materials/MyMetal.blend

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

data/materials/Rubber.blend

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

data/properties.json

@@ -0,0 +1,25 @@
+{
+  "shapes": {
+    "cube": "SmoothCube_v2",
+    "sphere": "Sphere",
+    "cylinder": "SmoothCylinder"
+  },
+  "colors": {
+    "gray": [87, 87, 87],
+    "red": [173, 35, 35],
+    "blue": [42, 75, 215],
+    "green": [29, 105, 20],
+    "brown": [129, 74, 25],
+    "purple": [129, 38, 192],
+    "cyan": [41, 208, 208],
+    "yellow": [255, 238, 51]
+  },
+  "materials": {
+    "rubber": "Rubber",
+    "metal": "MyMetal"
+  },
+  "sizes": {
+    "large": 0.7,
+    "small": 0.35
+  }
+}

data/shapes/SmoothCube_v2.blend

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

data/shapes/SmoothCylinder.blend

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

data/shapes/Sphere.blend

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

docker-compose.yml

@@ -0,0 +1,26 @@
+version: '3.8'
+
+services:
+  streamlit-app:
+    build:
+      context: .
+      dockerfile: Dockerfile
+    container_name: counterfactual-generator
+    ports:
+      - "8501:8501"
+    volumes:
+      # Mount data directory if needed
+      - ./data:/app/data:ro
+      # Mount output directory for persistence
+      - ./output:/app/output
+      # Mount temp output directory
+      - ./temp_output:/app/temp_output
+    environment:
+      - PYTHONUNBUFFERED=1
+    restart: unless-stopped
+    healthcheck:
+      test: ["CMD", "python", "-c", "import streamlit; print('OK')"]
+      interval: 30s
+      timeout: 10s
+      retries: 3
+      start_period: 40s

generate_semantic_semibalanced_200.py

@@ -0,0 +1,63 @@
+import csv
+import os
+from pathlib import Path
+
+
+def main() -> None:
+    base_dir = Path(__file__).resolve().parent
+
+    # Input mapping file (question mapping)
+    mapping_path = base_dir / "output" / "200samples_mmib_rel" / "image_mapping_with_questions_200_rel.csv"
+
+    # Output directory and file for the semantic semibalanced 200 subset
+    out_dir = base_dir / "output" / "semantic_semibalanced_200"
+    out_dir.mkdir(parents=True, exist_ok=True)
+    out_csv = out_dir / "balanced_benchmark_200_semantic.csv"
+
+    if not mapping_path.is_file():
+        raise FileNotFoundError(f"Mapping CSV not found at {mapping_path}")
+
+    with mapping_path.open(newline="", encoding="utf-8") as f_in:
+        reader = csv.DictReader(f_in)
+        rows = list(reader)
+        fieldnames = reader.fieldnames
+
+    if fieldnames is None:
+        raise ValueError("No header found in mapping CSV.")
+
+    # We require that the original question's answer on the base image
+    # differs from the answer to the same (original) question on the cf1 image.
+    # Also drop rows where either of these answers is unknown.
+    required_cols = [
+        "original_image_answer_to_original_question",
+        "cf_image_answer_to_original_question",
+    ]
+    for col in required_cols:
+        if col not in fieldnames:
+            raise KeyError(f"Expected column '{col}' not found in mapping CSV.")
+
+    filtered_rows = []
+    for row in rows:
+        base_ans = row["original_image_answer_to_original_question"]
+        cf1_ans = row["cf_image_answer_to_original_question"]
+
+        if base_ans.lower() == "unknown" or cf1_ans.lower() == "unknown":
+            continue
+
+        if base_ans != cf1_ans:
+            filtered_rows.append(row)
+
+    with out_csv.open("w", newline="", encoding="utf-8") as f_out:
+        writer = csv.DictWriter(f_out, fieldnames=fieldnames)
+        writer.writeheader()
+        writer.writerows(filtered_rows)
+
+    print(
+        f"Wrote {len(filtered_rows)} rows (from {len(rows)}) "
+        f"to {out_csv.relative_to(base_dir)}"
+    )
+
+
+if __name__ == "__main__":
+    main()
+

pipeline.py

@@ -0,0 +1,2200 @@
+#!/usr/bin/env python3
+
+import json
+import argparse
+import os
+import subprocess
+import csv
+import random
+import copy
+import sys
+import shutil
+import time
+import math
+import glob
+import zipfile
+from datetime import datetime
+from pathlib import Path
+
+script_dir = os.path.dirname(os.path.abspath(__file__))
+sys.path.insert(0, os.path.join(script_dir, 'scripts'))
+try:
+    from generate_questions_mapping import generate_mapping_with_questions
+except ImportError:
+    generate_mapping_with_questions = None
+
+def find_blender():
+    hf_paths = [
+        '/opt/blender/blender',
+        '/usr/local/bin/blender',
+    ]
+    
+    home = os.environ.get('HOME', os.path.expanduser('~'))
+    user_blender_paths = [
+        os.path.join(home, 'blender', 'blender'),
+        os.path.join(home, '.local', 'bin', 'blender'),
+    ]
+    hf_paths.extend(user_blender_paths)
+    
+    for path in hf_paths:
+        if os.path.exists(path):
+            return path
+    
+    if sys.platform == 'win32':
+        common_paths = [
+            r"C:\Program Files\Blender Foundation\Blender 4.5\blender.exe",
+            r"C:\Program Files\Blender Foundation\Blender 4.3\blender.exe",
+            r"C:\Program Files\Blender Foundation\Blender 4.2\blender.exe",
+        ]
+        for path in common_paths:
+            if os.path.exists(path):
+                return path
+    
+    try:
+        env = os.environ.copy()
+        result = subprocess.run(['which', 'blender'], capture_output=True, timeout=5, env=env)
+        if result.returncode == 0:
+            blender_path = result.stdout.decode().strip()
+            if blender_path and os.path.exists(blender_path):
+                return blender_path
+    except:
+        pass
+    
+    home = os.environ.get('HOME', os.path.expanduser('~'))
+    blender_default = os.path.join(home, 'blender', 'blender')
+    if os.path.exists(blender_default):
+        return blender_default
+    
+    return 'blender'
+    
+
+def create_run_directory(base_output_dir, run_name=None):
+    if run_name:
+        run_name = "".join(c for c in run_name if c.isalnum() or c in ('_', '-'))
+        run_dir = os.path.join(base_output_dir, run_name)
+    else:
+        timestamp = datetime.now().strftime('%Y%m%d_%H%M%S')
+        run_dir = os.path.join(base_output_dir, timestamp)
+    
+    os.makedirs(run_dir, exist_ok=True)
+    return run_dir
+
+def save_checkpoint(checkpoint_file, completed_scenes):
+    with open(checkpoint_file, 'w') as f:
+        json.dump({'completed_scenes': completed_scenes}, f)
+    print(f"  [CHECKPOINT] Saved: {len(completed_scenes)} scenes completed")
+
+def load_checkpoint(checkpoint_file):
+    if os.path.exists(checkpoint_file):
+        with open(checkpoint_file, 'r') as f:
+            data = json.load(f)
+            return set(data.get('completed_scenes', []))
+    return set()
+
+def get_completed_scenes_from_folder(images_dir):
+    if not os.path.exists(images_dir):
+        return set()
+    
+    completed = set()
+    files = os.listdir(images_dir)
+    
+    for f in files:
+        if f.startswith('scene_') and '_original.png' in f:
+            try:
+                scene_num = int(f.split('_')[1])
+                completed.add(scene_num)
+            except (IndexError, ValueError):
+                continue
+    
+    return completed
+
+def create_patched_utils():
+    return None
+
+def create_patched_render_script():
+    current_dir = os.path.dirname(os.path.abspath(__file__))
+    render_path = os.path.join(current_dir, 'scripts', 'render.py')
+    
+    with open(render_path, 'r', encoding='utf-8') as f:
+        original_content = f.read()
+    
+    patched_content = original_content
+    
+    import_patterns = [
+        'if INSIDE_BLENDER:\n  import sys\n  import os\n  current_dir = os.path.dirname(os.path.abspath(__file__))\n  if current_dir not in sys.path:\n    sys.path.insert(0, current_dir)\n  \n  try:\n    import utils',
+        'if INSIDE_BLENDER:\n  try:\n    import utils',
+    ]
+    
+    for pattern in import_patterns:
+        if pattern in patched_content:
+            import_start = patched_content.find(pattern)
+            if import_start != -1:
+                import_end = patched_content.find('    sys.exit(1)', import_start)
+                if import_end == -1:
+                    import_end = patched_content.find('\nparser =', import_start)
+                if import_end != -1:
+                    import_end = patched_content.find('\n', import_end)
+                    patched_content = patched_content[:import_start] + patched_content[import_end:]
+                    break
+    
+    patched_content = patched_content.replace(
+        '  render_args.tile_x = args.render_tile_size\n  render_args.tile_y = args.render_tile_size',
+        '  pass'
+    )
+    
+    patched_content = patched_content.replace("render_args.engine = 'BLENDER_EEVEE'", "render_args.engine = 'CYCLES'")
+    
+    patched_content = patched_content.replace(
+        "bpy.data.worlds['World'].cycles.sample_as_light = True",
+        "pass"
+    )
+    patched_content = patched_content.replace(
+        "bpy.context.scene.cycles.transparent_min_bounces = args.render_min_bounces",
+        "pass"
+    )
+    patched_content = patched_content.replace(
+        "bpy.context.scene.cycles.transparent_max_bounces = args.render_max_bounces",
+        "pass"
+    )
+
+    if "margins_good = True" in patched_content and "BROKEN MARGIN!" in patched_content:
+        old_margin_check = """          for direction_name in ['left', 'right', 'front', 'behind']:
+            direction_vec = scene_struct['directions'][direction_name]
+            assert direction_vec[2] == 0
+            margin = dx * direction_vec[0] + dy * direction_vec[1]
+            if 0 < margin < args.margin:
+              print(margin, args.margin, direction_name)
+              print('BROKEN MARGIN!')
+              margins_good = False
+              break"""
+        
+        new_margin_check = """          pass"""
+        
+        if old_margin_check in patched_content:
+            patched_content = patched_content.replace(old_margin_check, new_margin_check)
+    
+    patched_content = patched_content.replace(
+        "parser.add_argument('--min_pixels_per_object', default=200, type=int,",
+        "parser.add_argument('--min_pixels_per_object', default=50, type=int,"
+    )
+    patched_content = patched_content.replace(
+        "parser.add_argument('--max_retries', default=50, type=int,",
+        "parser.add_argument('--max_retries', default=200, type=int,"
+    )
+    patched_content = patched_content.replace(
+        "parser.add_argument('--max_retries', default=100, type=int,",
+        "parser.add_argument('--max_retries', default=200, type=int,"
+    )
+    patched_content = patched_content.replace(
+        "parser.add_argument('--margin', default=0.4, type=float,",
+        "parser.add_argument('--margin', default=0.05, type=float,"
+    )
+    patched_content = patched_content.replace(
+        "parser.add_argument('--margin', default=0.2, type=float,",
+        "parser.add_argument('--margin', default=0.05, type=float,"
+    )
+    patched_content = patched_content.replace(
+        "parser.add_argument('--min_dist', default=0.25, type=float,",
+        "parser.add_argument('--min_dist', default=0.15, type=float,"
+    )
+    
+    script_path = os.path.abspath('render_images_patched.py')
+    with open(script_path, 'w', encoding='utf-8') as f:
+        f.write(patched_content)
+    
+    return script_path
+
+def create_render_from_json_script():
+    current_dir = os.path.dirname(os.path.abspath(__file__))
+    render_path = os.path.join(current_dir, 'scripts', 'render.py')
+    return render_path
+
+def generate_base_scene(num_objects, blender_path, scene_idx, temp_run_dir=None):
+    cwd = os.getcwd()
+    script_file = os.path.abspath(__file__)
+    current_dir = os.path.dirname(script_file)
+    temp_dir_to_clean = None
+
+    possible_dirs = [
+        current_dir,
+        cwd,
+        os.path.join(os.environ.get('HOME', ''), 'app'),
+        '/home/user/app',
+        os.path.dirname(cwd),
+        '/app',
+    ]
+
+    data_dir = None
+    for possible_dir in possible_dirs:
+        if not possible_dir:
+            continue
+        test_data_dir = os.path.join(possible_dir, 'data')
+        if os.path.exists(test_data_dir) and os.path.exists(os.path.join(test_data_dir, 'base_scene.blend')):
+            data_dir = test_data_dir
+            break
+
+    if data_dir is None:
+        print(f"  ERROR: Could not find data directory")
+        print(f"  Searched in:")
+        for pd in possible_dirs:
+            if pd:
+                test_path = os.path.join(pd, 'data')
+                exists = os.path.exists(test_path)
+                print(f"    - {test_path}: {'EXISTS' if exists else 'NOT FOUND'}")
+                if exists:
+                    try:
+                        contents = os.listdir(test_path)
+                        print(f"      Contents: {contents[:5]}")
+                    except:
+                        pass
+        print(f"  Current working directory: {cwd}")
+        print(f"  Script directory: {current_dir}")
+        print(f"  Script file: {script_file}")
+        print(f"  HOME: {os.environ.get('HOME', 'NOT SET')}")
+        return None
+
+    if temp_run_dir is None:
+        temp_run_dir = os.path.join(cwd, 'temp_output', f"run_{datetime.now().strftime('%Y%m%d_%H%M%S')}_{scene_idx}")
+        temp_dir_to_clean = temp_run_dir
+    else:
+        temp_run_dir = os.path.join(cwd, 'temp_output', temp_run_dir) if not os.path.isabs(temp_run_dir) else temp_run_dir
+
+    temp_images_dir = os.path.join(temp_run_dir, 'images')
+    temp_scenes_dir = os.path.join(temp_run_dir, 'scenes')
+
+    os.makedirs(temp_images_dir, exist_ok=True)
+    os.makedirs(temp_scenes_dir, exist_ok=True)
+
+    try:
+        patched_script = create_patched_render_script()
+
+        if blender_path == 'blender':
+            blender_path = find_blender()
+
+        if not os.path.exists(blender_path) and blender_path != 'blender':
+            print(f"  ERROR: Blender path does not exist: {blender_path}")
+            return None
+
+        base_scene = os.path.join(data_dir, 'base_scene.blend')
+        properties_json = os.path.join(data_dir, 'properties.json')
+        shape_dir = os.path.join(data_dir, 'shapes')
+        material_dir = os.path.join(data_dir, 'materials')
+
+        base_scene = os.path.abspath(base_scene)
+        properties_json = os.path.abspath(properties_json)
+        shape_dir = os.path.abspath(shape_dir)
+        material_dir = os.path.abspath(material_dir)
+        temp_images_dir = os.path.abspath(temp_images_dir)
+        temp_scenes_dir = os.path.abspath(temp_scenes_dir)
+
+        if not os.path.exists(base_scene):
+            print(f"  ERROR: Base scene file not found: {base_scene}")
+            print(f"  Data directory contents: {os.listdir(data_dir) if os.path.exists(data_dir) else 'N/A'}")
+            return None
+        if not os.path.exists(properties_json):
+            print(f"  ERROR: Properties JSON not found: {properties_json}")
+            return None
+        if not os.path.exists(shape_dir):
+            print(f"  ERROR: Shape directory not found: {shape_dir}")
+            if os.path.exists(data_dir):
+                print(f"  Data directory contents: {os.listdir(data_dir)}")
+            return None
+        if not os.path.exists(material_dir):
+            print(f"  ERROR: Material directory not found: {material_dir}")
+            return None
+
+        env = os.environ.copy()
+
+        cmd = [
+            blender_path, '--background', '-noaudio', '--python', patched_script, '--',
+            '--num_images', '1',
+            '--start_idx', str(scene_idx),
+            '--min_objects', str(num_objects),
+            '--max_objects', str(num_objects),
+            '--min_pixels_per_object', '50',
+            '--min_dist', '0.20',
+            '--margin', '0.2',
+            '--max_retries', '100',
+            '--output_image_dir', temp_images_dir,
+            '--output_scene_dir', temp_scenes_dir,
+            '--filename_prefix', f'SCENE_{scene_idx:04d}',
+            '--base_scene_blendfile', base_scene,
+            '--properties_json', properties_json,
+            '--shape_dir', shape_dir,
+            '--material_dir', material_dir,
+        ]
+
+        result = subprocess.run(cmd, capture_output=True, text=True, timeout=300, env=env, cwd=cwd)
+
+        if result.returncode != 0:
+            print(f"ERROR: Blender returned code {result.returncode}")
+            print(f"  Blender path used: {blender_path}")
+            print(f"  Command: {' '.join(cmd[:3])}...")
+            if result.stderr:
+                print(f"  Error details (last 1000 chars): {result.stderr[-1000:]}")
+            if result.stdout:
+                error_lines = [line for line in result.stdout.split('\n') if 'error' in line.lower() or 'Error' in line or 'ERROR' in line or 'Traceback' in line]
+                if error_lines:
+                    print(f"  Error lines from stdout: {error_lines[-10:]}")
+                print(f"  Full stdout (last 500 chars): {result.stdout[-500:]}")
+            return None
+
+        if not os.path.exists(temp_scenes_dir):
+            print(f"ERROR: temp run scenes directory does not exist")
+            print(f"  Expected: {temp_scenes_dir}")
+            print(f"  Current directory: {cwd}")
+            print(f"  Temp run dir exists: {os.path.exists(temp_run_dir)}")
+            if os.path.exists(temp_run_dir):
+                print(f"  Contents: {os.listdir(temp_run_dir)}")
+            return None
+
+        scene_file = os.path.join(temp_scenes_dir, f'SCENE_{scene_idx:04d}_new_{scene_idx:06d}.json')
+        if not os.path.exists(scene_file):
+            print(f"  Scene file not found at expected path: {scene_file}")
+            if os.path.exists(temp_scenes_dir):
+                scene_files = os.listdir(temp_scenes_dir)
+                print(f"  Available scene files ({len(scene_files)}): {scene_files[:10]}")
+                matching_files = [f for f in scene_files if f.startswith(f'SCENE_{scene_idx:04d}')]
+                print(f"  Files matching SCENE_{scene_idx:04d}: {matching_files}")
+                if matching_files:
+                    scene_file = os.path.join(temp_scenes_dir, matching_files[0])
+                    print(f"  Using: {scene_file}")
+                else:
+                    print(f"ERROR: No matching scene file found for scene_idx {scene_idx}")
+                    print(f"  Checked for files starting with: SCENE_{scene_idx:04d}")
+                    return None
+            else:
+                print(f"ERROR: temp run scenes directory does not exist: {temp_scenes_dir}")
+                return None
+
+        if not os.path.exists(scene_file):
+            print(f"ERROR: Scene file not found: {scene_file}")
+            return None
+
+        try:
+            with open(scene_file, 'r') as f:
+                scene = json.load(f)
+        except Exception as e:
+            print(f"ERROR: Failed to read scene file {scene_file}: {e}")
+            return None
+
+        if 'objects' not in scene:
+            print(f"ERROR: Scene file missing 'objects' key. Scene keys: {list(scene.keys())}")
+            print(f"  Scene file contents (first 500 chars): {json.dumps(scene, indent=2)[:500]}")
+            return None
+
+        if len(scene['objects']) == 0:
+            print(f"WARNING: Scene has 0 objects")
+            print(f"  This usually means Blender hit max_retries trying to place objects")
+            print(f"  Scene file contents (first 1000 chars): {json.dumps(scene, indent=2)[:1000]}")
+            if result and result.stdout:
+                retry_lines = [line for line in result.stdout.split('\n') if 'retry' in line.lower() or 'Retry' in line or 'attempt' in line.lower()]
+                if retry_lines:
+                    print(f"  Retry-related output: {retry_lines[-5:]}")
+            return None
+
+        print(f"  [OK] Generated scene with {len(scene['objects'])} objects")
+        return scene
+    finally:
+        if temp_dir_to_clean and os.path.exists(temp_dir_to_clean):
+            try:
+                shutil.rmtree(temp_dir_to_clean)
+            except Exception:
+                pass
+
+def cf_change_color(scene):
+    cf_scene = copy.deepcopy(scene)
+    
+    if len(cf_scene['objects']) == 0:
+        return cf_scene, "no change (0 objects)"
+    
+    change_idx = random.randint(0, len(cf_scene['objects']) - 1)
+    obj = cf_scene['objects'][change_idx]
+    
+    colors = ['gray', 'red', 'blue', 'green', 'brown', 'purple', 'cyan', 'yellow']
+    old_color = obj['color']
+    new_color = random.choice([c for c in colors if c != old_color])
+    obj['color'] = new_color
+    
+    return cf_scene, f"changed {old_color} {obj['shape']} to {new_color}"
+
+def cf_change_position(scene):
+    cf_scene = copy.deepcopy(scene)
+    
+    if len(cf_scene['objects']) == 0:
+        return cf_scene, "no move (0 objects)"
+    
+    move_idx = random.randint(0, len(cf_scene['objects']) - 1)
+    obj = cf_scene['objects'][move_idx]
+    old_coords = obj['3d_coords']
+    
+    try:
+        script_dir = os.path.dirname(os.path.abspath(__file__))
+        with open(os.path.join(script_dir, 'data', 'properties.json'), 'r') as f:
+            properties = json.load(f)
+            size_mapping = properties['sizes']
+    except Exception:
+        size_mapping = {'small': 0.35, 'large': 0.7}
+    
+    r = size_mapping.get(obj['size'], 0.5)
+    if obj['shape'] == 'cube':
+        r /= math.sqrt(2)
+    
+    min_dist = 0.25
+    for attempt in range(100):
+        new_x = random.uniform(-3, 3)
+        new_y = random.uniform(-3, 3)
+        try:
+            dx0 = float(new_x) - float(old_coords[0])
+            dy0 = float(new_y) - float(old_coords[1])
+            if math.sqrt(dx0 * dx0 + dy0 * dy0) < 1.0:
+                continue
+        except Exception:
+            pass
+        
+        collision = False
+        for other_idx, other_obj in enumerate(cf_scene['objects']):
+            if other_idx == move_idx:
+                continue
+            other_x, other_y, _ = other_obj['3d_coords']
+            other_r = size_mapping.get(other_obj['size'], 0.5)
+            if other_obj['shape'] == 'cube':
+                other_r /= math.sqrt(2)
+            dist = math.sqrt((new_x - other_x)**2 + (new_y - other_y)**2)
+            if dist < (r + other_r + min_dist):
+                collision = True
+                break
+        
+        if not collision:
+            obj['3d_coords'] = [new_x, new_y, old_coords[2]]
+            obj['pixel_coords'] = [0, 0, 0]
+            return cf_scene, f"moved {obj['color']} {obj['shape']} from ({old_coords[0]:.1f},{old_coords[1]:.1f}) to ({new_x:.1f},{new_y:.1f})"
+    
+    return cf_scene, f"no move (couldn't find collision-free position for {obj['color']} {obj['shape']})"
+
+def cf_add_object(scene):
+    cf_scene = copy.deepcopy(scene)
+    
+    shapes = ['cube', 'sphere', 'cylinder']
+    colors = ['gray', 'red', 'blue', 'green', 'brown', 'purple', 'cyan', 'yellow']
+    materials = ['metal', 'rubber']
+    sizes = ['small', 'large']
+    
+    try:
+        script_dir = os.path.dirname(os.path.abspath(__file__))
+        with open(os.path.join(script_dir, 'data', 'properties.json'), 'r') as f:
+            properties = json.load(f)
+            size_mapping = properties['sizes']
+    except Exception:
+        size_mapping = {'small': 0.35, 'large': 0.7}
+    
+    min_dist = 0.25
+    
+    for attempt in range(100):
+        new_shape = random.choice(shapes)
+        new_size = random.choice(sizes)
+        new_r = size_mapping[new_size]
+        if new_shape == 'cube':
+            new_r /= math.sqrt(2)
+        
+        new_x = random.uniform(-3, 3)
+        new_y = random.uniform(-3, 3)
+        
+        collision = False
+        for other_obj in cf_scene['objects']:
+            other_x, other_y, _ = other_obj['3d_coords']
+            other_r = size_mapping.get(other_obj['size'], 0.5)
+            if other_obj['shape'] == 'cube':
+                other_r /= math.sqrt(2)
+            
+            dist = math.sqrt((new_x - other_x)**2 + (new_y - other_y)**2)
+            if dist < (new_r + other_r + min_dist):
+                collision = True
+                break
+        
+        if not collision:
+            new_obj = {
+                'shape': new_shape,
+                'color': random.choice(colors),
+                'material': random.choice(materials),
+                'size': new_size,
+                '3d_coords': [new_x, new_y, 0.35],
+                'rotation': random.uniform(0, 360),
+                'pixel_coords': [0, 0, 0]
+            }
+            cf_scene['objects'].append(new_obj)
+            return cf_scene, f"added {new_obj['color']} {new_obj['material']} {new_obj['shape']}"
+    
+    return cf_scene, "no change (couldn't find collision-free position for new object)"
+
+def cf_remove_object(scene):
+    cf_scene = copy.deepcopy(scene)
+    
+    if len(cf_scene['objects']) <= 1:
+        return cf_scene, "no removal (1 or fewer objects)"
+    
+    remove_idx = random.randint(0, len(cf_scene['objects']) - 1)
+    removed_obj = cf_scene['objects'].pop(remove_idx)
+    
+    return cf_scene, f"removed {removed_obj['color']} {removed_obj['shape']}"
+
+def cf_replace_object(scene):
+    cf_scene = copy.deepcopy(scene)
+    
+    if len(cf_scene['objects']) == 0:
+        return cf_scene, "no replace (0 objects)"
+    
+    replace_idx = random.randint(0, len(cf_scene['objects']) - 1)
+    old_obj = cf_scene['objects'][replace_idx]
+    old_desc = f"{old_obj['color']} {old_obj['shape']}"
+    
+    shapes = ['cube', 'sphere', 'cylinder']
+    colors = ['gray', 'red', 'blue', 'green', 'brown', 'purple', 'cyan', 'yellow']
+    materials = ['metal', 'rubber']
+    sizes = ['small', 'large']
+    
+    new_shape = random.choice([s for s in shapes if s != old_obj['shape']] or shapes)
+    new_color = random.choice([c for c in colors if c != old_obj['color']] or colors)
+    
+    new_obj = {
+        'shape': new_shape,
+        'color': new_color,
+        'material': random.choice(materials),
+        'size': random.choice(sizes),
+        '3d_coords': old_obj['3d_coords'],
+        'rotation': random.uniform(0, 360),
+        'pixel_coords': [0, 0, 0]
+    }
+    
+    cf_scene['objects'][replace_idx] = new_obj
+    
+    return cf_scene, f"replaced {old_desc} with {new_color} {new_shape}"
+
+
+def cf_swap_attribute(scene):
+    cf_scene = copy.deepcopy(scene)
+    
+    if len(cf_scene['objects']) < 2:
+        return cf_scene, "no swap (fewer than 2 objects)"
+    # Only consider pairs that differ in at least one intrinsic attribute
+    # beyond color, so we avoid swapping attributes between identical
+    # (shape,size,material) objects where questions cannot distinguish them.
+    candidates = []
+    objs = cf_scene['objects']
+    n = len(objs)
+    for i in range(n):
+        for j in range(i + 1, n):
+            a = objs[i]
+            b = objs[j]
+            if a['color'] == b['color']:
+                continue
+            if a['shape'] == b['shape'] and a['size'] == b['size'] and a['material'] == b['material']:
+                continue
+            candidates.append((i, j))
+    if not candidates:
+        return cf_scene, "no swap (no suitable object pair with different shape/size/material)"
+    idx_a, idx_b = random.choice(candidates)
+    obj_a = objs[idx_a]
+    obj_b = objs[idx_b]
+    color_a, color_b = obj_a['color'], obj_b['color']
+    obj_a['color'] = color_b
+    obj_b['color'] = color_a
+    return cf_scene, f"swapped colors between {color_a} {obj_a['shape']} and {color_b} {obj_b['shape']}"
+
+
+TARGET_OCCLUSION_COVERAGE = 0.6
+# Lateral offset as fraction of combined radius: occluder placed to the SIDE of target
+# so only part of target is hidden (partial occlusion), not fully behind occluder.
+OCCLUSION_LATERAL_FRACTIONS = (0.35, 0.5, 0.65, 0.25, 0.45)
+
+
+def cf_occlusion_change(scene):
+    cf_scene = copy.deepcopy(scene)
+    
+    if len(cf_scene['objects']) < 2:
+        return cf_scene, "no occlusion (fewer than 2 objects)"
+    
+    directions = cf_scene.get('directions', {})
+    front = directions.get('front', [0.75, -0.66, 0.0])
+    if len(front) < 2:
+        front = [0.75, -0.66]
+    left = directions.get('left', [-0.66, -0.75, 0.0])
+    if len(left) < 2:
+        left = [-0.66, -0.75]
+    
+    try:
+        script_dir = os.path.dirname(os.path.abspath(__file__))
+        with open(os.path.join(script_dir, 'data', 'properties.json'), 'r') as f:
+            properties = json.load(f)
+            size_mapping = properties['sizes']
+    except Exception:
+        size_mapping = {'small': 0.35, 'large': 0.7}
+    
+    def get_radius(obj):
+        r = size_mapping.get(obj['size'], 0.5)
+        if obj['shape'] == 'cube':
+            r /= math.sqrt(2)
+        return r
+    
+    min_dist = 0.15
+    def is_valid_occlusion_pos(cf_scene, occluder_idx, target_idx, new_x, new_y, occluder_r):
+        for i, other in enumerate(cf_scene['objects']):
+            if i == occluder_idx:
+                continue
+            other_x, other_y, _ = other['3d_coords']
+            other_r = get_radius(other)
+            dist = math.sqrt((new_x - other_x)**2 + (new_y - other_y)**2)
+            if dist < (occluder_r + other_r + min_dist):
+                return False
+        return -2.8 <= new_x <= 2.8 and -2.8 <= new_y <= 2.8
+    
+    fx, fy = float(front[0]), float(front[1])
+    fnorm = math.sqrt(fx * fx + fy * fy) or 1.0
+    lx, ly = float(left[0]), float(left[1])
+    lnorm = math.sqrt(lx * lx + ly * ly) or 1.0
+    # Forward offset: occluder between camera and target, but not jammed on top
+    forward_base = 0.25
+    forward_deltas = [0.0, 0.05, 0.1, 0.15, 0.2]
+    
+    pairs = [(i, j) for i in range(len(cf_scene['objects'])) for j in range(len(cf_scene['objects'])) if i != j]
+    random.shuffle(pairs)
+    
+    for occluder_idx, target_idx in pairs:
+        occluder = cf_scene['objects'][occluder_idx]
+        target = cf_scene['objects'][target_idx]
+        tx, ty, tz = target['3d_coords']
+        oz = occluder['3d_coords'][2]
+        occluder_r = get_radius(occluder)
+        target_r = get_radius(target)
+        combined = occluder_r + target_r + min_dist
+        # Lateral offset so occluder is to the side → partial overlap in camera view
+        for lateral_frac in OCCLUSION_LATERAL_FRACTIONS:
+            lateral = lateral_frac * combined
+            for sign in (1, -1):
+                lat_x = (lx / lnorm) * (lateral * sign)
+                lat_y = (ly / lnorm) * (lateral * sign)
+                for fdelta in forward_deltas:
+                    forward = forward_base + fdelta
+                    new_x = tx + (fx / fnorm) * forward + lat_x
+                    new_y = ty + (fy / fnorm) * forward + lat_y
+                    if is_valid_occlusion_pos(cf_scene, occluder_idx, target_idx, new_x, new_y, occluder_r):
+                        occluder['3d_coords'] = [new_x, new_y, oz]
+                        occluder['pixel_coords'] = [0, 0, 0]
+                        return cf_scene, f"moved {occluder['color']} {occluder['shape']} to partially occlude {target['color']} {target['shape']}"
+    
+    return cf_scene, "no occlusion (couldn't find valid position)"
+
+
+def cf_relational_flip(scene):
+    cf_scene = copy.deepcopy(scene)
+    
+    if len(cf_scene['objects']) < 2:
+        return cf_scene, "no flip (fewer than 2 objects)"
+    
+    directions = cf_scene.get('directions', {})
+    left_vec = directions.get('left', [-0.66, -0.75, 0.0])
+    if len(left_vec) < 2:
+        left_vec = [-0.66, -0.75]
+    
+    try:
+        script_dir = os.path.dirname(os.path.abspath(__file__))
+        with open(os.path.join(script_dir, 'data', 'properties.json'), 'r') as f:
+            properties = json.load(f)
+            size_mapping = properties['sizes']
+    except Exception:
+        size_mapping = {'small': 0.35, 'large': 0.7}
+    
+    def get_radius(obj):
+        r = size_mapping.get(obj['size'], 0.5)
+        if obj['shape'] == 'cube':
+            r /= math.sqrt(2)
+        return r
+    
+    def is_valid_pos(cf_scene, a_idx, new_x, new_y, r_a, min_dist=0.12):
+        for i, other in enumerate(cf_scene['objects']):
+            if i == a_idx:
+                continue
+            ox, oy, _ = other['3d_coords']
+            other_r = get_radius(other)
+            dist = math.sqrt((new_x - ox)**2 + (new_y - oy)**2)
+            if dist < (r_a + other_r + min_dist):
+                return False
+        return -2.8 <= new_x <= 2.8 and -2.8 <= new_y <= 2.8
+    
+    relationships = cf_scene.get('relationships', {})
+    left_of = relationships.get('left', [])
+    right_of = relationships.get('right', [])
+    
+    candidates = []
+    for b_idx in range(len(cf_scene['objects'])):
+        for a_idx in left_of[b_idx] if b_idx < len(left_of) else []:
+            if a_idx != b_idx and a_idx < len(cf_scene['objects']):
+                candidates.append((a_idx, b_idx, 'left'))
+        for a_idx in right_of[b_idx] if b_idx < len(right_of) else []:
+            if a_idx != b_idx and a_idx < len(cf_scene['objects']):
+                candidates.append((a_idx, b_idx, 'right'))
+    
+    if not candidates:
+        lx, ly = float(left_vec[0]), float(left_vec[1])
+        for a_idx in range(len(cf_scene['objects'])):
+            for b_idx in range(len(cf_scene['objects'])):
+                if a_idx == b_idx:
+                    continue
+                ax_a, ay_a, _ = cf_scene['objects'][a_idx]['3d_coords']
+                bx_b, by_b, _ = cf_scene['objects'][b_idx]['3d_coords']
+                dx, dy = ax_a - bx_b, ay_a - by_b
+                dot = dx * lx + dy * ly
+                if abs(dot) > 0.2:
+                    side = 'left' if dot > 0 else 'right'
+                    candidates.append((a_idx, b_idx, side))
+    
+    if not candidates:
+        return cf_scene, "no flip (no clear left/right relationships)"
+    
+    random.shuffle(candidates)
+    lx, ly = float(left_vec[0]), float(left_vec[1])
+    
+    for a_idx, b_idx, side in candidates:
+        obj_a = cf_scene['objects'][a_idx]
+        obj_b = cf_scene['objects'][b_idx]
+        ax, ay, az = obj_a['3d_coords']
+        bx, by, bz = obj_b['3d_coords']
+        r_a = get_radius(obj_a)
+        
+        dx, dy = ax - bx, ay - by
+        dot_left = dx * lx + dy * ly
+        ref_dx = dx - 2 * dot_left * lx
+        ref_dy = dy - 2 * dot_left * ly
+        
+        for scale in [1.0, 0.9, 0.8, 0.7, 0.85, 0.75]:
+            new_x = bx + scale * ref_dx
+            new_y = by + scale * ref_dy
+            if is_valid_pos(cf_scene, a_idx, new_x, new_y, r_a):
+                obj_a['3d_coords'] = [new_x, new_y, az]
+                obj_a['pixel_coords'] = [0, 0, 0]
+                new_side = "right" if side == "left" else "left"
+                return cf_scene, f"moved {obj_a['color']} {obj_a['shape']} from {side} of {obj_b['color']} {obj_b['shape']} to {new_side}"
+    
+    return cf_scene, "no flip (couldn't find collision-free position)"
+
+
+def cf_change_background(scene):
+    cf_scene = copy.deepcopy(scene)
+    
+    background_colors = ['gray', 'blue', 'green', 'brown', 'purple', 'orange', 'white', 'dark_gray']
+    current_bg = cf_scene.get('background_color', 'default')
+    
+    alternatives = [c for c in background_colors if c != current_bg]
+    new_background = random.choice(alternatives) if alternatives else 'gray'
+    
+    cf_scene['background_color'] = new_background
+    
+    return cf_scene, f"changed background to {new_background}"
+
+def cf_change_shape(scene):
+    cf_scene = copy.deepcopy(scene)
+    
+    if len(cf_scene['objects']) == 0:
+        return cf_scene, "no change (0 objects)"
+    
+    change_idx = random.randint(0, len(cf_scene['objects']) - 1)
+    obj = cf_scene['objects'][change_idx]
+    
+    shapes = ['cube', 'sphere', 'cylinder']
+    old_shape = obj['shape']
+    new_shape = random.choice([s for s in shapes if s != old_shape])
+    obj['shape'] = new_shape
+    
+    return cf_scene, f"changed {obj['color']} {old_shape} to {new_shape}"
+
+def cf_change_size(scene):
+    cf_scene = copy.deepcopy(scene)
+    
+    if len(cf_scene['objects']) == 0:
+        return cf_scene, "no change (0 objects)"
+    
+    change_idx = random.randint(0, len(cf_scene['objects']) - 1)
+    obj = cf_scene['objects'][change_idx]
+    
+    old_size = obj['size']
+    new_size = 'large' if old_size == 'small' else 'small'
+    obj['size'] = new_size
+    
+    return cf_scene, f"changed {obj['color']} {obj['shape']} from {old_size} to {new_size}"
+
+def cf_change_material(scene):
+    cf_scene = copy.deepcopy(scene)
+    
+    if len(cf_scene['objects']) == 0:
+        return cf_scene, "no change (0 objects)"
+    
+    change_idx = random.randint(0, len(cf_scene['objects']) - 1)
+    obj = cf_scene['objects'][change_idx]
+    
+    old_material = obj['material']
+    new_material = 'rubber' if old_material == 'metal' else 'metal'
+    obj['material'] = new_material
+    
+    return cf_scene, f"changed {obj['color']} {obj['shape']} from {old_material} to {new_material}"
+
+def cf_change_lighting(scene):
+    cf_scene = copy.deepcopy(scene)
+    
+    lighting_conditions = ['bright', 'dim', 'warm', 'cool', 'dramatic']
+    current_lighting = cf_scene.get('lighting', 'default')
+    
+    alternatives = [l for l in lighting_conditions if l != current_lighting]
+    new_lighting = random.choice(alternatives) if alternatives else 'bright'
+    
+    cf_scene['lighting'] = new_lighting
+    
+    return cf_scene, f"changed lighting to {new_lighting}"
+
+def cf_add_noise(scene, min_noise_level='light'):
+    cf_scene = copy.deepcopy(scene)
+    
+    noise_levels = ['light', 'medium', 'heavy']
+    noise_weights = {'light': 0, 'medium': 1, 'heavy': 2}
+    
+    min_weight = noise_weights.get(min_noise_level, 0)
+    valid_levels = [n for n in noise_levels if noise_weights[n] >= min_weight]
+    
+    current = cf_scene.get('noise_level', None)
+    choices = [n for n in valid_levels if n != current] if current in valid_levels else valid_levels
+    
+    if not choices:
+        choices = [min_noise_level] if min_noise_level in noise_levels else ['medium']
+    
+    cf_scene['noise_level'] = random.choice(choices)
+    
+    return cf_scene, f"added {cf_scene['noise_level']} noise (min: {min_noise_level})"
+
+def cf_apply_fisheye(scene):
+    cf_scene = copy.deepcopy(scene)
+    
+    current_filter = cf_scene.get('filter_type', None)
+    if current_filter == 'fisheye':
+        filter_strength = random.uniform(0.8, 1.2)
+    else:
+        filter_strength = random.uniform(0.8, 1.2)
+    
+    cf_scene['filter_type'] = 'fisheye'
+    cf_scene['filter_strength'] = filter_strength
+    
+    return cf_scene, f"applied fisheye filter (strength: {filter_strength:.2f})"
+
+def cf_apply_blur(scene):
+    cf_scene = copy.deepcopy(scene)
+    
+    current_filter = cf_scene.get('filter_type', None)
+    if current_filter == 'blur':
+        filter_strength = random.uniform(8.0, 15.0)
+    else:
+        filter_strength = random.uniform(8.0, 15.0)
+    
+    cf_scene['filter_type'] = 'blur'
+    cf_scene['filter_strength'] = filter_strength
+    
+    return cf_scene, f"applied blur filter (strength: {filter_strength:.2f})"
+
+def cf_apply_vignette(scene):
+    cf_scene = copy.deepcopy(scene)
+    
+    current_filter = cf_scene.get('filter_type', None)
+    if current_filter == 'vignette':
+        filter_strength = random.uniform(3.0, 5.0)
+    else:
+        filter_strength = random.uniform(3.0, 5.0)
+    
+    cf_scene['filter_type'] = 'vignette'
+    cf_scene['filter_strength'] = filter_strength
+    
+    return cf_scene, f"applied vignette filter (strength: {filter_strength:.2f})"
+
+def cf_apply_chromatic_aberration(scene):
+    cf_scene = copy.deepcopy(scene)
+    
+    current_filter = cf_scene.get('filter_type', None)
+    if current_filter == 'chromatic_aberration':
+        filter_strength = random.uniform(1.0, 4.0)
+    else:
+        filter_strength = random.uniform(1.0, 4.0)
+    
+    cf_scene['filter_type'] = 'chromatic_aberration'
+    cf_scene['filter_strength'] = filter_strength
+    
+    return cf_scene, f"applied chromatic aberration filter (strength: {filter_strength:.2f})"
+
+IMAGE_COUNTERFACTUALS = {
+    'change_color': cf_change_color,
+    'change_shape': cf_change_shape,
+    'change_size': cf_change_size,
+    'change_material': cf_change_material,
+    'change_position': cf_change_position,
+    'add_object': cf_add_object,
+    'remove_object': cf_remove_object,
+    'replace_object': cf_replace_object,
+    'swap_attribute': cf_swap_attribute,
+    'relational_flip': cf_relational_flip,
+}
+
+NEGATIVE_COUNTERFACTUALS = {
+    'change_background': cf_change_background,
+    'change_lighting': cf_change_lighting,
+    'add_noise': cf_add_noise,
+    'apply_fisheye': cf_apply_fisheye,
+    'apply_blur': cf_apply_blur,
+    'apply_vignette': cf_apply_vignette,
+    'apply_chromatic_aberration': cf_apply_chromatic_aberration,
+    'occlusion_change': cf_occlusion_change,
+}
+
+DEFAULT_NEGATIVE_CF_TYPES = [k for k in NEGATIVE_COUNTERFACTUALS if k != 'apply_fisheye']
+
+COUNTERFACTUAL_TYPES = {**IMAGE_COUNTERFACTUALS, **NEGATIVE_COUNTERFACTUALS}
+
+def generate_counterfactuals(scene, num_counterfactuals=2, cf_types=None, same_cf_type=False, min_change_score=1.0, max_cf_attempts=10, min_noise_level='light', semantic_only=False, negative_only=False):
+    counterfactuals = []
+
+    def compute_change_score(original_scene, cf_scene):
+        score = 0.0
+        if not isinstance(original_scene, dict) or not isinstance(cf_scene, dict):
+            return score
+
+        orig_objs = original_scene.get('objects', []) or []
+        cf_objs = cf_scene.get('objects', []) or []
+
+        if len(orig_objs) != len(cf_objs):
+            score += 5.0
+
+        n = min(len(orig_objs), len(cf_objs))
+        for i in range(n):
+            o = orig_objs[i] or {}
+            c = cf_objs[i] or {}
+            for k in ['color', 'shape', 'size', 'material']:
+                if o.get(k) != c.get(k):
+                    score += 1.0
+
+            o3 = o.get('3d_coords')
+            c3 = c.get('3d_coords')
+            try:
+                if o3 and c3 and len(o3) >= 2 and len(c3) >= 2:
+                    dx = float(c3[0]) - float(o3[0])
+                    dy = float(c3[1]) - float(o3[1])
+                    dist = math.sqrt(dx * dx + dy * dy)
+                    score += min(dist, 3.0)
+            except Exception:
+                pass
+
+            try:
+                if o.get('rotation') is not None and c.get('rotation') is not None:
+                    rot_diff = abs(float(c.get('rotation')) - float(o.get('rotation')))
+                    rot_diff = min(rot_diff, 360.0 - rot_diff)
+                    score += min(rot_diff / 180.0, 1.0) * 0.5
+            except Exception:
+                pass
+
+        if 'background_color' in cf_scene and original_scene.get('background_color') != cf_scene.get('background_color'):
+            score += 1.0
+            if cf_scene.get('background_color') in ['white', 'dark_gray']:
+                score += 0.5
+        if 'lighting' in cf_scene and original_scene.get('lighting') != cf_scene.get('lighting'):
+            score += 1.0
+        if 'noise_level' in cf_scene and original_scene.get('noise_level') != cf_scene.get('noise_level'):
+            score += {'light': 0.5, 'medium': 1.0, 'heavy': 1.5}.get(cf_scene.get('noise_level'), 0.8)
+        if 'filter_type' in cf_scene and original_scene.get('filter_type') != cf_scene.get('filter_type'):
+            filter_strength = cf_scene.get('filter_strength', 1.0)
+            score += min(filter_strength, 2.0)
+
+        return score
+
+    def generate_one_with_min_change(cf_func, min_change_score=0.0, max_attempts=10):
+        best_scene = None
+        best_desc = None
+        best_score = -1.0
+        attempts = 0
+        for attempt in range(max_attempts):
+            attempts = attempt + 1
+            if cf_func == cf_add_noise:
+                candidate_scene, candidate_desc = cf_func(scene, min_noise_level=min_noise_level)
+            else:
+                candidate_scene, candidate_desc = cf_func(scene)
+            score = compute_change_score(scene, candidate_scene)
+            if score > best_score:
+                best_scene, best_desc, best_score = candidate_scene, candidate_desc, score
+            if score >= min_change_score:
+                break
+        return best_scene, best_desc, best_score, attempts
+    
+    selected_types = None
+    if semantic_only and negative_only:
+        semantic_only = False
+        negative_only = False
+    if same_cf_type and cf_types:
+        pool = cf_types
+        if semantic_only:
+            pool = [t for t in cf_types if t in IMAGE_COUNTERFACTUALS]
+        elif negative_only:
+            pool = [t for t in cf_types if t in NEGATIVE_COUNTERFACTUALS]
+        if pool:
+            selected_types = [pool[0]] * num_counterfactuals
+        else:
+            selected_types = [cf_types[0]] * num_counterfactuals if cf_types else None
+    elif same_cf_type and not cf_types:
+        if semantic_only:
+            one_type = random.choice(list(IMAGE_COUNTERFACTUALS.keys()))
+        elif negative_only:
+            one_type = random.choice(DEFAULT_NEGATIVE_CF_TYPES)
+        else:
+            one_type = random.choice(list(COUNTERFACTUAL_TYPES.keys()))
+        selected_types = [one_type] * num_counterfactuals
+    elif cf_types:
+        pool = cf_types
+        if semantic_only:
+            pool = [t for t in cf_types if t in IMAGE_COUNTERFACTUALS] or cf_types
+        elif negative_only:
+            pool = [t for t in cf_types if t in NEGATIVE_COUNTERFACTUALS] or cf_types
+        # No duplicate CF types per scene: sample without replacement
+        n = min(num_counterfactuals, len(pool))
+        selected_types = random.sample(pool, n) if n > 0 else []
+    elif semantic_only:
+        pool = list(IMAGE_COUNTERFACTUALS.keys())
+        selected_types = [random.choice(pool) for _ in range(num_counterfactuals)]
+    elif negative_only:
+        pool = DEFAULT_NEGATIVE_CF_TYPES
+        selected_types = [random.choice(pool) for _ in range(num_counterfactuals)]
+
+    if selected_types is not None:
+        for cf_type in selected_types:
+            if cf_type not in COUNTERFACTUAL_TYPES:
+                print(f"WARNING: Unknown CF type '{cf_type}', skipping")
+                continue
+            
+            cf_func = COUNTERFACTUAL_TYPES[cf_type]
+            cf_scene, cf_desc, change_score, change_attempts = generate_one_with_min_change(
+                cf_func,
+                min_change_score=min_change_score,
+                max_attempts=max_cf_attempts
+            )
+            cf_category = 'image_cf' if cf_type in IMAGE_COUNTERFACTUALS else 'negative_cf'
+            
+            counterfactuals.append({
+                'scene': cf_scene,
+                'description': cf_desc,
+                'type': cf_type,
+                'cf_category': cf_category,
+                'change_score': change_score,
+                'change_attempts': change_attempts,
+            })
+
+    elif num_counterfactuals >= 2:
+        if semantic_only:
+            pool = list(IMAGE_COUNTERFACTUALS.keys())
+            for _ in range(num_counterfactuals):
+                cf_type = random.choice(pool)
+                cf_func = IMAGE_COUNTERFACTUALS[cf_type]
+                cf_scene, cf_desc, change_score, change_attempts = generate_one_with_min_change(
+                    cf_func,
+                    min_change_score=min_change_score,
+                    max_attempts=max_cf_attempts
+                )
+                counterfactuals.append({
+                    'scene': cf_scene,
+                    'description': cf_desc,
+                    'type': cf_type,
+                    'cf_category': 'image_cf',
+                    'change_score': change_score,
+                    'change_attempts': change_attempts,
+                })
+        elif negative_only:
+            pool = DEFAULT_NEGATIVE_CF_TYPES
+            for _ in range(num_counterfactuals):
+                cf_type = random.choice(pool)
+                cf_func = NEGATIVE_COUNTERFACTUALS[cf_type]
+                cf_scene, cf_desc, change_score, change_attempts = generate_one_with_min_change(
+                    cf_func,
+                    min_change_score=min_change_score,
+                    max_attempts=max_cf_attempts
+                )
+                counterfactuals.append({
+                    'scene': cf_scene,
+                    'description': cf_desc,
+                    'type': cf_type,
+                    'cf_category': 'negative_cf',
+                    'change_score': change_score,
+                    'change_attempts': change_attempts,
+                })
+        else:
+            image_cf_type = random.choice(list(IMAGE_COUNTERFACTUALS.keys()))
+            image_cf_func = IMAGE_COUNTERFACTUALS[image_cf_type]
+            cf_scene, cf_desc, change_score, change_attempts = generate_one_with_min_change(
+                image_cf_func,
+                min_change_score=min_change_score,
+                max_attempts=max_cf_attempts
+            )
+            counterfactuals.append({
+                'scene': cf_scene,
+                'description': cf_desc,
+                'type': image_cf_type,
+                'cf_category': 'image_cf',
+                'change_score': change_score,
+                'change_attempts': change_attempts,
+            })
+            
+            neg_cf_type = random.choice(DEFAULT_NEGATIVE_CF_TYPES)
+            neg_cf_func = NEGATIVE_COUNTERFACTUALS[neg_cf_type]
+            cf_scene, cf_desc, change_score, change_attempts = generate_one_with_min_change(
+                neg_cf_func,
+                min_change_score=min_change_score,
+                max_attempts=max_cf_attempts
+            )
+            counterfactuals.append({
+                'scene': cf_scene,
+                'description': cf_desc,
+                'type': neg_cf_type,
+                'cf_category': 'negative_cf',
+                'change_score': change_score,
+                'change_attempts': change_attempts,
+            })
+
+            remaining = num_counterfactuals - 2
+            if remaining > 0:
+                all_cf_types = list(COUNTERFACTUAL_TYPES.keys())
+                used_types = {image_cf_type, neg_cf_type}
+                available = [t for t in all_cf_types if t not in used_types and t != 'apply_fisheye']
+                
+                extra_types = random.sample(available, min(remaining, len(available)))
+                for cf_type in extra_types:
+                    cf_func = COUNTERFACTUAL_TYPES[cf_type]
+                    cf_scene, cf_desc, change_score, change_attempts = generate_one_with_min_change(
+                        cf_func,
+                        min_change_score=min_change_score,
+                        max_attempts=max_cf_attempts
+                    )
+                    cf_category = 'image_cf' if cf_type in IMAGE_COUNTERFACTUALS else 'negative_cf'
+                    counterfactuals.append({
+                        'scene': cf_scene,
+                        'description': cf_desc,
+                        'type': cf_type,
+                        'cf_category': cf_category,
+                        'change_score': change_score,
+                        'change_attempts': change_attempts,
+                    })
+    
+    elif num_counterfactuals == 1:
+        if semantic_only:
+            cf_type = random.choice(list(IMAGE_COUNTERFACTUALS.keys()))
+            cf_func = IMAGE_COUNTERFACTUALS[cf_type]
+            cf_category = 'image_cf'
+        elif negative_only:
+            cf_type = random.choice(DEFAULT_NEGATIVE_CF_TYPES)
+            cf_func = NEGATIVE_COUNTERFACTUALS[cf_type]
+            cf_category = 'negative_cf'
+        elif random.random() < 0.5:
+            cf_type = random.choice(list(IMAGE_COUNTERFACTUALS.keys()))
+            cf_func = IMAGE_COUNTERFACTUALS[cf_type]
+            cf_category = 'image_cf'
+        else:
+            cf_type = random.choice(DEFAULT_NEGATIVE_CF_TYPES)
+            cf_func = NEGATIVE_COUNTERFACTUALS[cf_type]
+            cf_category = 'negative_cf'
+        
+        cf_scene, cf_desc, change_score, change_attempts = generate_one_with_min_change(
+            cf_func,
+            min_change_score=min_change_score,
+            max_attempts=max_cf_attempts
+        )
+        counterfactuals.append({
+            'scene': cf_scene,
+            'description': cf_desc,
+            'type': cf_type,
+            'cf_category': cf_category,
+            'change_score': change_score,
+            'change_attempts': change_attempts,
+        })
+    
+    return counterfactuals
+
+def render_scene(blender_path, scene_file, output_image, use_gpu=0, samples=512, width=320, height=240):
+    current_dir = os.path.dirname(os.path.abspath(__file__))
+    render_script = os.path.join(current_dir, 'scripts', 'render.py')
+    render_script = os.path.normpath(render_script)
+
+    base_scene = os.path.join(current_dir, 'data', 'base_scene.blend')
+    properties_json = os.path.join(current_dir, 'data', 'properties.json')
+    shape_dir = os.path.join(current_dir, 'data', 'shapes')
+    material_dir = os.path.join(current_dir, 'data', 'materials')
+
+    base_scene = os.path.normpath(base_scene)
+    properties_json = os.path.normpath(properties_json)
+    shape_dir = os.path.normpath(shape_dir)
+    material_dir = os.path.normpath(material_dir)
+    scene_file = os.path.normpath(scene_file)
+    output_image = os.path.normpath(output_image)
+
+    if not os.path.exists(base_scene):
+        print(f"  ERROR: Base scene file not found: {base_scene}")
+        return False
+    if not os.path.exists(properties_json):
+        print(f"  ERROR: Properties JSON not found: {properties_json}")
+        return False
+    if not os.path.exists(scene_file):
+        print(f"  ERROR: Scene file not found: {scene_file}")
+        return False
+
+    output_dir = os.path.dirname(output_image)
+    if output_dir and not os.path.exists(output_dir):
+        os.makedirs(output_dir, exist_ok=True)
+
+    output_image_abs = os.path.abspath(output_image)
+    
+    cmd = [
+        blender_path, '--background', '-noaudio', '--python', render_script, '--',
+        '--scene_file', scene_file,
+        '--output_image', output_image_abs,
+        '--base_scene_blendfile', base_scene,
+        '--properties_json', properties_json,
+        '--shape_dir', shape_dir,
+        '--material_dir', material_dir,
+        '--use_gpu', str(use_gpu),
+        '--render_num_samples', str(samples),
+        '--width', str(width),
+        '--height', str(height)
+    ]
+    
+    env = os.environ.copy()
+    result = subprocess.run(cmd, capture_output=True, text=True, timeout=600, env=env)
+
+    if result.returncode == 0 and os.path.exists(output_image_abs):
+        try:
+            import json
+            with open(scene_file, 'r') as f:
+                scene_data = json.load(f)
+            
+            filter_type = scene_data.get('filter_type')
+            noise_level = scene_data.get('noise_level')
+            
+            if filter_type or noise_level:
+                try:
+                    from PIL import Image, ImageFilter
+                    import math
+                    
+                    filter_strength = scene_data.get('filter_strength', 1.0)
+                    img = Image.open(output_image_abs)
+                    
+                    if filter_type == 'blur':
+                        radius = max(1, int(filter_strength))
+                        img = img.filter(ImageFilter.GaussianBlur(radius=radius))
+                    
+                    elif filter_type == 'vignette':
+                        width, height = img.size
+                        center_x, center_y = width // 2, height // 2
+                        max_dist = math.sqrt(center_x**2 + center_y**2)
+                        img = img.convert('RGB')
+                        pixels = img.load()
+                        for y in range(height):
+                            for x in range(width):
+                                dist = math.sqrt((x - center_x)**2 + (y - center_y)**2)
+                                factor = 1.0 - (dist / max_dist) * (filter_strength / 5.0)
+                                factor = max(0.0, min(1.0, factor))
+                                r, g, b = pixels[x, y]
+                                pixels[x, y] = (int(r * factor), int(g * factor), int(b * factor))
+                    
+                    elif filter_type == 'fisheye':
+                        width, height = img.size
+                        center_x, center_y = width / 2.0, height / 2.0
+                        max_radius = min(center_x, center_y)
+                        img = img.convert('RGB')
+                        output = Image.new('RGB', (width, height))
+                        out_pixels = output.load()
+                        in_pixels = img.load()
+                        
+                        distortion_strength = 0.55 * filter_strength
+                        
+                        for y in range(height):
+                            for x in range(width):
+                                dx = (x - center_x) / max_radius
+                                dy = (y - center_y) / max_radius
+                                distance = math.sqrt(dx*dx + dy*dy)
+                                
+                                if distance >= 1.0:
+                                    out_pixels[x, y] = in_pixels[x, y]
+                                else:
+                                    theta = math.atan2(dy, dx)
+                                    r_normalized = distance
+                                    
+                                    r_distorted = math.atan(2 * r_normalized * distortion_strength) / math.atan(2 * distortion_strength)
+                                    r_distorted = min(0.999, r_distorted)
+                                    
+                                    src_x = int(center_x + r_distorted * max_radius * math.cos(theta))
+                                    src_y = int(center_y + r_distorted * max_radius * math.sin(theta))
+                                    
+                                    if 0 <= src_x < width and 0 <= src_y < height:
+                                        out_pixels[x, y] = in_pixels[src_x, src_y]
+                                    else:
+                                        out_pixels[x, y] = in_pixels[x, y]
+                        
+                        img = output
+                    
+                    elif filter_type == 'chromatic_aberration':
+                        width, height = img.size
+                        img = img.convert('RGB')
+                        output = Image.new('RGB', (width, height))
+                        out_pixels = output.load()
+                        in_pixels = img.load()
+                        
+                        offset = int(filter_strength * 2)
+                        
+                        for y in range(height):
+                            for x in range(width):
+                                r_x = max(0, min(width - 1, x - offset))
+                                g_x = x
+                                b_x = max(0, min(width - 1, x + offset))
+                                
+                                r = in_pixels[r_x, y][0] if 0 <= r_x < width else 0
+                                g = in_pixels[g_x, y][1] if 0 <= g_x < width else 0
+                                b = in_pixels[b_x, y][2] if 0 <= b_x < width else 0
+                                
+                                out_pixels[x, y] = (r, g, b)
+                        
+                        img = output
+
+                    if noise_level:
+                        import random
+                        noise_amounts = {'light': 10, 'medium': 25, 'heavy': 50}
+                        noise_amount = noise_amounts.get(noise_level, 20)
+                        img = img.convert('RGB')
+                        pixels = img.load()
+                        width, height = img.size
+                        
+                        for y in range(height):
+                            for x in range(width):
+                                r, g, b = pixels[x, y]
+                                noise_r = random.randint(-noise_amount, noise_amount)
+                                noise_g = random.randint(-noise_amount, noise_amount)
+                                noise_b = random.randint(-noise_amount, noise_amount)
+                                
+                                r = max(0, min(255, r + noise_r))
+                                g = max(0, min(255, g + noise_g))
+                                b = max(0, min(255, b + noise_b))
+                                
+                                pixels[x, y] = (r, g, b)
+                    
+                    img.save(output_image_abs)
+                except ImportError:
+                    pass
+                except Exception as e:
+                    print(f"  Warning: Could not apply filter {filter_type}: {e}")
+        
+        except Exception as e:
+            pass
+    
+    if result.returncode == 0 and os.path.exists(output_image_abs):
+        return True
+    else:
+        print(f"  ERROR rendering {output_image_abs}")
+        print(f"  Return code: {result.returncode}")
+        print(f"  Output file exists: {os.path.exists(output_image_abs)}")
+        if result.stderr:
+            print(f"  Blender stderr (last 1000 chars):")
+            print(result.stderr[-1000:])
+        if result.stdout:
+            print(f"  Blender stdout (last 1000 chars):")
+            print(result.stdout[-1000:])
+            error_lines = [line for line in result.stdout.split('\n') if 'ERROR' in line.upper() or 'Traceback' in line or 'Exception' in line or 'failed' in line.lower()]
+            if error_lines:
+                error_msg = '\n'.join(error_lines[-20:])
+                print(f"  Error lines found: {error_msg}")
+        return False
+
+def save_scene(scene, output_path):
+    os.makedirs(os.path.dirname(output_path), exist_ok=True)
+    with open(output_path, 'w') as f:
+        json.dump(scene, f, indent=2)
+
+def list_counterfactual_types():
+    print("\n" + "="*70)
+    print("AVAILABLE COUNTERFACTUAL TYPES")
+    print("="*70)
+    
+    print("\nIMAGE COUNTERFACTUALS (Should change VQA answers):")
+    print("  change_color       - Change color of an object")
+    print("  change_shape       - Change shape of an object (cube/sphere/cylinder)")
+    print("  change_size        - Change size of an object (small/large)")
+    print("  change_material    - Change material of an object (metal/rubber)")
+    print("  change_position    - Move an object to a different location")
+    print("  add_object         - Add a new random object")
+    print("  swap_attribute     - Swap colors between two objects")
+    print("  relational_flip    - Move object from left of X to right of X")
+    print("  remove_object      - Remove a random object")
+    print("  replace_object     - Replace an object with a different one")
+    
+    print("\nNEGATIVE COUNTERFACTUALS (Should NOT change VQA answers):")
+    print("  change_background  - Change background/ground color")
+    print("  change_lighting    - Change lighting conditions")
+    print("  add_noise          - Add image noise/grain")
+    print("  occlusion_change   - Move object to partially hide another")
+    print("  apply_fisheye      - Apply fisheye lens distortion")
+    print("  apply_blur         - Apply Gaussian blur")
+    print("  apply_vignette     - Apply vignette (edge darkening)")
+    print("  apply_chromatic_aberration - Apply chromatic aberration (color fringing)")
+    
+    print("\n" + "="*70)
+    print("\nUsage examples:")
+    print("  # Use specific types")
+    print("  python pipeline.py --num_scenes 10 --cf_types change_color change_position")
+    print("  ")
+    print("  # Mix image and negative CFs")
+    print("  python pipeline.py --num_scenes 10 --cf_types change_shape change_lighting")
+    print("  ")
+    print("  # Only negative CFs")
+    print("  python pipeline.py --num_scenes 10 --cf_types change_background add_noise")
+    print("="*70 + "\n")
+
+def find_scene_files(scenes_dir):
+    scene_files = glob.glob(os.path.join(scenes_dir, 'scene_*.json'))
+    scene_sets = {}
+    
+    for scene_file in scene_files:
+        basename = os.path.basename(scene_file)
+        parts = basename.replace('.json', '').split('_')
+        if len(parts) >= 3:
+            scene_num = int(parts[1])
+            variant = '_'.join(parts[2:])
+
+            if scene_num not in scene_sets:
+                scene_sets[scene_num] = {}
+            scene_sets[scene_num][variant] = scene_file
+    
+    return scene_sets
+
+def render_existing_scenes(args):
+    import json
+
+    if args.run_dir:
+        run_dir = args.run_dir
+    elif args.run_name:
+        run_dir = os.path.join(args.output_dir, args.run_name)
+    elif args.auto_latest:
+        if not os.path.exists(args.output_dir):
+            print(f"ERROR: Output directory does not exist: {args.output_dir}")
+            return
+        
+        subdirs = [d for d in os.listdir(args.output_dir) 
+                  if os.path.isdir(os.path.join(args.output_dir, d))]
+        if not subdirs:
+            print(f"ERROR: No run directories found in {args.output_dir}")
+            return
+
+        dirs_with_time = [(d, os.path.getmtime(os.path.join(args.output_dir, d))) 
+                         for d in subdirs]
+        latest = max(dirs_with_time, key=lambda x: x[1])[0]
+        run_dir = os.path.join(args.output_dir, latest)
+        print(f"Using latest run: {run_dir}")
+    else:
+        print("ERROR: Must specify --run_dir, --run_name, or --auto_latest for --render_only")
+        return
+    
+    if not os.path.exists(run_dir):
+        print(f"ERROR: Run directory does not exist: {run_dir}")
+        return
+    
+    scenes_dir = os.path.join(run_dir, 'scenes')
+    images_dir = os.path.join(run_dir, 'images')
+    
+    if not os.path.exists(scenes_dir):
+        print(f"ERROR: Scenes directory does not exist: {scenes_dir}")
+        return
+
+    os.makedirs(images_dir, exist_ok=True)
+
+    blender_path = args.blender_path or find_blender()
+    print(f"Using Blender: {blender_path}")
+
+    print("\nPreparing render scripts...")
+    create_patched_render_script()
+
+    scene_sets = find_scene_files(scenes_dir)
+    total_scenes = len(scene_sets)
+    
+    if total_scenes == 0:
+        print(f"ERROR: No scene JSON files found in {scenes_dir}")
+        return
+    
+    print(f"\nFound {total_scenes} scene sets to render")
+
+    checkpoint_file = os.path.join(run_dir, 'render_checkpoint.json')
+
+    completed_scenes = set()
+    if args.resume:
+        completed_scenes = load_checkpoint(checkpoint_file)
+        rendered_scenes = get_completed_scenes_from_folder(images_dir)
+        completed_scenes.update(rendered_scenes)
+        
+        if completed_scenes:
+            print(f"\n[RESUME] Found {len(completed_scenes)} already rendered scenes")
+    
+    print("\n" + "="*70)
+    print(f"RENDERING {total_scenes} SCENE SETS")
+    print("="*70)
+    
+    successful_renders = 0
+    
+    for scene_num in sorted(scene_sets.keys()):
+        if scene_num in completed_scenes:
+            print(f"\n[SKIP] Skipping scene {scene_num} (already rendered)")
+            successful_renders += 1
+            continue
+        
+        print(f"\n{'='*70}")
+        print(f"SCENE SET {scene_num+1}/{total_scenes} (Scene #{scene_num})")
+        print(f"{'='*70}")
+        
+        scene_set = scene_sets[scene_num]
+        total_to_render = len(scene_set)
+        render_success = 0
+        
+        for variant, scene_file in scene_set.items():
+            scene_prefix = f"scene_{scene_num:04d}"
+            image_file = os.path.join(images_dir, f"{scene_prefix}_{variant}.png")
+            
+            print(f"  Rendering {variant}...")
+            if render_scene(blender_path, scene_file, image_file, 
+                          args.use_gpu, args.samples, args.width, args.height):
+                render_success += 1
+                print(f"    [OK] {variant}")
+            else:
+                print(f"    [FAILED] {variant}")
+        
+            if render_success == total_to_render:
+                successful_renders += 1
+                completed_scenes.add(scene_num)
+                save_checkpoint(checkpoint_file, list(completed_scenes))
+        
+        print(f"  [OK] Rendered {render_success}/{total_to_render} images")
+
+    metadata_path = os.path.join(run_dir, 'run_metadata.json')
+    if os.path.exists(metadata_path):
+        with open(metadata_path, 'r') as f:
+            metadata = json.load(f)
+        metadata['successful_renders'] = successful_renders
+        metadata['rendered_timestamp'] = datetime.now().isoformat()
+        with open(metadata_path, 'w') as f:
+            json.dump(metadata, f, indent=2)
+
+    print("\n" + "="*70)
+    print("RENDERING COMPLETE")
+    print("="*70)
+    print(f"Run directory: {run_dir}")
+    print(f"Successfully rendered: {successful_renders}/{total_scenes} scene sets")
+    print(f"\nOutput:")
+    print(f"  Images: {images_dir}/")
+    print(f"  Checkpoint: {checkpoint_file}")
+    print("="*70)
+
+def is_running_on_huggingface():
+    return (
+        os.environ.get('SPACES_REPO_TYPE') is not None or
+        os.environ.get('SPACES_REPO_ID') is not None or
+        os.environ.get('SPACE_ID') is not None or
+        os.environ.get('HF_HOME') is not None or
+        'huggingface' in str(os.environ.get('PATH', '')).lower() or
+        os.path.exists('/.dockerenv')
+    )
+
+def create_downloadable_archive(run_dir, output_zip_path=None):
+    if not is_running_on_huggingface():
+        return None
+    
+    if not os.path.exists(run_dir):
+        print(f"Warning: Run directory does not exist: {run_dir}")
+        return None
+    
+    if output_zip_path is None:
+        run_name = os.path.basename(run_dir)
+        output_zip_path = os.path.join(os.path.dirname(os.path.dirname(run_dir)) if 'output' in run_dir else '.', f"{run_name}.zip")
+        output_zip_path = os.path.abspath(output_zip_path)
+    
+    print(f"\n[ARCHIVE] Creating downloadable archive: {output_zip_path}")
+    print(f"   (This file will be available in the Files tab)")
+    
+    try:
+        with zipfile.ZipFile(output_zip_path, 'w', zipfile.ZIP_DEFLATED) as zipf:
+            for root, dirs, files in os.walk(run_dir):
+                dirs[:] = [d for d in dirs if not d.startswith('.')]
+                
+                for file in files:
+                    if file.startswith('.'):
+                        continue
+                    
+                    file_path = os.path.join(root, file)
+                    arcname = os.path.relpath(file_path, os.path.dirname(run_dir))
+                    zipf.write(file_path, arcname)
+        
+        zip_size = os.path.getsize(output_zip_path) / (1024 * 1024)
+        print(f"[OK] Archive created successfully ({zip_size:.2f} MB)")
+        print(f"  File location: {os.path.abspath(output_zip_path)}")
+        print(f"  To download: Go to the 'Files' tab in your Hugging Face Space and download '{os.path.basename(output_zip_path)}'")
+        return output_zip_path
+    except Exception as e:
+        print(f"[WARNING] Could not create archive: {e}")
+        return None
+
+def save_run_metadata(run_dir, args, successful_scenes, successful_renders):
+    metadata = {
+        'timestamp': datetime.now().isoformat(),
+        'run_directory': run_dir,
+        'arguments': {
+            'num_scenes': args.num_scenes,
+            'num_objects': args.num_objects,
+            'min_objects': args.min_objects,
+            'max_objects': args.max_objects,
+            'num_counterfactuals': args.num_counterfactuals,
+            'use_gpu': args.use_gpu,
+            'samples': args.samples,
+            'width': args.width,
+            'height': args.height,
+            'cf_types': args.cf_types if args.cf_types else 'default (1 image + 1 negative)',
+            'semantic_only': getattr(args, 'semantic_only', False),
+            'negative_only': getattr(args, 'negative_only', False),
+            'min_cf_change_score': args.min_cf_change_score,
+            'max_cf_attempts': args.max_cf_attempts,
+        },
+        
+        'results': {
+            'scenes_generated': successful_scenes,
+            'scenes_rendered': successful_renders,
+            'total_images': successful_renders * (args.num_counterfactuals + 1) if not args.skip_render else 0,
+        },
+        'cf_types_used': args.cf_types if args.cf_types else list(COUNTERFACTUAL_TYPES.keys())
+    }
+    
+    metadata_path = os.path.join(run_dir, 'run_metadata.json')
+    with open(metadata_path, 'w') as f:
+        json.dump(metadata, f, indent=2)
+    
+    print(f"\n[OK] Saved run metadata to: {metadata_path}")
+
+
+def regenerate_scene_sets(args):
+    run_dir = os.path.join(args.output_dir, args.run_name)
+    if not os.path.exists(run_dir):
+        print(f"ERROR: Run directory does not exist: {run_dir}")
+        return
+    
+    metadata_path = os.path.join(run_dir, 'run_metadata.json')
+    if not os.path.exists(metadata_path):
+        print(f"ERROR: run_metadata.json not found in {run_dir}. Cannot determine original settings.")
+        return
+    
+    with open(metadata_path, 'r') as f:
+        metadata = json.load(f)
+    meta_args = metadata.get('arguments', {})
+    
+    scenes_dir = os.path.join(run_dir, 'scenes')
+    images_dir = os.path.join(run_dir, 'images')
+    os.makedirs(scenes_dir, exist_ok=True)
+    os.makedirs(images_dir, exist_ok=True)
+    
+    blender_path = args.blender_path or find_blender()
+    print(f"Using Blender: {blender_path}")
+    print("\nPreparing scripts...")
+    create_patched_render_script()
+    
+    scene_indices = sorted(set(args.regenerate))
+    num_counterfactuals = meta_args.get('num_counterfactuals', 2)
+    cf_types = meta_args.get('cf_types')
+    if isinstance(cf_types, list) and cf_types:
+        pass
+    else:
+        cf_types = None
+    
+    use_gpu = meta_args.get('use_gpu', 0)
+    samples = meta_args.get('samples', 512)
+    width = meta_args.get('width', 320)
+    height = meta_args.get('height', 240)
+    
+    print(f"\n{'='*70}")
+    print(f"REGENERATING {len(scene_indices)} SCENE SETS: {scene_indices}")
+    print(f"{'='*70}")
+    
+    temp_run_id = os.path.basename(run_dir)
+    checkpoint_file = os.path.join(run_dir, 'checkpoint.json')
+    completed_scenes = load_checkpoint(checkpoint_file)
+    
+    for i in scene_indices:
+        print(f"\n{'='*70}")
+        print(f"REGENERATING SCENE SET #{i}")
+        print(f"{'='*70}")
+        
+        num_objects = meta_args.get('num_objects')
+        if num_objects is None:
+            min_objs = meta_args.get('min_objects', 3)
+            max_objs = meta_args.get('max_objects', 7)
+            num_objects = random.randint(min_objs, max_objs)
+        
+        base_scene = None
+        for retry in range(3):
+            base_scene = generate_base_scene(num_objects, blender_path, i, temp_run_dir=temp_run_id)
+            if base_scene and len(base_scene.get('objects', [])) > 0:
+                break
+            print(f"  Retry {retry + 1}/3...")
+        
+        if not base_scene or len(base_scene.get('objects', [])) == 0:
+            print(f"  [FAILED] Could not generate base scene for #{i}")
+            continue
+        
+        min_cf_score = meta_args.get('min_cf_change_score', 1.0)
+        max_cf_attempts = meta_args.get('max_cf_attempts', 10)
+        min_noise = meta_args.get('min_noise_level', 'light')
+        
+        counterfactuals = generate_counterfactuals(
+            base_scene,
+            num_counterfactuals,
+            cf_types=cf_types,
+            same_cf_type=meta_args.get('same_cf_type', False),
+            min_change_score=min_cf_score,
+            max_cf_attempts=max_cf_attempts,
+            min_noise_level=min_noise,
+            semantic_only=meta_args.get('semantic_only', False),
+            negative_only=meta_args.get('negative_only', False)
+        )
+        
+        for idx, cf in enumerate(counterfactuals):
+            print(f"    CF{idx+1} [{cf.get('cf_category', '?')}] ({cf.get('type', '?')}): {cf.get('description', '')}")
+        
+        scene_prefix = f"scene_{i:04d}"
+        scene_paths = {'original': os.path.join(scenes_dir, f"{scene_prefix}_original.json")}
+        image_paths = {'original': os.path.join(images_dir, f"{scene_prefix}_original.png")}
+        
+        base_scene['cf_metadata'] = {
+            'variant': 'original', 'is_counterfactual': False, 'cf_index': None,
+            'cf_category': 'original', 'cf_type': None, 'cf_description': None, 'source_scene': scene_prefix,
+        }
+        save_scene(base_scene, scene_paths['original'])
+        
+        for idx, cf in enumerate(counterfactuals):
+            cf_name = f"cf{idx+1}"
+            scene_paths[cf_name] = os.path.join(scenes_dir, f"{scene_prefix}_{cf_name}.json")
+            image_paths[cf_name] = os.path.join(images_dir, f"{scene_prefix}_{cf_name}.png")
+            cf_scene = cf['scene']
+            cf_scene['cf_metadata'] = {
+                'variant': cf_name, 'is_counterfactual': True, 'cf_index': idx + 1,
+                'cf_category': cf.get('cf_category', 'unknown'), 'cf_type': cf.get('type', None),
+                'cf_description': cf.get('description', None), 'change_score': cf.get('change_score'),
+                'change_attempts': cf.get('change_attempts'), 'source_scene': scene_prefix,
+            }
+            save_scene(cf_scene, scene_paths[cf_name])
+        
+        print(f"  [OK] Saved {len(counterfactuals) + 1} scene files")
+        
+        if not args.skip_render:
+            print("  Rendering...")
+            render_success = 0
+            for scene_type, scene_path in scene_paths.items():
+                if render_scene(blender_path, scene_path, image_paths[scene_type],
+                               use_gpu, samples, width, height):
+                    render_success += 1
+                    print(f"    [OK] {scene_type}")
+            print(f"  [OK] Rendered {render_success}/{len(scene_paths)} images")
+            completed_scenes.add(i)
+    
+    save_checkpoint(checkpoint_file, list(completed_scenes))
+    
+    temp_run_path = os.path.join(os.getcwd(), 'temp_output', temp_run_id)
+    if os.path.exists(temp_run_path):
+        shutil.rmtree(temp_run_path)
+    if os.path.exists('render_images_patched.py'):
+        try:
+            os.remove('render_images_patched.py')
+        except Exception:
+            pass
+    
+    print(f"\n{'='*70}")
+    print("REGENERATION COMPLETE")
+    print(f"{'='*70}")
+    print(f"Regenerated {len(scene_indices)} scene sets: {scene_indices}")
+    print(f"Run directory: {run_dir}")
+    
+    if args.generate_questions:
+        if generate_mapping_with_questions is None:
+            print("\n[WARNING] Questions module not found. Skipping CSV generation.")
+        else:
+            print("\nRegenerating questions CSV...")
+            try:
+                generate_mapping_with_questions(
+                    run_dir, args.csv_name, generate_questions=True,
+                    strict_question_validation=not getattr(args, 'no_strict_validation', False)
+                )
+                print(f"[OK] CSV saved to: {os.path.join(run_dir, args.csv_name)}")
+            except Exception as e:
+                print(f"[ERROR] Questions: {e}")
+                import traceback
+                traceback.print_exc()
+
+
+def filter_same_answer_scenes(run_dir, csv_filename):
+    """Remove CSV rows where CF1 or CF2 answer matches original; delete those scenes' images and scene JSONs."""
+    csv_path = os.path.join(run_dir, csv_filename)
+    if not os.path.isfile(csv_path):
+        return
+    with open(csv_path, 'r', encoding='utf-8') as f:
+        reader = csv.reader(f)
+        header = next(reader)
+        try:
+            idx_orig_ans = header.index('original_image_answer_to_original_question')
+            idx_cf1_ans = header.index('cf1_image_answer_to_cf1_question')
+            idx_cf2_ans = header.index('cf2_image_answer_to_cf2_question')
+            idx_orig_img = header.index('original_image')
+        except ValueError:
+            return
+    kept_rows = [header]
+    removed_scene_ids = set()
+    with open(csv_path, 'r', encoding='utf-8') as f:
+        reader = csv.reader(f)
+        next(reader)
+        for row in reader:
+            if len(row) <= max(idx_orig_ans, idx_cf1_ans, idx_cf2_ans, idx_orig_img):
+                kept_rows.append(row)
+                continue
+            o = str(row[idx_orig_ans]).strip().lower()
+            c1 = str(row[idx_cf1_ans]).strip().lower()
+            c2 = str(row[idx_cf2_ans]).strip().lower()
+            if o == c1 or o == c2:
+                orig_img = row[idx_orig_img]
+                if orig_img.endswith('_original.png'):
+                    scene_id = orig_img.replace('_original.png', '')
+                    removed_scene_ids.add(scene_id)
+                continue
+            kept_rows.append(row)
+    if not removed_scene_ids:
+        return
+    with open(csv_path, 'w', newline='', encoding='utf-8') as f:
+        writer = csv.writer(f, quoting=csv.QUOTE_ALL)
+        writer.writerows(kept_rows)
+    images_dir = os.path.join(run_dir, 'images')
+    scenes_dir = os.path.join(run_dir, 'scenes')
+    deleted = 0
+    for scene_id in removed_scene_ids:
+        for suffix in ('_original', '_cf1', '_cf2'):
+            for d, ext in [(images_dir, '.png'), (scenes_dir, '.json')]:
+                if not os.path.isdir(d):
+                    continue
+                fn = scene_id + suffix + ext
+                fp = os.path.join(d, fn)
+                if os.path.isfile(fp):
+                    try:
+                        os.remove(fp)
+                        deleted += 1
+                    except OSError:
+                        pass
+    print(f"\n[OK] Filtered {len(removed_scene_ids)} scenes where answers matched; removed {deleted} files. CSV now has {len(kept_rows) - 1} rows.")
+
+
+def main():
+    script_dir = os.path.dirname(os.path.abspath(__file__))
+    os.chdir(script_dir)
+    
+    parser = argparse.ArgumentParser(description='Generate and render multiple CLEVR scene sets with diverse counterfactuals and resume support')
+    parser.add_argument('--num_scenes', type=int, default=5,
+                       help='Number of scene sets to generate')
+    parser.add_argument('--num_objects', type=int, default=None,
+                       help='Fixed number of objects per scene')
+    parser.add_argument('--min_objects', type=int, default=3,
+                       help='Minimum objects per scene (if num_objects not set)')
+    parser.add_argument('--max_objects', type=int, default=7,
+                       help='Maximum objects per scene (if num_objects not set)')
+    parser.add_argument('--num_counterfactuals', type=int, default=2,
+                       help='Number of counterfactual variants per scene (default: 2 = 1 Image CF + 1 Negative CF)')
+    parser.add_argument('--blender_path', default=None,
+                       help='Path to Blender executable')
+    parser.add_argument('--output_dir', default='output',
+                       help='Base output directory')
+    parser.add_argument('--run_name', default=None,
+                       help='Optional name for this run (required for resume)')
+    parser.add_argument('--resume', action='store_true',
+                       help='Resume from last checkpoint (requires --run_name)')
+    parser.add_argument('--use_gpu', type=int, default=0,
+                       help='Use GPU rendering (0 or 1)')
+    parser.add_argument('--samples', type=int, default=512,
+                       help='Number of render samples')
+    parser.add_argument('--width', type=int, default=320,
+                       help='Image width in pixels (default: 320)')
+    parser.add_argument('--height', type=int, default=240,
+                       help='Image height in pixels (default: 240)')
+    parser.add_argument('--skip_render', action='store_true',
+                       help='Only generate scenes, skip rendering')
+    parser.add_argument('--render_only', action='store_true',
+                       help='Only render existing scene JSON files. Requires --run_dir, --run_name, or --auto_latest')
+    parser.add_argument('--run_dir', type=str, default=None,
+                       help='Run directory containing scenes/ folder (for --render_only mode)')
+    parser.add_argument('--auto_latest', action='store_true',
+                       help='Automatically use the latest run in output_dir (for --render_only mode)')
+    parser.add_argument('--cf_types', nargs='+', 
+                   choices=[
+                       'change_color', 'change_shape', 'change_size', 
+                       'change_material', 'change_position', 
+                       'add_object', 'remove_object', 'replace_object',
+                       'swap_attribute', 'occlusion_change', 'relational_flip',
+                       'change_background', 
+                       'change_lighting', 'add_noise',
+                       'apply_fisheye', 'apply_blur', 'apply_vignette', 'apply_chromatic_aberration'
+                   ],
+                   help='Specific counterfactual types to use (if not specified, uses default: 1 image CF + 1 negative CF)')
+    parser.add_argument('--semantic_only', action='store_true',
+                   help='Generate only Semantic/Image counterfactuals (e.g. Change Color, Add Object); no Negative CFs')
+    parser.add_argument('--negative_only', action='store_true',
+                   help='Generate only Negative counterfactuals (e.g. Change Lighting, Add Noise, Occlusion Change); no Semantic CFs')
+    parser.add_argument('--same_cf_type', action='store_true',
+                   help='Use the same counterfactual type for all variants (first in --cf_types, or one random type if --cf_types not set)')
+    parser.add_argument('--min_cf_change_score', type=float, default=1.0,
+                   help='Minimum heuristic change score for a counterfactual to be accepted (retries until met). Increase for more noticeable CFs.')
+    parser.add_argument('--max_cf_attempts', type=int, default=10,
+                   help='Max retries per counterfactual type to meet --min_cf_change_score (default: 10)')
+    parser.add_argument('--min_noise_level', type=str, default='light',
+                   choices=['light', 'medium', 'heavy'],
+                   help='Minimum noise level when using add_noise counterfactual (default: light)')
+
+    parser.add_argument('--list_cf_types', action='store_true',
+                   help='List all available counterfactual types and exit')
+    
+    parser.add_argument('--generate_questions', action='store_true',
+                       help='Create questions and answers CSV after rendering completes')
+    parser.add_argument('--filter_same_answer', action='store_true',
+                       help='After generating questions, remove scenes where CF1 or CF2 answer matches original (delete those rows and their image/scene files). Use with --generate_questions.')
+    parser.add_argument('--csv_name', default='image_mapping_with_questions.csv',
+                       help='Output CSV filename (default: image_mapping_with_questions.csv)')
+    parser.add_argument('--no_strict_validation', action='store_true',
+                       help='Disable strict question validation (Semantic-Valid / Negative-Valid); use legacy accept logic when generating questions CSV')
+    parser.add_argument('--regenerate', nargs='+', type=int, metavar='N',
+                       help='Regenerate specific scene sets by index (e.g. --regenerate 63 83 272). Requires --run_name. Uses settings from run_metadata.json.')
+    
+    args = parser.parse_args()
+
+    if args.list_cf_types:
+        list_counterfactual_types()
+        return
+    
+    if args.render_only:
+        render_existing_scenes(args)
+        return
+    
+    if args.resume and not args.run_name:
+        print("ERROR: --run_name is required when using --resume")
+        return
+    
+    if args.regenerate is not None:
+        if not args.run_name:
+            print("ERROR: --run_name is required when using --regenerate")
+            return
+        regenerate_scene_sets(args)
+        return
+
+    blender_path = args.blender_path or find_blender()
+    print(f"Using Blender: {blender_path}")
+    
+    print("\nPreparing scripts...")
+    create_patched_render_script()
+    run_dir = create_run_directory(args.output_dir, args.run_name)
+    temp_run_id = os.path.basename(run_dir)
+    print(f"\n{'='*70}")
+    print(f"RUN DIRECTORY: {run_dir}")
+    print(f"{'='*70}")
+
+    scenes_dir = os.path.join(run_dir, 'scenes')
+    images_dir = os.path.join(run_dir, 'images')
+    os.makedirs(scenes_dir, exist_ok=True)
+    os.makedirs(images_dir, exist_ok=True)
+
+    checkpoint_file = os.path.join(run_dir, 'checkpoint.json')
+
+    completed_scenes = set()
+    if args.resume:
+        completed_scenes = load_checkpoint(checkpoint_file)
+        rendered_scenes = get_completed_scenes_from_folder(images_dir)
+        completed_scenes.update(rendered_scenes)
+        
+        if completed_scenes:
+            print(f"\n[RESUME] Found {len(completed_scenes)} already completed scenes")
+            print(f"   Completed: {sorted(completed_scenes)}")
+            print(f"   Will generate scenes: {args.num_scenes}")
+            print(f"   Remaining: {args.num_scenes - len(completed_scenes)}")
+        else:
+            print("\n[WARNING] Resume flag set but no checkpoint found, starting fresh")
+
+    print("\n" + "="*70)
+    print(f"GENERATING {args.num_scenes} SCENE SETS")
+    print(f"Each with {args.num_counterfactuals} counterfactual variants")
+    print(f"Available CF types: {len(COUNTERFACTUAL_TYPES)}")
+    print("="*70)
+    
+    successful_scenes = 0
+    successful_renders = 0
+    
+    for i in range(args.num_scenes):
+        if i in completed_scenes:
+            print(f"\n[SKIP] Skipping scene {i} (already completed)")
+            successful_scenes += 1
+            successful_renders += 1
+            continue
+        
+        print(f"\n{'='*70}")
+        print(f"SCENE SET {i+1}/{args.num_scenes} (Scene #{i})")
+        print(f"{'='*70}")
+        
+        if args.num_objects is not None:
+            num_objects = args.num_objects
+        else:
+            num_objects = random.randint(args.min_objects, args.max_objects)
+        
+        base_scene = None
+        for retry in range(3):
+            base_scene = generate_base_scene(num_objects, blender_path, i, temp_run_dir=temp_run_id)
+            if base_scene and len(base_scene['objects']) > 0:
+                break
+            print(f"  Retry {retry + 1}/3...")
+        
+        if not base_scene or len(base_scene['objects']) == 0:
+            print(f"  [FAILED] Failed to generate scene {i+1}")
+            continue
+        
+        successful_scenes += 1
+        
+        print(f"  Creating {args.num_counterfactuals} counterfactuals...")
+        counterfactuals = generate_counterfactuals(
+            base_scene,
+            args.num_counterfactuals,
+            cf_types=args.cf_types,
+            same_cf_type=args.same_cf_type,
+            min_change_score=args.min_cf_change_score,
+            max_cf_attempts=args.max_cf_attempts,
+            min_noise_level=args.min_noise_level,
+            semantic_only=args.semantic_only,
+            negative_only=args.negative_only
+        )
+        
+        for idx, cf in enumerate(counterfactuals):
+            cf_cat = cf.get('cf_category', 'unknown')
+            print(f"    CF{idx+1} [{cf_cat}] ({cf['type']}): {cf['description']}")
+        
+        scene_prefix = f"scene_{i:04d}"
+        scene_paths = {'original': os.path.join(scenes_dir, f"{scene_prefix}_original.json")}
+        image_paths = {'original': os.path.join(images_dir, f"{scene_prefix}_original.png")}
+
+        base_scene['cf_metadata'] = {
+            'variant': 'original',
+            'is_counterfactual': False,
+            'cf_index': None,
+            'cf_category': 'original',
+            'cf_type': None,
+            'cf_description': None,
+            'source_scene': scene_prefix,
+        }
+        save_scene(base_scene, scene_paths['original'])
+        
+        for idx, cf in enumerate(counterfactuals):
+            cf_name = f"cf{idx+1}"
+            scene_paths[cf_name] = os.path.join(scenes_dir, f"{scene_prefix}_{cf_name}.json")
+            image_paths[cf_name] = os.path.join(images_dir, f"{scene_prefix}_{cf_name}.png")
+
+            cf_scene = cf['scene']
+            cf_scene['cf_metadata'] = {
+                'variant': cf_name,
+                'is_counterfactual': True,
+                'cf_index': idx + 1,
+                'cf_category': cf.get('cf_category', 'unknown'),
+                'cf_type': cf.get('type', None),
+                'cf_description': cf.get('description', None),
+                'change_score': cf.get('change_score', None),
+                'change_attempts': cf.get('change_attempts', None),
+                'source_scene': scene_prefix,
+            }
+            save_scene(cf_scene, scene_paths[cf_name])
+        
+        print(f"  [OK] Saved {len(counterfactuals) + 1} scene files")
+        
+        if not args.skip_render:
+            print("  Rendering...")
+            render_success = 0
+            total_to_render = len(counterfactuals) + 1
+            
+            for scene_type, scene_path in scene_paths.items():
+                if render_scene(blender_path, scene_path, image_paths[scene_type], 
+                               args.use_gpu, args.samples, args.width, args.height):
+                    render_success += 1
+                    print(f"    [OK] {scene_type}")
+            
+            if render_success == total_to_render:
+                successful_renders += 1
+                completed_scenes.add(i)
+                save_checkpoint(checkpoint_file, list(completed_scenes))
+            
+            print(f"  [OK] Rendered {render_success}/{total_to_render} images")
+        else:
+            completed_scenes.add(i)
+            save_checkpoint(checkpoint_file, list(completed_scenes))
+    
+    save_run_metadata(run_dir, args, successful_scenes, successful_renders)
+    
+    archive_path = create_downloadable_archive(run_dir)
+    
+    temp_run_path = os.path.join(os.getcwd(), 'temp_output', temp_run_id)
+    if os.path.exists(temp_run_path):
+        shutil.rmtree(temp_run_path)
+    if os.path.exists('render_images_patched.py'):
+        os.remove('render_images_patched.py')
+    
+    print("\n" + "="*70)
+    print("PIPELINE COMPLETE")
+    print("="*70)
+    print(f"Run directory: {run_dir}")
+    print(f"Successfully generated: {successful_scenes}/{args.num_scenes} scene sets")
+    if not args.skip_render:
+        print(f"Successfully rendered: {successful_renders}/{successful_scenes} scene sets")
+    print(f"\nOutput:")
+    print(f"  Scene files: {scenes_dir}/")
+    if not args.skip_render:
+        print(f"  Images: {images_dir}/")
+    print(f"  Metadata: {os.path.join(run_dir, 'run_metadata.json')}")
+    print(f"  Checkpoint: {checkpoint_file}")
+    if archive_path:
+        print(f"\n[ARCHIVE] Downloadable archive created:")
+        print(f"  Filename: {os.path.basename(archive_path)}")
+        print(f"  Location: {os.path.abspath(archive_path)}")
+        print(f"  To download: Go to the 'Files' tab in your Hugging Face Space")
+        print(f"     and look for '{os.path.basename(archive_path)}' in the file list")
+    print(f"\nFile naming: scene_XXXX_original/cf1/cf2/....json/png")
+    if args.cf_types:
+        print(f"\nCounterfactual types requested: {', '.join(args.cf_types)}")
+    else:
+        print("\nCounterfactual types: default (mix of image_cf + negative_cf)")
+    
+    if args.resume and completed_scenes:
+        print(f"\n[OK] Resume successful! Completed {len(completed_scenes)}/{args.num_scenes} scenes total")
+    
+    if args.generate_questions and not args.skip_render:
+        if generate_mapping_with_questions is None:
+            print("\n[WARNING] Questions module not found. Skipping.")
+        else:
+            print("\n" + "="*70)
+            print("QUESTIONS AND ANSWERS")
+            print("="*70)
+            try:
+                generate_mapping_with_questions(
+                    run_dir,
+                    args.csv_name if args.num_counterfactuals != 1 else 'image_mapping_single_cf.csv',
+                    generate_questions=True,
+                    strict_question_validation=not getattr(args, 'no_strict_validation', False),
+                    single_cf_per_row=(args.num_counterfactuals == 1)
+                )
+                csv_used = args.csv_name if args.num_counterfactuals != 1 else 'image_mapping_single_cf.csv'
+                print(f"\n[OK] CSV saved to: {os.path.join(run_dir, csv_used)}")
+                if getattr(args, 'filter_same_answer', False):
+                    filter_same_answer_scenes(run_dir, csv_used)
+            except Exception as e:
+                print(f"\n[ERROR] Questions: {e}")
+                import traceback
+                traceback.print_exc()
+
+if __name__ == '__main__':
+    main()

requirements.txt

@@ -0,0 +1,12 @@
+# Core dependencies
+numpy>=1.24.0
+Pillow>=10.0.0
+
+# Streamlit for UI
+streamlit>=1.28.0
+
+# PyTorch and Hugging Face dependencies
+# Using flexible versions for compatibility with Python 3.13
+torch>=2.0.0
+transformers>=4.35.0
+huggingface_hub>=0.16.4,<0.18

scripts/README.md

@@ -0,0 +1,107 @@
+# Scripts
+
+Utility scripts for working with CLEVR counterfactual scenes.
+
+## Available Scripts
+
+### generate_scenes.py
+Generate scene JSON files with counterfactuals (no rendering).
+
+**Purpose**: Create scene JSON files that can be rendered later.
+
+**Usage:**
+```bash
+# Generate 10 scene sets
+python scripts/generate_scenes.py --num_scenes 10 --num_objects 5 --run_name experiment1
+
+# Resume from checkpoint
+python scripts/generate_scenes.py --num_scenes 100 --run_name experiment1 --resume
+```
+
+**Output**: Scene JSON files in `output/run_name/scenes/`
+
+**Next step**: Use `pipeline.py --render_only` to render these scenes.
+
+**Note**: Alternatively, you can use `pipeline.py --skip_render` instead of this script.
+
+---
+
+### generate_examples.py
+Generate examples of each counterfactual type applied to a base scene. Optionally renders scenes to images.
+
+**Purpose**: Create reference examples demonstrating all counterfactual types.
+
+**Usage:**
+```bash
+# Generate scene JSON files only
+python scripts/generate_examples.py [--output_dir DIR] [--num_objects N]
+
+# Generate and render to images
+python scripts/generate_examples.py --render [--output_dir DIR] [--num_objects N] [--use_gpu 0|1]
+```
+
+**Options:**
+- `--output_dir`: Output directory (default: `output/counterfactual_examples`)
+- `--num_objects`: Number of objects in base scene (default: 5)
+- `--render`: Render scenes to PNG images
+- `--use_gpu`: Use GPU rendering (0 = CPU, 1 = GPU, default: 0)
+
+**Output**: 
+- Scene JSON files for all counterfactual types
+- Optional: PNG images (if `--render` is used)
+
+---
+
+### generate_questions_mapping.py
+Generate CSV mapping with questions and counterfactual questions for scenes.
+
+**Purpose**: Create question-answer datasets for training/evaluation.
+
+**Usage:**
+```bash
+# For a specific run directory
+python scripts/generate_questions_mapping.py --output_dir output/experiment1 --generate_questions
+
+# Auto-detect latest run
+python scripts/generate_questions_mapping.py --output_dir output --auto_latest --generate_questions
+
+# Generate CSV with scene_id and links (relative paths)
+python scripts/generate_questions_mapping.py --output_dir output/experiment1 --generate_questions --with_links
+
+# Generate CSV with scene_id and full URLs
+python scripts/generate_questions_mapping.py --output_dir output/experiment1 --generate_questions --with_links --base_url https://example.com/dataset
+```
+
+**Options:**
+- `--output_dir`: Run directory or base output directory (default: `output`)
+- `--auto_latest`: Automatically find and use the latest run in output_dir
+- `--csv_name`: Output CSV filename (default: `image_mapping_with_questions.csv`)
+- `--generate_questions`: Generate questions and answers for each scene set
+- `--with_links`: Include scene_id and image/scene link columns (for URLs or file paths)
+- `--base_url`: Base URL for links (e.g., `https://example.com`). If not provided, uses relative paths like `images/filename.png`
+
+**Output**: CSV files with question-answer mappings
+
+---
+
+
+## Main Pipeline
+
+For production use (generating large datasets), use the main pipeline script:
+
+```bash
+python pipeline.py --num_scenes 100 --num_objects 5 --run_name my_experiment
+```
+
+See the main `README.md` for full documentation of the production pipeline.
+
+---
+
+## Script Summary
+
+| Script | Purpose | When to Use |
+|--------|---------|-------------|
+| `generate_scenes.py` | Generate scene JSON files | Generate scenes separately (alternative to `pipeline.py --skip_render`) |
+| `generate_examples.py` | Generate reference examples | Creating demonstrations, testing counterfactuals |
+| `generate_questions_mapping.py` | Create QA datasets | Preparing training/evaluation data |
+| `pipeline.py` | Combined generation + rendering | Main entry point. Supports `--skip_render` and `--render_only` modes |

scripts/__pycache__/generate_questions_mapping.cpython-312.pyc

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

scripts/generate_examples.py

@@ -0,0 +1,218 @@
+#!/usr/bin/env python3
+
+import json
+import os
+import sys
+import copy
+import argparse
+from pathlib import Path
+
+script_dir = os.path.dirname(os.path.abspath(__file__))
+project_root = os.path.dirname(script_dir)
+sys.path.insert(0, project_root)
+
+from pipeline import (
+    generate_base_scene,
+    find_blender,
+    create_patched_utils,
+    create_patched_render_script,
+    create_render_from_json_script,
+    save_scene,
+    render_scene,
+    IMAGE_COUNTERFACTUALS,
+    NEGATIVE_COUNTERFACTUALS,
+    COUNTERFACTUAL_TYPES
+)
+
+def generate_all_counterfactual_examples(output_dir='output/counterfactual_examples',
+                                        num_objects=5,
+                                        render=False,
+                                        use_gpu=0):
+    print("="*70)
+    print("GENERATING COUNTERFACTUAL EXAMPLES")
+    print("="*70)
+    
+    script_dir = os.path.dirname(os.path.abspath(__file__))
+    project_root = os.path.dirname(script_dir)
+    if not os.path.isabs(output_dir):
+        output_dir = os.path.join(project_root, output_dir)
+    
+    os.makedirs(output_dir, exist_ok=True)
+    scenes_dir = os.path.join(output_dir, 'scenes')
+    images_dir = os.path.join(output_dir, 'images') if render else None
+    if render:
+        os.makedirs(images_dir, exist_ok=True)
+    os.makedirs(scenes_dir, exist_ok=True)
+
+    blender_path = find_blender()
+    create_patched_utils()
+    create_patched_render_script()
+    if render:
+        create_render_from_json_script()
+    
+    print(f"\n1. Generating base scene with {num_objects} objects...")
+    base_scene = None
+    for retry in range(3):
+        base_scene = generate_base_scene(num_objects, blender_path, 0)
+        if base_scene and len(base_scene.get('objects', [])) > 0:
+            break
+        print(f"  Retry {retry + 1}/3...")
+    
+    if not base_scene or len(base_scene.get('objects', [])) == 0:
+        print("ERROR: Failed to generate base scene")
+        return
+
+    original_path = os.path.join(scenes_dir, '00_original.json')
+    save_scene(base_scene, original_path)
+    print(f"  [OK] Saved original scene: {original_path}")
+
+    if render:
+        original_image = os.path.join(images_dir, '00_original.png')
+        print(f"  Rendering original scene...")
+        render_scene(blender_path, original_path, original_image, use_gpu=use_gpu)
+        if os.path.exists(original_image):
+            print(f"  [OK] Rendered: 00_original.png")
+
+    all_cf_types = {**IMAGE_COUNTERFACTUALS, **NEGATIVE_COUNTERFACTUALS}
+    total_cfs = len(all_cf_types)
+    
+    print(f"\n2. Generating {total_cfs} counterfactual examples...")
+
+    image_cf_index = 1
+    for cf_type, cf_func in sorted(IMAGE_COUNTERFACTUALS.items()):
+        print(f"\n  [Image CF {image_cf_index}/{len(IMAGE_COUNTERFACTUALS)}] Applying: {cf_type}")
+
+        try:
+            cf_scene, description = cf_func(copy.deepcopy(base_scene))
+
+            cf_scene['cf_metadata'] = {
+                'variant': f'image_cf_{image_cf_index}',
+                'is_counterfactual': True,
+                'cf_index': image_cf_index,
+                'cf_category': 'image_cf',
+                'cf_type': cf_type,
+                'cf_description': description,
+                'source_scene': '00_original'
+            }
+
+            filename = f"01_image_{image_cf_index:02d}_{cf_type}.json"
+            cf_path = os.path.join(scenes_dir, filename)
+            
+            save_scene(cf_scene, cf_path)
+            print(f"    [OK] Saved: {filename}")
+            print(f"      Description: {description}")
+
+            if render:
+                cf_image = os.path.join(images_dir, filename.replace('.json', '.png'))
+                render_scene(blender_path, cf_path, cf_image, use_gpu=use_gpu)
+                if os.path.exists(cf_image):
+                    print(f"    [OK] Rendered: {filename.replace('.json', '.png')}")
+
+            image_cf_index += 1
+            
+        except Exception as e:
+            print(f"    [ERROR] ERROR applying {cf_type}: {e}")
+            import traceback
+            traceback.print_exc()
+            continue
+
+    negative_cf_index = 1
+    for cf_type, cf_func in sorted(NEGATIVE_COUNTERFACTUALS.items()):
+        print(f"\n  [Negative CF {negative_cf_index}/{len(NEGATIVE_COUNTERFACTUALS)}] Applying: {cf_type}")
+
+        try:
+            if cf_type == 'add_noise':
+                cf_scene, description = cf_func(copy.deepcopy(base_scene), min_noise_level='medium')
+            else:
+                cf_scene, description = cf_func(copy.deepcopy(base_scene))
+
+            cf_scene['cf_metadata'] = {
+                'variant': f'negative_cf_{negative_cf_index}',
+                'is_counterfactual': True,
+                'cf_index': negative_cf_index,
+                'cf_category': 'negative_cf',
+                'cf_type': cf_type,
+                'cf_description': description,
+                'source_scene': '00_original'
+            }
+
+            filename = f"02_negative_{negative_cf_index:02d}_{cf_type}.json"
+            cf_path = os.path.join(scenes_dir, filename)
+            
+            save_scene(cf_scene, cf_path)
+            print(f"    [OK] Saved: {filename}")
+            print(f"      Description: {description}")
+
+            if render:
+                cf_image = os.path.join(images_dir, filename.replace('.json', '.png'))
+                render_scene(blender_path, cf_path, cf_image, use_gpu=use_gpu)
+                if os.path.exists(cf_image):
+                    print(f"    [OK] Rendered: {filename.replace('.json', '.png')}")
+
+            negative_cf_index += 1
+            
+        except Exception as e:
+            print(f"    [ERROR] ERROR applying {cf_type}: {e}")
+            import traceback
+            traceback.print_exc()
+            continue
+
+    summary = {
+        'base_scene': '00_original.json',
+        'total_counterfactuals': len(all_cf_types),
+        'image_counterfactuals': len(IMAGE_COUNTERFACTUALS),
+        'negative_counterfactuals': len(NEGATIVE_COUNTERFACTUALS),
+        'counterfactuals': {}
+    }
+
+    image_cf_index = 1
+    for cf_type in sorted(IMAGE_COUNTERFACTUALS.keys()):
+        filename = f"01_image_{image_cf_index:02d}_{cf_type}.json"
+        summary['counterfactuals'][cf_type] = {
+            'filename': filename,
+            'category': 'image_cf',
+            'index': image_cf_index
+        }
+        image_cf_index += 1
+
+    negative_cf_index = 1
+    for cf_type in sorted(NEGATIVE_COUNTERFACTUALS.keys()):
+        filename = f"02_negative_{negative_cf_index:02d}_{cf_type}.json"
+        summary['counterfactuals'][cf_type] = {
+            'filename': filename,
+            'category': 'negative_cf',
+            'index': negative_cf_index
+        }
+        negative_cf_index += 1
+
+    summary_path = os.path.join(output_dir, 'summary.json')
+    with open(summary_path, 'w') as f:
+        json.dump(summary, f, indent=2)
+    
+    print("\n" + "="*70)
+    print("SUMMARY")
+    print("="*70)
+    print(f"Base scene: {original_path}")
+    print(f"Total counterfactuals generated: {len(all_cf_types)}")
+    print(f"  - Image CFs: {len(IMAGE_COUNTERFACTUALS)}")
+    print(f"  - Negative CFs: {len(NEGATIVE_COUNTERFACTUALS)}")
+    print(f"\nAll files saved to: {output_dir}")
+    print(f"Summary saved to: {summary_path}")
+    if render:
+        print(f"Images saved to: {images_dir}")
+    print("="*70)
+
+if __name__ == '__main__':
+    parser = argparse.ArgumentParser(description='Generate examples of each counterfactual type')
+    parser.add_argument('--output_dir', type=str, default='output/counterfactual_examples',
+                       help='Output directory for examples (default: output/counterfactual_examples)')
+    parser.add_argument('--num_objects', type=int, default=5,
+                       help='Number of objects in base scene (default: 5)')
+    parser.add_argument('--render', action='store_true',
+                       help='Render scenes to images')
+    parser.add_argument('--use_gpu', type=int, default=0,
+                       help='Use GPU rendering (0 = CPU, 1 = GPU, default: 0)')
+    
+    args = parser.parse_args()
+    
+    generate_all_counterfactual_examples(args.output_dir, args.num_objects, args.render, args.use_gpu)

scripts/generate_scenes.py

@@ -0,0 +1,242 @@
+#!/usr/bin/env python3
+
+import sys
+import os
+
+script_dir = os.path.dirname(os.path.abspath(__file__))
+project_root = os.path.dirname(script_dir)
+sys.path.insert(0, project_root)
+
+from pipeline import (
+    find_blender,
+    create_patched_render_script,
+    create_run_directory,
+    generate_base_scene,
+    generate_counterfactuals,
+    save_scene,
+    save_checkpoint,
+    load_checkpoint,
+    get_completed_scenes_from_folder,
+    COUNTERFACTUAL_TYPES,
+    list_counterfactual_types
+)
+import argparse
+import random
+import json
+import shutil
+from datetime import datetime
+
+def main():
+    parser = argparse.ArgumentParser(
+        description='Generate scene JSON files with counterfactuals (no rendering)'
+    )
+    
+    parser.add_argument('--num_scenes', type=int, default=5,
+                       help='Number of scene sets to generate')
+    parser.add_argument('--num_objects', type=int, default=None,
+                       help='Fixed number of objects per scene (overrides min/max)')
+    parser.add_argument('--min_objects', type=int, default=3,
+                       help='Minimum object count (if num_objects not given)')
+    parser.add_argument('--max_objects', type=int, default=7,
+                       help='Maximum object count (if num_objects not given)')
+    parser.add_argument('--num_counterfactuals', type=int, default=2,
+                       help='Number of counterfactual variants per scene')
+    parser.add_argument('--blender_path', type=str, default=None,
+                       help='Path to Blender executable (auto-detected if not provided)')
+    parser.add_argument('--output_dir', type=str, default='output',
+                       help='Base directory for all runs')
+    parser.add_argument('--run_name', type=str, default=None,
+                       help='Optional custom name for this run')
+    parser.add_argument('--resume', action='store_true',
+                       help='Resume from last checkpoint (requires --run_name)')
+    parser.add_argument('--cf_types', nargs='+', 
+                   choices=[
+                       'change_color', 'change_shape', 'change_size', 
+                       'change_material', 'change_position', 
+                       'add_object', 'remove_object', 'swap_attribute', 'occlusion_change', 'relational_flip',
+                       'replace_object',
+                       'change_background', 
+                       'change_lighting', 'add_noise',
+                       'apply_fisheye', 'apply_blur', 'apply_vignette', 'apply_chromatic_aberration'
+                   ],
+                   help='Specific counterfactual types to use')
+    parser.add_argument('--semantic_only', action='store_true',
+                   help='Generate only Semantic/Image counterfactuals (no Negative CFs)')
+    parser.add_argument('--negative_only', action='store_true',
+                   help='Generate only Negative counterfactuals (no Semantic CFs)')
+    parser.add_argument('--same_cf_type', action='store_true',
+                   help='Use the same counterfactual type for all variants')
+    parser.add_argument('--min_cf_change_score', type=float, default=1.0,
+                   help='Minimum heuristic change score for counterfactuals')
+    parser.add_argument('--max_cf_attempts', type=int, default=10,
+                   help='Max retries per counterfactual to meet --min_cf_change_score')
+    parser.add_argument('--min_noise_level', type=str, default='light',
+                   choices=['light', 'medium', 'heavy'],
+                   help='Minimum noise level when using add_noise counterfactual')
+    parser.add_argument('--list_cf_types', action='store_true',
+                   help='List all available counterfactual types and exit')
+    
+    args = parser.parse_args()
+    
+    if args.list_cf_types:
+        list_counterfactual_types()
+        return
+    
+    if args.resume and not args.run_name:
+        print("ERROR: --run_name is required when using --resume")
+        return
+    
+    blender_path = args.blender_path or find_blender()
+    print(f"Using Blender: {blender_path}")
+    
+    print("\nPreparing scripts...")
+    create_patched_render_script()
+    
+    run_dir = create_run_directory(args.output_dir, args.run_name)
+    temp_run_id = os.path.basename(run_dir)
+    print(f"\n{'='*70}")
+    print(f"RUN DIRECTORY: {run_dir}")
+    print(f"{'='*70}")
+
+    scenes_dir = os.path.join(run_dir, 'scenes')
+    os.makedirs(scenes_dir, exist_ok=True)
+    
+    checkpoint_file = os.path.join(run_dir, 'checkpoint.json')
+    
+    completed_scenes = set()
+    if args.resume:
+        completed_scenes = load_checkpoint(checkpoint_file)
+        existing_scenes = get_completed_scenes_from_folder(scenes_dir)
+        completed_scenes.update(existing_scenes)
+        
+        if completed_scenes:
+            print(f"\n[RESUME] Found {len(completed_scenes)} already completed scenes")
+        else:
+            print("\n[WARNING] Resume flag set but no checkpoint found, starting fresh")
+    
+    print("\n" + "="*70)
+    print(f"GENERATING {args.num_scenes} SCENE SETS (JSON ONLY)")
+    print(f"Each with {args.num_counterfactuals} counterfactual variants")
+    print("="*70)
+    
+    successful_scenes = 0
+    
+    for i in range(args.num_scenes):
+        if i in completed_scenes:
+            print(f"\n[SKIP] Skipping scene {i} (already completed)")
+            successful_scenes += 1
+            continue
+        
+        print(f"\n{'='*70}")
+        print(f"SCENE SET {i+1}/{args.num_scenes} (Scene #{i})")
+        print(f"{'='*70}")
+        
+        if args.num_objects is not None:
+            num_objects = args.num_objects
+        else:
+            num_objects = random.randint(args.min_objects, args.max_objects)
+        
+        base_scene = None
+        for retry in range(3):
+            base_scene = generate_base_scene(num_objects, blender_path, i, temp_run_dir=temp_run_id)
+            if base_scene and len(base_scene['objects']) > 0:
+                break
+            print(f"  Retry {retry + 1}/3...")
+        
+        if not base_scene or len(base_scene['objects']) == 0:
+            print(f"  [FAILED] Failed to generate scene {i+1}")
+            continue
+        
+        successful_scenes += 1
+        
+        print(f"  Creating {args.num_counterfactuals} counterfactuals...")
+        counterfactuals = generate_counterfactuals(
+            base_scene,
+            args.num_counterfactuals,
+            cf_types=args.cf_types,
+            same_cf_type=args.same_cf_type,
+            min_change_score=args.min_cf_change_score,
+            max_cf_attempts=args.max_cf_attempts,
+            min_noise_level=args.min_noise_level,
+            semantic_only=args.semantic_only,
+            negative_only=args.negative_only
+        )
+        
+        for idx, cf in enumerate(counterfactuals):
+            cf_cat = cf.get('cf_category', 'unknown')
+            print(f"    CF{idx+1} [{cf_cat}] ({cf['type']}): {cf['description']}")
+        
+        scene_num = i + 1
+        scene_prefix = f"scene_{scene_num:04d}"
+        scene_paths = {'original': os.path.join(scenes_dir, f"{scene_prefix}_original.json")}
+        
+        base_scene['cf_metadata'] = {
+            'variant': 'original',
+            'is_counterfactual': False,
+            'cf_index': None,
+            'cf_category': 'original',
+            'cf_type': None,
+            'cf_description': None,
+            'source_scene': scene_prefix,
+        }
+        save_scene(base_scene, scene_paths['original'])
+        
+        for idx, cf in enumerate(counterfactuals):
+            cf_name = f"cf{idx+1}"
+            scene_paths[cf_name] = os.path.join(scenes_dir, f"{scene_prefix}_{cf_name}.json")
+            
+            cf_scene = cf['scene']
+            cf_scene['cf_metadata'] = {
+                'variant': cf_name,
+                'is_counterfactual': True,
+                'cf_index': idx + 1,
+                'cf_category': cf.get('cf_category', 'unknown'),
+                'cf_type': cf.get('type', None),
+                'cf_description': cf.get('description', None),
+                'change_score': cf.get('change_score', None),
+                'change_attempts': cf.get('change_attempts', None),
+                'source_scene': scene_prefix,
+            }
+            save_scene(cf_scene, scene_paths[cf_name])
+        
+        print(f"  [OK] Saved {len(counterfactuals) + 1} scene files")
+        
+        completed_scenes.add(i)
+        save_checkpoint(checkpoint_file, list(completed_scenes))
+    
+    metadata = {
+        'timestamp': datetime.now().isoformat(),
+        'num_scenes': args.num_scenes,
+        'num_counterfactuals': args.num_counterfactuals,
+        'successful_scenes': successful_scenes,
+        'successful_renders': 0,
+        'cf_types': args.cf_types if args.cf_types else 'default',
+        'semantic_only': args.semantic_only,
+        'negative_only': args.negative_only,
+    }
+    
+    metadata_path = os.path.join(run_dir, 'run_metadata.json')
+    with open(metadata_path, 'w') as f:
+        json.dump(metadata, f, indent=2)
+    
+    temp_run_path = os.path.join(os.getcwd(), 'temp_output', temp_run_id)
+    if os.path.exists(temp_run_path):
+        shutil.rmtree(temp_run_path)
+    if os.path.exists('render_images_patched.py'):
+        os.remove('render_images_patched.py')
+    
+    print("\n" + "="*70)
+    print("SCENE COMPLETE")
+    print("="*70)
+    print(f"Run directory: {run_dir}")
+    print(f"Successfully generated: {successful_scenes}/{args.num_scenes} scene sets")
+    print(f"\nOutput:")
+    print(f"  Scene files: {scenes_dir}/")
+    print(f"  Metadata: {metadata_path}")
+    print(f"  Checkpoint: {checkpoint_file}")
+    print(f"\nNext step: Run 'python pipeline.py --render_only --run_name {args.run_name}' to render these scenes")
+    print("="*70)
+
+if __name__ == '__main__':
+    main()
+

scripts/render.py

@@ -0,0 +1,1204 @@
+from __future__ import print_function
+import math, sys, random, argparse, json, os, tempfile
+from datetime import datetime as dt
+from collections import Counter
+try:
+    from PIL import Image, ImageFilter
+except ImportError:
+    Image = None
+    ImageFilter = None
+
+INSIDE_BLENDER = True
+try:
+  import bpy, bpy_extras
+  from mathutils import Vector
+except ImportError as e:
+  INSIDE_BLENDER = False
+
+def extract_args(input_argv=None):
+  if input_argv is None:
+    input_argv = sys.argv
+  output_argv = []
+  if '--' in input_argv:
+    idx = input_argv.index('--')
+    output_argv = input_argv[(idx + 1):]
+  return output_argv
+
+def parse_args(parser, argv=None):
+  return parser.parse_args(extract_args(argv))
+
+def delete_object(obj):
+  if not INSIDE_BLENDER:
+    return
+  bpy.ops.object.select_all(action='DESELECT')
+  obj.select_set(True)
+  bpy.context.view_layer.objects.active = obj
+  bpy.ops.object.delete()
+
+def get_camera_coords(cam, pos):
+  if not INSIDE_BLENDER:
+    return (0, 0, 0)
+  scene = bpy.context.scene
+  x, y, z = bpy_extras.object_utils.world_to_camera_view(scene, cam, pos)
+  scale = scene.render.resolution_percentage / 100.0
+  w = int(scale * scene.render.resolution_x)
+  h = int(scale * scene.render.resolution_y)
+  px = int(round(x * w))
+  py = int(round(h - y * h))
+  return (px, py, z)
+
+def set_layer(obj, layer_idx):
+  if not INSIDE_BLENDER:
+    return
+  obj.layers[layer_idx] = True
+  for i in range(len(obj.layers)):
+    obj.layers[i] = (i == layer_idx)
+
+def add_object(object_dir, name, scale, loc, theta=0):
+  if not INSIDE_BLENDER:
+    return
+  object_dir = os.path.abspath(os.path.normpath(object_dir))
+  if not os.path.exists(object_dir):
+    print(f"ERROR: Object directory does not exist: {object_dir}")
+    return
+  count = 0
+  for obj in bpy.data.objects:
+    if obj.name.startswith(name):
+      count += 1
+
+  blend_file = os.path.join(object_dir, '%s.blend' % name)
+  blend_file = os.path.abspath(blend_file).replace('\\', '/')
+  if not os.path.exists(blend_file):
+    print(f"ERROR: Blend file does not exist: {blend_file}")
+    return
+  directory = blend_file + '/Object/'
+  try:
+    bpy.ops.wm.append(
+      directory=directory,
+      filename=name,
+      filter_blender=True
+    )
+  except Exception as e:
+    error_msg = str(e)
+    print(f"ERROR: Failed to load object {name} from {directory}: {error_msg}")
+    print(f"  Error type: {type(e).__name__}")
+    raise
+
+  new_name = '%s_%d' % (name, count)
+  bpy.data.objects[name].name = new_name
+
+  x, y = loc
+  bpy.context.view_layer.objects.active = bpy.data.objects[new_name]
+  bpy.context.object.rotation_euler[2] = theta
+  bpy.ops.transform.resize(value=(scale, scale, scale))
+  bpy.ops.transform.translate(value=(x, y, scale))
+
+def load_materials(material_dir):
+  if not INSIDE_BLENDER:
+    return
+  material_dir = os.path.abspath(os.path.normpath(material_dir))
+  if not os.path.exists(material_dir):
+    print(f"ERROR: Material directory does not exist: {material_dir}")
+    return
+  for fn in os.listdir(material_dir):
+    if not fn.endswith('.blend'): continue
+    name = os.path.splitext(fn)[0]
+    blend_file = os.path.join(material_dir, fn)
+    blend_file = os.path.abspath(blend_file).replace('\\', '/')
+    if not os.path.exists(blend_file):
+      print(f"ERROR: Blend file does not exist: {blend_file}")
+      continue
+    directory = blend_file + '/NodeTree/'
+    try:
+      bpy.ops.wm.append(
+        directory=directory,
+        filename=name,
+        filter_blender=True
+      )
+    except Exception as e:
+      error_msg = str(e)
+      print(f"ERROR: Failed to load material {name} from {directory}: {error_msg}")
+      print(f"  Error type: {type(e).__name__}")
+      raise
+
+def apply_filter_to_image(image_path, filter_type, filter_strength):
+  image_path = os.path.abspath(image_path)
+  if Image is None:
+    print(f"ERROR: PIL/Image not available, cannot apply filter {filter_type}")
+    return
+  if not os.path.exists(image_path):
+    print(f"ERROR: Image file does not exist: {image_path}")
+    return
+  
+  try:
+    img = Image.open(image_path)
+    
+    if filter_type == 'blur':
+      radius = max(1, int(filter_strength))
+      img = img.filter(ImageFilter.GaussianBlur(radius=radius))
+    
+    elif filter_type == 'vignette':
+      width, height = img.size
+      center_x, center_y = width // 2, height // 2
+      max_dist = math.sqrt(center_x**2 + center_y**2)
+      
+      img = img.convert('RGB')
+      pixels = img.load()
+      for y in range(height):
+        for x in range(width):
+          dist = math.sqrt((x - center_x)**2 + (y - center_y)**2)
+          factor = 1.0 - (dist / max_dist) * (filter_strength / 5.0)
+          factor = max(0.0, min(1.0, factor))
+          
+          r, g, b = pixels[x, y]
+          pixels[x, y] = (int(r * factor), int(g * factor), int(b * factor))
+    
+    elif filter_type == 'fisheye':
+      width, height = img.size
+      center_x, center_y = width / 2.0, height / 2.0
+      max_radius = min(center_x, center_y)
+      
+      img = img.convert('RGB')
+      output = Image.new('RGB', (width, height))
+      out_pixels = output.load()
+      in_pixels = img.load()
+      
+      for y in range(height):
+        for x in range(width):
+          dx = (x - center_x) / max_radius
+          dy = (y - center_y) / max_radius
+          distance = math.sqrt(dx*dx + dy*dy)
+          
+          if distance > 1.0:
+            out_pixels[x, y] = (0, 0, 0)
+          else:
+            theta = math.atan2(dy, dx)
+            r_normalized = distance
+            r_distorted = r_normalized * (1.0 + filter_strength * (1.0 - r_normalized))
+            r_distorted = min(1.0, r_distorted)
+            
+            src_x = int(center_x + r_distorted * max_radius * math.cos(theta))
+            src_y = int(center_y + r_distorted * max_radius * math.sin(theta))
+            
+            if 0 <= src_x < width and 0 <= src_y < height:
+              out_pixels[x, y] = in_pixels[src_x, src_y]
+            else:
+              out_pixels[x, y] = (0, 0, 0)
+      
+      img = output
+    
+    img.save(image_path)
+    print(f"[OK] Applied {filter_type} filter (strength: {filter_strength:.2f})")
+  except Exception as e:
+    import traceback
+    print(f"ERROR applying filter {filter_type}: {e}")
+    traceback.print_exc()
+    raise
+
+def add_material(name, **properties):
+  if not INSIDE_BLENDER:
+    return
+  mat_count = len(bpy.data.materials)
+  bpy.ops.material.new()
+  mat = bpy.data.materials['Material']
+  mat.name = 'Material_%d' % mat_count
+  obj = bpy.context.active_object
+  assert len(obj.data.materials) == 0
+  obj.data.materials.append(mat)
+
+  output_node = None
+  for n in mat.node_tree.nodes:
+    if n.name == 'Material Output':
+      output_node = n
+      break
+
+  group_node = mat.node_tree.nodes.new('ShaderNodeGroup')
+  group_node.node_tree = bpy.data.node_groups[name]
+
+  for inp in group_node.inputs:
+    if inp.name in properties:
+      inp.default_value = properties[inp.name]
+
+  mat.node_tree.links.new(
+      group_node.outputs['Shader'],
+      output_node.inputs['Surface'],
+  )
+
+parser = argparse.ArgumentParser()
+parser.add_argument('--scene_file', default=None,
+    help="Optional JSON file to load scene from. If provided, renders from JSON instead of generating random scenes.")
+parser.add_argument('--base_scene_blendfile', default='data/base_scene.blend',
+    help="Base blender file on which all scenes are based; includes " +
+          "ground plane, lights, and camera.")
+parser.add_argument('--properties_json', default='data/properties.json',
+    help="JSON file defining objects, materials, sizes, and colors. " +
+         "The \"colors\" field maps from CLEVR color names to RGB values; " +
+         "The \"sizes\" field maps from CLEVR size names to scalars used to " +
+         "rescale object models; the \"materials\" and \"shapes\" fields map " +
+         "from CLEVR material and shape names to .blend files in the " +
+         "--object_material_dir and --shape_dir directories respectively.")
+parser.add_argument('--shape_dir', default='data/shapes',
+    help="Directory where .blend files for object models are stored")
+parser.add_argument('--material_dir', default='data/materials',
+    help="Directory where .blend files for materials are stored")
+parser.add_argument('--shape_color_combos_json', default=None,
+    help="Optional path to a JSON file mapping shape names to a list of " +
+         "allowed color names for that shape. This allows rendering images " +
+         "for CLEVR-CoGenT.")
+
+parser.add_argument('--min_objects', default=3, type=int,
+    help="The minimum number of objects to place in each scene")
+parser.add_argument('--max_objects', default=10, type=int,
+    help="The maximum number of objects to place in each scene")
+parser.add_argument('--min_dist', default=0.15, type=float,
+    help="The minimum allowed distance between object centers")
+parser.add_argument('--margin', default=0.2, type=float,
+    help="Along all cardinal directions (left, right, front, back), all " +
+         "objects will be at least this distance apart. This makes resolving " +
+         "spatial relationships slightly less ambiguous.")
+parser.add_argument('--min_pixels_per_object', default=50, type=int,
+    help="All objects will have at least this many visible pixels in the " +
+         "final rendered images; this ensures that no objects are fully " +
+         "occluded by other objects.")
+parser.add_argument('--max_retries', default=100, type=int,
+    help="The number of times to try placing an object before giving up and " +
+         "re-placing all objects in the scene.")
+
+parser.add_argument('--start_idx', default=0, type=int,
+    help="The index at which to start for numbering rendered images. Setting " +
+         "this to non-zero values allows you to distribute rendering across " +
+         "multiple machines and recombine the results later.")
+parser.add_argument('--num_images', default=5, type=int,
+    help="The number of images to render")
+parser.add_argument('--filename_prefix', default='CLEVR',
+    help="This prefix will be prepended to the rendered images and JSON scenes")
+parser.add_argument('--split', default='new',
+    help="Name of the split for which we are rendering. This will be added to " +
+         "the names of rendered images, and will also be stored in the JSON " +
+         "scene structure for each image.")
+parser.add_argument('--output_image_dir', default='../output/images/',
+    help="The directory where output images will be stored. It will be " +
+         "created if it does not exist.")
+parser.add_argument('--output_scene_dir', default='../output/scenes/',
+    help="The directory where output JSON scene structures will be stored. " +
+         "It will be created if it does not exist.")
+parser.add_argument('--output_scene_file', default='../output/CLEVR_scenes.json',
+    help="Path to write a single JSON file containing all scene information")
+parser.add_argument('--output_blend_dir', default='output/blendfiles',
+    help="The directory where blender scene files will be stored, if the " +
+         "user requested that these files be saved using the " +
+         "--save_blendfiles flag; in this case it will be created if it does " +
+         "not already exist.")
+parser.add_argument('--save_blendfiles', type=int, default=0,
+    help="Setting --save_blendfiles 1 will cause the blender scene file for " +
+         "each generated image to be stored in the directory specified by " +
+         "the --output_blend_dir flag. These files are not saved by default " +
+         "because they take up ~5-10MB each.")
+parser.add_argument('--version', default='1.0',
+    help="String to store in the \"version\" field of the generated JSON file")
+parser.add_argument('--license',
+    default="Creative Commons Attribution (CC-BY 4.0)",
+    help="String to store in the \"license\" field of the generated JSON file")
+parser.add_argument('--date', default=dt.today().strftime("%m/%d/%Y"),
+    help="String to store in the \"date\" field of the generated JSON file; " +
+         "defaults to today's date")
+
+parser.add_argument('--use_gpu', default=0, type=int,
+    help="Setting --use_gpu 1 enables GPU-accelerated rendering using CUDA. " +
+         "You must have an NVIDIA GPU with the CUDA toolkit installed for " +
+         "to work.")
+parser.add_argument('--width', default=320, type=int,
+    help="The width (in pixels) for the rendered images")
+parser.add_argument('--height', default=240, type=int,
+    help="The height (in pixels) for the rendered images")
+parser.add_argument('--key_light_jitter', default=1.0, type=float,
+    help="The magnitude of random jitter to add to the key light position.")
+parser.add_argument('--fill_light_jitter', default=1.0, type=float,
+    help="The magnitude of random jitter to add to the fill light position.")
+parser.add_argument('--back_light_jitter', default=1.0, type=float,
+    help="The magnitude of random jitter to add to the back light position.")
+parser.add_argument('--camera_jitter', default=0.5, type=float,
+    help="The magnitude of random jitter to add to the camera position")
+parser.add_argument('--render_num_samples', default=512, type=int,
+    help="The number of samples to use when rendering. Larger values will " +
+         "result in nicer images but will cause rendering to take longer.")
+parser.add_argument('--render_min_bounces', default=8, type=int,
+    help="The minimum number of bounces to use for rendering.")
+parser.add_argument('--render_max_bounces', default=8, type=int,
+    help="The maximum number of bounces to use for rendering.")
+parser.add_argument('--render_tile_size', default=256, type=int,
+    help="The tile size to use for rendering. This should not affect the " +
+         "quality of the rendered image but may affect the speed; CPU-based " +
+         "rendering may achieve better performance using smaller tile sizes " +
+         "while larger tile sizes may be optimal for GPU-based rendering.")
+parser.add_argument('--output_image', default=None,
+    help="Output image path (used when rendering from JSON)")
+
+MIN_VISIBLE_FRACTION = 0.001
+MIN_VISIBLE_FRACTION_PARTIAL_OCCLUSION = 0.0005
+MIN_PIXELS_FLOOR = 50
+
+BASE_MIN_VISIBILITY_FRACTION = 0.9
+CF_OCCLUSION_MIN_VISIBILITY_FRACTION = 0.3
+CF_OCCLUSION_MAX_VISIBILITY_FRACTION = 0.5
+CF_OCCLUSION_HARD_MIN_FRACTION = 0.2
+
+
+def min_visible_pixels(width, height, fraction=MIN_VISIBLE_FRACTION, floor=MIN_PIXELS_FLOOR):
+  return max(floor, int(width * height * fraction))
+
+
+BACKGROUND_COLORS = {
+    'default': None,
+    'gray': (0.5, 0.5, 0.5),
+    'blue': (0.2, 0.4, 0.8),
+    'green': (0.2, 0.6, 0.3),
+    'brown': (0.4, 0.3, 0.2),
+    'purple': (0.5, 0.3, 0.6),
+    'orange': (0.8, 0.5, 0.2),
+    'white': (0.9, 0.9, 0.9),
+    'dark_gray': (0.2, 0.2, 0.2),
+    'red': (0.7, 0.2, 0.2),
+    'yellow': (0.8, 0.8, 0.3),
+    'cyan': (0.3, 0.7, 0.8),
+}
+
+LIGHTING_PRESETS = {
+    'default': {'key': 1.0, 'fill': 0.5, 'back': 0.3},
+    'bright': {'key': 12.0, 'fill': 6.0, 'back': 4.0},
+    'dim': {'key': 0.008, 'fill': 0.004, 'back': 0.002},
+    'warm': {'key': 5.0, 'fill': 0.8, 'back': 0.3, 'color': (1.0, 0.5, 0.2)},
+    'cool': {'key': 4.0, 'fill': 2.0, 'back': 1.5, 'color': (0.2, 0.5, 1.0)},
+    'dramatic': {'key': 15.0, 'fill': 0.005, 'back': 0.002},
+}
+
+def set_background_color(color_name):
+  """Set the world background color"""
+  if not INSIDE_BLENDER:
+    return
+  if color_name not in BACKGROUND_COLORS or BACKGROUND_COLORS[color_name] is None:
+    return
+  
+  rgb = BACKGROUND_COLORS[color_name]
+  
+  world = bpy.context.scene.world
+  if world is None:
+    world = bpy.data.worlds.new("World")
+    bpy.context.scene.world = world
+  
+  world.use_nodes = True
+  nodes = world.node_tree.nodes
+  
+  bg_node = None
+  for node in nodes:
+    if node.type == 'BACKGROUND':
+      bg_node = node
+      break
+  
+  if bg_node is None:
+    bg_node = nodes.new(type='ShaderNodeBackground')
+  
+  bg_node.inputs['Color'].default_value = (rgb[0], rgb[1], rgb[2], 1.0)
+  bg_node.inputs['Strength'].default_value = 1.0
+  
+  print(f"Set background color to {color_name}: RGB{rgb}")
+
+def set_ground_color(color_name):
+  if not INSIDE_BLENDER:
+    return
+  if color_name not in BACKGROUND_COLORS or BACKGROUND_COLORS[color_name] is None:
+    return
+  
+  rgb = BACKGROUND_COLORS[color_name]
+  
+  ground = None
+  for obj in bpy.data.objects:
+    if 'ground' in obj.name.lower() or 'plane' in obj.name.lower():
+      ground = obj
+      break
+  
+  if ground is None:
+    return
+  
+  if len(ground.data.materials) == 0:
+    mat = bpy.data.materials.new(name="Ground_Material")
+    ground.data.materials.append(mat)
+  else:
+    mat = ground.data.materials[0]
+  
+  mat.use_nodes = True
+  nodes = mat.node_tree.nodes
+  
+  bsdf = None
+  for node in nodes:
+    if node.type == 'BSDF_PRINCIPLED':
+      bsdf = node
+      break
+  
+  if bsdf:
+    bsdf.inputs['Base Color'].default_value = (rgb[0], rgb[1], rgb[2], 1.0)
+    print(f"Set ground color to {color_name}")
+
+def set_lighting(lighting_name):
+  """Set lighting conditions"""
+  if not INSIDE_BLENDER:
+    return
+  if lighting_name not in LIGHTING_PRESETS:
+    return
+  
+  preset = LIGHTING_PRESETS[lighting_name]
+  
+  lamp_names = ['Lamp_Key', 'Lamp_Fill', 'Lamp_Back']
+  intensity_keys = ['key', 'fill', 'back']
+  
+  for lamp_name, int_key in zip(lamp_names, intensity_keys):
+    if lamp_name in bpy.data.objects:
+      lamp_obj = bpy.data.objects[lamp_name]
+      if lamp_obj.data and hasattr(lamp_obj.data, 'energy'):
+        base_energy = lamp_obj.data.energy
+        lamp_obj.data.energy = base_energy * preset.get(int_key, 1.0)
+        
+        if 'color' in preset and hasattr(lamp_obj.data, 'color'):
+          lamp_obj.data.color = preset['color']
+  
+  print(f"Set lighting to {lighting_name}")
+
+def render_from_json(args):
+  if not INSIDE_BLENDER:
+    print("ERROR: render_from_json must be run inside Blender")
+    return
+  
+  output_dir = os.path.dirname(args.output_image) if args.output_image else '.'
+  if output_dir and not os.path.exists(output_dir):
+    os.makedirs(output_dir)
+  
+  with open(args.scene_file, 'r') as f:
+    scene_struct = json.load(f)
+  
+  num_objects = len(scene_struct.get('objects', []))
+  print(f"Scene has {num_objects} objects")
+  
+  base_scene_path = os.path.abspath(args.base_scene_blendfile)
+  bpy.ops.wm.open_mainfile(filepath=base_scene_path)
+  
+  try:
+    load_materials(args.material_dir)
+  except Exception as e:
+    print(f"Warning: Could not load materials: {e}")
+
+  background_color = scene_struct.get('background_color', None)
+  if background_color:
+    set_background_color(background_color)
+    set_ground_color(background_color)
+  
+  lighting = scene_struct.get('lighting', None)
+  if lighting:
+    set_lighting(lighting)
+  
+  render_args = bpy.context.scene.render
+  render_args.engine = "CYCLES"
+  render_args.filepath = args.output_image
+  render_args.resolution_x = args.width
+  render_args.resolution_y = args.height
+  render_args.resolution_percentage = 100
+  
+  if args.use_gpu == 1:
+    try:
+      bpy.context.preferences.addons['cycles'].preferences.compute_device_type = 'CUDA'
+      bpy.context.scene.cycles.device = 'GPU'
+      print("[OK] GPU rendering enabled")
+    except Exception as e:
+      print(f"Warning: Could not enable GPU: {e}")
+  
+  bpy.context.scene.cycles.samples = args.render_num_samples
+  
+  filter_type = scene_struct.get('filter_type')
+  filter_strength = scene_struct.get('filter_strength', 1.0)
+  
+  if filter_type == 'fisheye':
+    camera = bpy.data.objects.get('Camera')
+    if camera and camera.data:
+      cam_data = camera.data
+      if cam_data.type == 'PERSP':
+        cam_data.lens = cam_data.lens * 0.7
+        print(f"[OK] Zoomed out camera for fisheye: lens={cam_data.lens:.1f}mm")
+  
+  with open(args.properties_json, 'r') as f:
+    properties = json.load(f)
+    color_name_to_rgba = {}
+    for name, rgb in properties['colors'].items():
+      rgba = [float(c) / 255.0 for c in rgb] + [1.0]
+      color_name_to_rgba[name] = rgba
+    size_mapping = properties['sizes']
+  
+  shape_semantic_to_file = properties['shapes']
+  material_semantic_to_file = properties['materials']
+  
+  blender_objects = []
+  print("Adding objects to scene...")
+  for i, obj_info in enumerate(scene_struct.get('objects', [])):
+    x, y, z = obj_info['3d_coords']
+    r = size_mapping[obj_info['size']]
+    semantic_shape = obj_info['shape']
+    
+    if semantic_shape == 'cube':
+      r /= math.sqrt(2)
+    
+    if semantic_shape not in shape_semantic_to_file:
+      print(f"ERROR: Shape '{semantic_shape}' not found")
+      continue
+    
+    shape_file_name = shape_semantic_to_file[semantic_shape]
+    
+    try:
+      add_object(args.shape_dir, shape_file_name, r, (x, y), theta=obj_info['rotation'])
+    except Exception as e:
+      print(f"Error adding object {i}: {e}")
+      continue
+    if INSIDE_BLENDER and bpy.context.object:
+      blender_objects.append(bpy.context.object)
+    
+    rgba = color_name_to_rgba[obj_info['color']]
+    semantic_material = obj_info['material']
+    
+    if semantic_material not in material_semantic_to_file:
+      print(f"ERROR: Material '{semantic_material}' not found")
+      continue
+    
+    mat_file_name = material_semantic_to_file[semantic_material]
+    
+    try:
+      add_material(mat_file_name, Color=rgba)
+    except Exception as e:
+      print(f"Warning: Could not add material: {e}")
+  
+  if blender_objects:
+    cf_meta = scene_struct.get('cf_metadata') or {}
+    cf_type = cf_meta.get('cf_type', '')
+
+    visibility_info = None
+    if INSIDE_BLENDER and Image is not None:
+      try:
+        visibility_info = compute_visibility_fractions(blender_objects)
+      except Exception as e:
+        print(f"Warning: compute_visibility_fractions failed during render: {e}")
+        visibility_info = None
+
+    all_visible = True
+    fail_reason = 'unknown visibility failure'
+
+    if visibility_info is not None:
+      ratios, scene_counts, full_counts = visibility_info
+
+      if cf_type == 'occlusion_change':
+        too_hidden = [
+          (i, r) for i, r in enumerate(ratios)
+          if full_counts[i] > 0 and r < CF_OCCLUSION_HARD_MIN_FRACTION
+        ]
+        band_objects = [
+          (i, r) for i, r in enumerate(ratios)
+          if full_counts[i] > 0 and CF_OCCLUSION_MIN_VISIBILITY_FRACTION <= r <= CF_OCCLUSION_MAX_VISIBILITY_FRACTION
+        ]
+
+        if too_hidden:
+          all_visible = False
+          min_r = min(r for (_, r) in too_hidden)
+          fail_reason = (f'at least one object is too occluded in occlusion_change CF; '
+                         f'min visibility fraction={min_r:.3f} '
+                         f'(required >= {CF_OCCLUSION_HARD_MIN_FRACTION})')
+        elif not band_objects:
+          all_visible = False
+          fail_reason = (f'no object falls into required occlusion band '
+                         f'[{CF_OCCLUSION_MIN_VISIBILITY_FRACTION}, '
+                         f'{CF_OCCLUSION_MAX_VISIBILITY_FRACTION}]')
+        else:
+          all_visible = True
+
+      else:
+        too_occluded = [
+          (i, r) for i, r in enumerate(ratios)
+          if full_counts[i] > 0 and r < BASE_MIN_VISIBILITY_FRACTION
+        ]
+        if too_occluded:
+          all_visible = False
+          min_r = min(r for (_, r) in too_occluded)
+          fail_reason = (f'at least one object is too occluded in base scene; '
+                         f'min visibility fraction={min_r:.3f} '
+                         f'(required >= {BASE_MIN_VISIBILITY_FRACTION})')
+        else:
+          all_visible = True
+
+    else:
+      # Fallback to legacy absolute pixel-based visibility when we cannot
+      # compute per-object relative visibility (e.g., PIL not available).
+      w = getattr(args, 'width', 320)
+      h = getattr(args, 'height', 240)
+      if cf_type == 'occlusion_change':
+        min_pixels = min_visible_pixels(w, h, MIN_VISIBLE_FRACTION_PARTIAL_OCCLUSION, MIN_PIXELS_FLOOR)
+      else:
+        base = min_visible_pixels(w, h, MIN_VISIBLE_FRACTION, MIN_PIXELS_FLOOR)
+        min_pixels = max(getattr(args, 'min_pixels_per_object', MIN_PIXELS_FLOOR), base)
+      all_visible = check_visibility(blender_objects, min_pixels)
+      if not all_visible:
+        fail_reason = 'at least one object has too few visible pixels'
+
+    if not all_visible:
+      print(f'Visibility check failed: {fail_reason}')
+      for obj in blender_objects:
+        try:
+          delete_object(obj)
+        except Exception:
+          pass
+      sys.exit(1)
+  
+  filter_type = scene_struct.get('filter_type')
+  filter_strength = scene_struct.get('filter_strength', 1.0)
+  
+  print(f"Rendering to {args.output_image}...")
+  
+  try:
+    bpy.ops.render.render(write_still=True)
+    print("[OK] Rendering complete!")
+  except Exception as e:
+    print(f"Error during rendering: {e}")
+    sys.exit(1)
+  
+  post_filter_type = scene_struct.get('filter_type')
+  if post_filter_type and post_filter_type != 'fisheye':
+    if Image is None:
+      print(f"Warning: PIL not available, cannot apply post-filter {post_filter_type}")
+    elif not os.path.exists(args.output_image):
+      print(f"Warning: Output image does not exist: {args.output_image}")
+    else:
+      try:
+        post_filter_strength = scene_struct.get('filter_strength', 1.0)
+        apply_filter_to_image(args.output_image, post_filter_type, post_filter_strength)
+      except Exception as e:
+        import traceback
+        print(f"Warning: Failed to apply post-filter {post_filter_type}: {e}")
+        traceback.print_exc()
+
+def main(args):
+  if args.scene_file:
+    render_from_json(args)
+    return
+  
+  num_digits = 6
+  prefix = '%s_%s_' % (args.filename_prefix, args.split)
+  img_template = '%s%%0%dd.png' % (prefix, num_digits)
+  scene_template = '%s%%0%dd.json' % (prefix, num_digits)
+  blend_template = '%s%%0%dd.blend' % (prefix, num_digits)
+  img_template = os.path.join(args.output_image_dir, img_template)
+  scene_template = os.path.join(args.output_scene_dir, scene_template)
+  blend_template = os.path.join(args.output_blend_dir, blend_template)
+
+  if not os.path.isdir(args.output_image_dir):
+    os.makedirs(args.output_image_dir)
+  if not os.path.isdir(args.output_scene_dir):
+    os.makedirs(args.output_scene_dir)
+  if args.save_blendfiles == 1 and not os.path.isdir(args.output_blend_dir):
+    os.makedirs(args.output_blend_dir)
+  
+  all_scene_paths = []
+  for i in range(args.num_images):
+    img_path = img_template % (i + args.start_idx)
+    scene_path = scene_template % (i + args.start_idx)
+    all_scene_paths.append(scene_path)
+    blend_path = None
+    if args.save_blendfiles == 1:
+      blend_path = blend_template % (i + args.start_idx)
+    num_objects = random.randint(args.min_objects, args.max_objects)
+    render_scene(args,
+      num_objects=num_objects,
+      output_index=(i + args.start_idx),
+      output_split=args.split,
+      output_image=img_path,
+      output_scene=scene_path,
+      output_blendfile=blend_path,
+    )
+
+  all_scenes = []
+  for scene_path in all_scene_paths:
+    with open(scene_path, 'r') as f:
+      all_scenes.append(json.load(f))
+  output = {
+    'info': {
+      'date': args.date,
+      'version': args.version,
+      'split': args.split,
+      'license': args.license,
+    },
+    'scenes': all_scenes
+  }
+  if args.output_scene_file:
+    output_dir = os.path.dirname(os.path.abspath(args.output_scene_file))
+    if output_dir:
+      os.makedirs(output_dir, exist_ok=True)
+    with open(args.output_scene_file, 'w') as f:
+      json.dump(output, f)
+
+
+
+def render_scene(args,
+    num_objects=5,
+    output_index=0,
+    output_split='none',
+    output_image='render.png',
+    output_scene='render_json',
+    output_blendfile=None,
+  ):
+
+  base_scene_path = os.path.abspath(args.base_scene_blendfile)
+  bpy.ops.wm.open_mainfile(filepath=base_scene_path)
+  load_materials(args.material_dir)
+
+  render_args = bpy.context.scene.render
+  render_args.engine = "CYCLES"
+  render_args.filepath = output_image
+  render_args.resolution_x = args.width
+  render_args.resolution_y = args.height
+  render_args.resolution_percentage = 100
+  if args.use_gpu == 1:
+    bpy.context.preferences.addons['cycles'].preferences.compute_device_type = 'CUDA'
+    bpy.context.preferences.addons['cycles'].preferences.get_devices()
+    for device in bpy.context.preferences.addons['cycles'].preferences.devices:
+      device.use = True
+
+  bpy.data.worlds['World'].cycles.sample_as_light = True
+  bpy.context.scene.cycles.blur_glossy = 2.0
+  bpy.context.scene.cycles.samples = args.render_num_samples
+  bpy.context.scene.cycles.transparent_min_bounces = args.render_min_bounces
+  bpy.context.scene.cycles.transparent_max_bounces = args.render_max_bounces
+  if args.use_gpu == 1:
+    bpy.context.scene.cycles.device = 'GPU'
+
+  scene_struct = {
+      'split': output_split,
+      'image_index': output_index,
+      'image_filename': os.path.basename(output_image),
+      'objects': [],
+      'directions': {},
+  }
+
+  bpy.ops.mesh.primitive_plane_add(size=10, location=(0, 0, 0))
+  plane = bpy.context.object
+
+  def rand(L):
+    return 2.0 * L * (random.random() - 0.5)
+
+  if args.camera_jitter > 0:
+    for i in range(3):
+      bpy.data.objects['Camera'].location[i] += rand(args.camera_jitter)
+
+  camera = bpy.data.objects['Camera']
+  plane_normal = plane.data.vertices[0].normal
+  cam_behind = camera.matrix_world.to_quaternion() @ Vector((0, 0, -1))
+  cam_left = camera.matrix_world.to_quaternion() @ Vector((-1, 0, 0))
+  cam_up = camera.matrix_world.to_quaternion() @ Vector((0, 1, 0))
+  plane_behind = (cam_behind - cam_behind.project(plane_normal)).normalized()
+  plane_left = (cam_left - cam_left.project(plane_normal)).normalized()
+  plane_up = cam_up.project(plane_normal).normalized()
+
+  delete_object(plane)
+
+  scene_struct['directions']['behind'] = tuple(plane_behind)
+  scene_struct['directions']['front'] = tuple(-plane_behind)
+  scene_struct['directions']['left'] = tuple(plane_left)
+  scene_struct['directions']['right'] = tuple(-plane_left)
+  scene_struct['directions']['above'] = tuple(plane_up)
+  scene_struct['directions']['below'] = tuple(-plane_up)
+
+  if args.key_light_jitter > 0:
+    for i in range(3):
+      bpy.data.objects['Lamp_Key'].location[i] += rand(args.key_light_jitter)
+  if args.back_light_jitter > 0:
+    for i in range(3):
+      bpy.data.objects['Lamp_Back'].location[i] += rand(args.back_light_jitter)
+  if args.fill_light_jitter > 0:
+    for i in range(3):
+      bpy.data.objects['Lamp_Fill'].location[i] += rand(args.fill_light_jitter)
+
+  objects, blender_objects = add_random_objects(scene_struct, num_objects, args, camera)
+  scene_struct['objects'] = objects
+  scene_struct['relationships'] = compute_all_relationships(scene_struct)
+  while True:
+    try:
+      bpy.ops.render.render(write_still=True)
+      break
+    except Exception as e:
+      print(e)
+
+  with open(output_scene, 'w') as f:
+    json.dump(scene_struct, f, indent=2)
+
+  if output_blendfile is not None:
+    bpy.ops.wm.save_as_mainfile(filepath=output_blendfile)
+
+
+def add_random_objects(scene_struct, num_objects, args, camera, max_scene_attempts=10):
+  scene_attempt = 0
+  while scene_attempt < max_scene_attempts:
+    scene_attempt += 1
+
+    with open(args.properties_json, 'r') as f:
+      properties = json.load(f)
+      color_name_to_rgba = {}
+      for name, rgb in properties['colors'].items():
+        rgba = [float(c) / 255.0 for c in rgb] + [1.0]
+        color_name_to_rgba[name] = rgba
+      material_mapping = [(v, k) for k, v in properties['materials'].items()]
+      object_mapping = [(v, k) for k, v in properties['shapes'].items()]
+      size_mapping = list(properties['sizes'].items())
+
+    shape_color_combos = None
+    if args.shape_color_combos_json is not None:
+      with open(args.shape_color_combos_json, 'r') as f:
+        shape_color_combos = list(json.load(f).items())
+
+    positions = []
+    objects = []
+    blender_objects = []
+    for i in range(num_objects):
+      size_name, r = random.choice(size_mapping)
+
+      num_tries = 0
+      while True:
+        num_tries += 1
+        if num_tries > args.max_retries:
+          for obj in blender_objects:
+            delete_object(obj)
+          break
+        x = random.uniform(-3, 3)
+        y = random.uniform(-3, 3)
+        dists_good = True
+        margins_good = True
+        for (xx, yy, rr) in positions:
+          dx, dy = x - xx, y - yy
+          dist = math.sqrt(dx * dx + dy * dy)
+          if dist - r - rr < args.min_dist:
+            dists_good = False
+            break
+          for direction_name in ['left', 'right', 'front', 'behind']:
+            direction_vec = scene_struct['directions'][direction_name]
+            assert direction_vec[2] == 0
+            margin = dx * direction_vec[0] + dy * direction_vec[1]
+            if 0 < margin < args.margin:
+              print(margin, args.margin, direction_name)
+              print('BROKEN MARGIN!')
+              margins_good = False
+              break
+          if not margins_good:
+            break
+
+        if dists_good and margins_good:
+          break
+      
+      if num_tries > args.max_retries:
+        break
+
+      if shape_color_combos is None:
+        obj_name, obj_name_out = random.choice(object_mapping)
+        color_name, rgba = random.choice(list(color_name_to_rgba.items()))
+      else:
+        obj_name_out, color_choices = random.choice(shape_color_combos)
+        color_name = random.choice(color_choices)
+        obj_name = [k for k, v in object_mapping if v == obj_name_out][0]
+        rgba = color_name_to_rgba[color_name]
+
+      if obj_name == 'Cube':
+        r /= math.sqrt(2)
+
+      theta = 360.0 * random.random()
+      add_object(args.shape_dir, obj_name, r, (x, y), theta=theta)
+      obj = bpy.context.object
+      blender_objects.append(obj)
+      positions.append((x, y, r))
+
+      mat_name, mat_name_out = random.choice(material_mapping)
+      add_material(mat_name, Color=rgba)
+
+      pixel_coords = get_camera_coords(camera, obj.location)
+      objects.append({
+        'shape': obj_name_out,
+        'size': size_name,
+        'material': mat_name_out,
+        '3d_coords': tuple(obj.location),
+        'rotation': theta,
+        'pixel_coords': pixel_coords,
+        'color': color_name,
+      })
+
+    if len(objects) < num_objects:
+      continue
+
+    visibility_info = None
+    if INSIDE_BLENDER and Image is not None:
+      try:
+        visibility_info = compute_visibility_fractions(blender_objects)
+      except Exception as e:
+        print(f"Warning: compute_visibility_fractions failed during scene generation: {e}")
+        visibility_info = None
+
+    all_visible = True
+    if visibility_info is not None:
+      ratios, scene_counts, full_counts = visibility_info
+      min_ratio = min((r for r in ratios if full_counts[ratios.index(r)] > 0), default=1.0)
+      all_visible = all(
+        (full_counts[i] == 0) or (ratios[i] >= BASE_MIN_VISIBILITY_FRACTION)
+        for i in range(len(ratios))
+      )
+      if not all_visible:
+        print(f'Some objects are too occluded in generated scene; '
+              f'min visibility fraction={min_ratio:.3f} (required >= {BASE_MIN_VISIBILITY_FRACTION})')
+    else:
+      # Fallback to legacy absolute pixel-based visibility when PIL or Blender context is unavailable.
+      min_pixels = max(args.min_pixels_per_object, min_visible_pixels(args.width, args.height))
+      all_visible = check_visibility(blender_objects, min_pixels)
+
+    if not all_visible:
+      print('Some objects are occluded; replacing objects')
+      for obj in blender_objects:
+        delete_object(obj)
+      continue
+
+    return objects, blender_objects
+
+  raise RuntimeError(f"Failed to generate a valid scene after {max_scene_attempts} attempts")
+
+
+def compute_all_relationships(scene_struct, eps=0.2):
+  """
+  Computes relationships between all pairs of objects in the scene.
+  
+  Returns a dictionary mapping string relationship names to lists of lists of
+  integers, where output[rel][i] gives a list of object indices that have the
+  relationship rel with object i. For example if j is in output['left'][i] then
+  object j is left of object j.
+  """
+  all_relationships = {}
+  for name, direction_vec in scene_struct['directions'].items():
+    if name == 'above' or name == 'below': continue
+    all_relationships[name] = []
+    for i, obj1 in enumerate(scene_struct['objects']):
+      coords1 = obj1['3d_coords']
+      related = set()
+      for j, obj2 in enumerate(scene_struct['objects']):
+        if obj1 == obj2: continue
+        coords2 = obj2['3d_coords']
+        diff = [coords2[k] - coords1[k] for k in [0, 1, 2]]
+        dot = sum(diff[k] * direction_vec[k] for k in [0, 1, 2])
+        if dot > eps:
+          related.add(j)
+      all_relationships[name].append(sorted(list(related)))
+  return all_relationships
+
+
+def compute_visibility_fractions(blender_objects):
+  if not INSIDE_BLENDER or not blender_objects:
+    return None
+  if Image is None:
+    return None
+
+  # First pass: all objects together (occluded counts).
+  fd, path = tempfile.mkstemp(suffix='.png')
+  os.close(fd)
+  try:
+    colors_list = render_shadeless(blender_objects, path, use_distinct_colors=True)
+    img = Image.open(path).convert('RGB')
+    w, h = img.size
+    pix = img.load()
+    color_to_idx = {}
+    for i, (r, g, b) in enumerate(colors_list):
+      key = (round(r * 255), round(g * 255), round(b * 255))
+      color_to_idx[key] = i
+    scene_counts = [0] * len(blender_objects)
+    for y in range(h):
+      for x in range(w):
+        key = (pix[x, y][0], pix[x, y][1], pix[x, y][2])
+        if key in color_to_idx:
+          scene_counts[color_to_idx[key]] += 1
+  finally:
+    try:
+      os.remove(path)
+    except Exception:
+      pass
+
+  # Second pass: per-object "full area" with other objects hidden.
+  full_counts = []
+  original_hide_render = [obj.hide_render for obj in blender_objects]
+  try:
+    for idx, obj in enumerate(blender_objects):
+      # Hide all other objects, ensure this one is visible.
+      for j, other in enumerate(blender_objects):
+        if j == idx:
+          other.hide_render = False
+        else:
+          other.hide_render = True
+
+      fd_i, path_i = tempfile.mkstemp(suffix='.png')
+      os.close(fd_i)
+      try:
+        colors_list = render_shadeless([obj], path_i, use_distinct_colors=True)
+        img = Image.open(path_i).convert('RGB')
+        w, h = img.size
+        pix = img.load()
+        color_to_idx = {}
+        for i, (r, g, b) in enumerate(colors_list):
+          key = (round(r * 255), round(g * 255), round(b * 255))
+          color_to_idx[key] = i
+        count = 0
+        for y in range(h):
+          for x in range(w):
+            key = (pix[x, y][0], pix[x, y][1], pix[x, y][2])
+            if key in color_to_idx:
+              count += 1
+        full_counts.append(count)
+      finally:
+        try:
+          os.remove(path_i)
+        except Exception:
+          pass
+  finally:
+    # Restore previous hide_render flags.
+    for obj, prev in zip(blender_objects, original_hide_render):
+      obj.hide_render = prev
+
+  visibility = []
+  for scene_c, full_c in zip(scene_counts, full_counts):
+    if full_c <= 0:
+      visibility.append(0.0)
+    else:
+      visibility.append(float(scene_c) / float(full_c))
+
+  return visibility, scene_counts, full_counts
+
+
+def check_visibility(blender_objects, min_pixels_per_object):
+  """
+  Legacy absolute pixel-count visibility check, kept as a fallback when
+  relative per-object visibility cannot be computed.
+  """
+  if not INSIDE_BLENDER or not blender_objects:
+    return True
+  if Image is None:
+    return True
+  fd, path = tempfile.mkstemp(suffix='.png')
+  os.close(fd)
+  try:
+    colors_list = render_shadeless(blender_objects, path, use_distinct_colors=True)
+    img = Image.open(path).convert('RGB')
+    w, h = img.size
+    pix = img.load()
+    color_to_idx = {}
+    for i, (r, g, b) in enumerate(colors_list):
+      key = (round(r * 255), round(g * 255), round(b * 255))
+      color_to_idx[key] = i
+    counts = [0] * len(blender_objects)
+    for y in range(h):
+      for x in range(w):
+        key = (pix[x, y][0], pix[x, y][1], pix[x, y][2])
+        if key in color_to_idx:
+          counts[color_to_idx[key]] += 1
+    all_visible = all(c >= min_pixels_per_object for c in counts)
+    return all_visible
+  finally:
+    try:
+      os.remove(path)
+    except Exception:
+      pass
+
+
+def render_shadeless(blender_objects, path='flat.png', use_distinct_colors=False):
+  """
+  Render a version of the scene with shading disabled and unique materials
+  assigned to all objects. The image itself is written to path. This is used to ensure
+  that all objects will be visible in the final rendered scene (when check_visibility is enabled).
+  Returns a list of (r,g,b) colors in object order (for visibility counting when use_distinct_colors=True).
+  """
+  render_args = bpy.context.scene.render
+
+  old_filepath = render_args.filepath
+  old_engine = render_args.engine
+
+  render_args.filepath = path
+  render_args.engine = 'BLENDER_EEVEE_NEXT'
+  
+  view_layer = bpy.context.scene.view_layers[0]
+  old_use_pass_combined = view_layer.use_pass_combined
+  
+  for obj_name in ['Lamp_Key', 'Lamp_Fill', 'Lamp_Back', 'Ground']:
+    if obj_name in bpy.data.objects:
+      obj = bpy.data.objects[obj_name]
+      obj.hide_render = True
+
+  n = len(blender_objects)
+  object_colors = [] if use_distinct_colors else set()
+  old_materials = []
+  for i, obj in enumerate(blender_objects):
+    if len(obj.data.materials) > 0:
+      old_materials.append(obj.data.materials[0])
+    else:
+      old_materials.append(None)
+    
+    mat = bpy.data.materials.new(name='Material_%d' % i)
+    mat.use_nodes = True
+    nodes = mat.node_tree.nodes
+    nodes.clear()
+    
+    node_emission = nodes.new(type='ShaderNodeEmission')
+    node_output = nodes.new(type='ShaderNodeOutputMaterial')
+    
+    if use_distinct_colors:
+      r = (i + 1) / (n + 1)
+      g, b = 0.5, 0.5
+      object_colors.append((r, g, b))
+    else:
+      while True:
+        r, g, b = [random.random() for _ in range(3)]
+        if (r, g, b) not in object_colors:
+          break
+      object_colors.add((r, g, b))
+    
+    node_emission.inputs['Color'].default_value = (r, g, b, 1.0)
+    mat.node_tree.links.new(node_emission.outputs['Emission'], node_output.inputs['Surface'])
+    
+    if len(obj.data.materials) > 0:
+      obj.data.materials[0] = mat
+    else:
+      obj.data.materials.append(mat)
+
+  bpy.ops.render.render(write_still=True)
+
+  for mat, obj in zip(old_materials, blender_objects):
+    if mat is not None:
+      obj.data.materials[0] = mat
+    elif len(obj.data.materials) > 0:
+      obj.data.materials.clear()
+
+  for obj_name in ['Lamp_Key', 'Lamp_Fill', 'Lamp_Back', 'Ground']:
+    if obj_name in bpy.data.objects:
+      obj = bpy.data.objects[obj_name]
+      obj.hide_render = False
+
+  render_args.filepath = old_filepath
+  render_args.engine = old_engine
+
+  return object_colors
+
+
+if __name__ == '__main__':
+  if INSIDE_BLENDER:
+    argv = extract_args()
+    args = parser.parse_args(argv)
+    main(args)
+  elif '--help' in sys.argv or '-h' in sys.argv:
+    parser.print_help()
+  else:
+    print('This script is intended to be called from blender like this:')
+    print()
+    print('blender --background --python render_images.py -- [args]')
+    print()
+    print('You can also run as a standalone python script to view all')
+    print('arguments like this:')
+    print()
+    print('python render_images.py --help')