SpatialCanvas

New in this package

• Depth-aware auto placement with wall candidate detection
• Adjacent wall targeting (left, center, right, or best-fit auto)
• Manual four-point override when needed
• Backend OpenCV rendering plus client-side OpenCV.js fallback

SpatialCanvas is an open-source engine for turning a single image into a spatially-aware staging canvas.

The project starts with one sharp promise:

Upload a room photo, mark a wall plane, and place artwork with correct perspective, scale cues, and depth-aware shadows.

Instead of leading with abstract math, SpatialCanvas leads with a tactile artifact that developers can improve. Under the hood it is designed for contributions in geometry, robotics math, signal processing, computer vision, rendering, and human-computer interaction.

Why this exists

Most virtual staging tools place flat overlays on top of images. SpatialCanvas aims to push beyond that by combining:

• projective geometry and homographies
• camera and plane reasoning
• optional depth estimation and segmentation
• physically-plausible shadows and occlusion
• an extensible plugin system for new math and rendering experiments

Current MVP

The included MVP is intentionally practical:

1. Upload a room image
2. Click four points on a wall in clockwise order
3. Upload artwork
4. The engine warps the artwork into the selected plane using a perspective transform
5. A soft contact shadow is rendered to make placement feel more grounded
6. The transformed result can be downloaded

This gives the community a concrete baseline to improve.

Repo layout

spatialcanvas/
  app/                    FastAPI server + API routes
  frontend/               Lightweight browser client
  spatialcanvas/          Core Python package
    geometry/             Projective geometry + homography math
    rendering/            Placement rendering and shadows
    plugins/              Extension hooks and sample plugins
    vision/               Stubs/interfaces for depth/layout modules
  tests/                  Unit tests for core math and rendering
  .github/                Community health and workflow files

Quick start

1) Create a virtual environment

python -m venv .venv
source .venv/bin/activate

2) Install dependencies

pip install -r requirements.txt

3) Run the app

uvicorn app.main:app --reload

Then open:

http://127.0.0.1:8000

API

POST /api/warp-artwork

Form fields:

• scene_image: room photo
• art_image: artwork image
• wall_points_json: JSON array of four [x, y] points in clockwise order
• shadow_strength: optional float from 0.0 to 1.0
• margin_ratio: optional float to leave a clean border inside the plane

Returns:

• PNG bytes of the composited result

Design principles

• Useful first: the first experience should work in minutes.
• Math-friendly: the architecture should reward contributions from geometry and robotics communities.
• Progressive intelligence: depth maps and learned models plug in later without forcing them into the core.
• Open by design: examples, tests, and docs are first-class.

Roadmap

v0.1

• Manual wall plane selection
• Perspective-correct artwork placement
• Contact shadow rendering
• Downloadable output
• Plugin interface for placement refinement

v0.2

• Auto wall candidate detection from line structure
• Vanishing point estimation utilities
• Occlusion mask input/output support
• Furniture/cardboard-box 2.5D placement primitives

v0.3

• Monocular depth adapter
• Layout confidence map
• Multi-object scene graph
• WebGL viewer

v1.0

• Full community benchmark
• Standard plugin registry
• Public demo gallery
• Reference integrations with Three.js and Blender

Contributing

Please start with:

• CONTRIBUTING.md
• CODE_OF_CONDUCT.md
• open issues labeled good first issue, geometry, vision, or rendering

License

MIT

Launch kit

For launch-ready assets, starter issues, discussion thread drafts, social copy, and helper scripts, see launch/.