DeepSonar

DeepSonar is a Blender-based simulation toolkit for generating forward-looking sonar imagery from 3D assets (.glb) along with paired RGB views and pose files.
The repository contains multiple script variants, including baseline CPU implementations and optional NVIDIA Warp-accelerated pipelines.

Features

• Forward-looking sonar ray-casting in Blender scenes
• Polar and fan-shaped cartesian sonar image generation
• Optional speckle and backscatter noise modeling
• Object-aware sonar crop export
• Paired RGB image rendering from matching viewpoints
• Sonar/camera pose export as .npy
• Optional GPU acceleration for histogram/binning (Warp)

Repository Layout

DeepSonar/
  README.md
  Sonar/
    scan.py               # Full spherical scan pipeline (GLB import, sonar + RGB + poses)
    SonarIllumination.py  # Baseline single-scene sonar projection + noise + cartesian export
    warp_sonar.py         # Warp-optional acceleration example (CLI Blender script)
    warp_final.py         # Warp-optional module with public API run_sonar_pipeline(...)

Requirements

Core

• Blender (tested with Python 3.11 runtime embedded in Blender)
• Python packages available to Blender's Python:
  • numpy
  • torch
  • matplotlib
  • scipy
  • Pillow

Optional (GPU acceleration)

• NVIDIA GPU + CUDA driver
• warp-lang Python package (imported as warp)

If Warp is unavailable, scripts automatically fall back to CPU paths where implemented.

Install Dependencies

Because these scripts run inside Blender, install packages into Blender's Python environment (or an environment Blender can access).

Example (replace Blender Python path as needed):

"/path/to/blender/3.x/python/bin/python3.11" -m pip install numpy torch matplotlib scipy pillow warp-lang

If you run Blender with your system/site packages enabled, ensure those packages are also visible from Blender runtime.

How to Run

1) Full dataset-style pipeline: Sonar/scan.py

This is the most comprehensive script in the repo. It:

• Imports and normalizes a .glb
• Samples viewpoints over a spherical grid
• Generates:
  • sonar_polar/*.png
  • sonar_cartesian/*.png
  • cropped_sonar_cartesian/*.png (when object hits are detected)
  • rgb/*.png
  • poses/*_sonar_pose.npy

Run from Blender:

blender -b -P Sonar/scan.py

Important: scan.py currently contains hardcoded paths in the main(...) call near the end of the file.
Edit those to your local GLB input path and output directory before running.

2) Baseline sonar render: Sonar/SonarIllumination.py

This script performs sonar projection for the current Blender scene, applies noise, and saves a cartesian sonar image to:

• //renders/fan_with_ticks.png (Blender-relative path)

Run:

blender -b your_scene.blend -P Sonar/SonarIllumination.py

3) Warp-optional script: Sonar/warp_sonar.py

CLI-style script that keeps sonar math similar to baseline while accelerating accumulation with Warp when available.

Run:

blender -b your_scene.blend -P Sonar/warp_sonar.py

4) Warp-optional module/API: Sonar/warp_final.py

Exposes:

run_sonar_pipeline(output_path="//renders/fan_with_ticks.png")

Can be run directly:

blender -b your_scene.blend -P Sonar/warp_final.py

Outputs

Depending on script and mode, output directories typically include:

• rgb/: RGB renders at sonar viewpoints
• sonar_polar/: polar-projected sonar images
• sonar_cartesian/: fan/cartesian sonar images
• cropped_sonar_cartesian/: tight sonar crops around object-hit regions
• poses/: sonar pose matrices (.npy)

Configuration You Will Likely Change

Each script has editable constants near the top:

• LIGHT_ORIGIN, TARGET_CENTER
• cam_info:
  • azi_range, azi_bins
  • rad_range, rad_bins
  • ele_range, pp_arc
• Noise settings (variance, backscatter scale/mode)
• Spherical scan sampling (azim_step_deg, elev_step_deg, radius)

For scan.py, also update:

• Input GLB path in main(...)
• Base output path in main(...)

Notes and Caveats

• Several scripts are designed for Blender scripting context and may not run correctly with plain python script.py.
• Some paths are absolute/hardcoded by default; update them for portability.
• Higher ray counts (azi_bins * pp_arc) can be computationally expensive.
• Warp acceleration only applies to supported sections and only when CUDA + Warp are detected.

Troubleshooting

• ModuleNotFoundError inside Blender
  Install dependencies into Blender's Python environment.

• No output image appears
  Check output paths (bpy.path.abspath(...)) and write permissions.

• Very slow execution
  Reduce azi_bins, pp_arc, or viewpoint count; use Warp-enabled scripts when possible.

• Black/empty sonar image
  Verify scene/object placement, sonar origin/target, and rad_range coverage.