hermes
be3221e93d
- SPEC: add User Story 0 (Property Setup via Catastro) as P1 entry - SPEC: add catastro_data and catastro_imports tables to data model - PLAN: add Phase 2A (Catastro Integration) with 8 tasks - AGENTS.md: add 3 key decisions (Catastro SSOT, 3DGS hybrid, plan inputs) - Demo v3: Spanish apartment (C/ Altabix 24, 3ºB, Elche), 7 rooms, upload panel for catastro/DXF, proper collisions on all doors
9.6 KiB
Feature Specification: InteriorScan MVP
Feature Branch: feat/001-interiorscan-mvp
Status: Draft — Awaiting Approval
Vision Statement
InteriorScan turns apartment photos into a navigable 3D space — like a Doom map of a real home. Real estate agents photograph a property, upload to InteriorScan, and share a link where potential buyers walk through the space in first-person. This filters out properties that don't fit, saving both agents and buyers from unnecessary physical visits.
User Scenarios & Testing
User Story 0 — Property Setup via Catastro (Priority: P1) 🎯 MVP Entry
As a real estate agent, I enter a property address and InteriorScan fetches the building's exterior footprint from the Spanish Cadastro (INSPIRE WFS), so the 3D model starts with verified exterior walls before I upload any photos.
Why this priority: The Catastro provides the SSOT for exterior geometry — wall outlines, building height, and number of floors. This eliminates manual exterior wall drawing and ensures dimensional accuracy. Interior walls come from photos or user-uploaded floor plans.
Independent Test: Enter "C/ Altabix 24, Elche" → refcat is resolved → building polygon is displayed on a minimap → exterior walls are generated in the 3D scene.
Acceptance Scenarios:
- Given I am creating a new project, When I type a Spanish address and submit, Then the system resolves it to a cadastral reference (refcat) and fetches the building footprint polygon from INSPIRE WFS.
- Given a building footprint is fetched, When the 3D scene initializes, Then exterior walls appear at the correct dimensions matching the Catastro polygon, with the correct number of floors.
- Given the Catastro lookup fails, When no polygon is found, Then the system falls back to manual wall drawing or DXF/SVG upload.
User Story 1 — Upload & Process (Priority: P1) 🎯 MVP Core
As a real estate agent, I upload 30-100 photos of a property and InteriorScan reconstructs the interior as a 3D walkthrough, so I can share a link where potential buyers navigate it like a first-person game.
Why this priority: Without reconstruction, nothing else matters. This is the core value proposition.
Independent Test: Upload photos → receive a shareable walkthrough URL. A visitor opens URL → navigates space in first-person.
Acceptance Scenarios:
- Given I am logged in, When I create a new project, upload 40+ JPEG photos of an interior, and submit for processing, Then the system accepts the upload, shows a processing status (queued → processing → complete), and within 60 minutes produces a 3D walkthrough.
- Given a walkthrough has completed processing, When I open the shareable link in a desktop browser, Then I see the reconstructed 3D space with WASD + mouse controls, collision detection, and texture-mapped walls/floors/ceilings.
- Given a walkthrough has completed processing, When I open the shareable link on a mobile browser, Then I see the reconstructed 3D space with tap-to-walk navigation and gyroscope look-around option.
User Story 2 — Share & Embed (Priority: P1) 🎯 MVP Distribution
As a real estate agent, I can share a walkthrough link or embed the viewer on any listing page, so potential buyers encounter the 3D tour wherever they find the property.
Why this priority: The walkthrough is useless without distribution. Sharing and embedding are how real estate works.
Independent Test: Agent shares link → opens in new tab. Agent copies embed code → pastes on WordPress/listing → viewer renders.
Acceptance Scenarios:
- Given a completed walkthrough, When I click "Share", Then I get a copyable link and an oEmbed-embeddable iframe snippet.
- Given an embed snippet, When I paste it into a website, Then the InteriorScan viewer renders inline with all navigation controls functional.
- Given a shared link, When an unauthenticated visitor opens it, Then they can navigate the full walkthrough without signing up (public access).
User Story 3 — Dashboard & Projects (Priority: P2)
As a real estate agent, I manage all my properties from a dashboard, so I can track processing status, edit metadata, and organize my portfolio.
Why this priority: Essential for retention but not for first-value. A single walkthrough proves the concept.
Independent Test: Agent creates 3 projects → sees them in dashboard → edits name/address → deletes one.
Acceptance Scenarios:
- Given I am logged in, When I visit the dashboard, Then I see a grid of my projects with thumbnail, name, address, processing status, and date.
- Given a project exists, When I edit its name or address, Then the changes persist and appear in the walkthrough metadata.
- Given I have 3 projects, When I delete one, Then it is removed from the dashboard and its data is scheduled for cleanup within 24h.
User Story 4 — API Access (Priority: P2)
As a developer integrating InteriorScan, I can upload photos and retrieve walkthroughs via REST API, so I can embed reconstruction into my own platform.
Why this priority: API-first is a constitution principle, but the web UI validates the pipeline first. API follows proven flow.
Independent Test: POST /api/v1/projects with photos → GET /api/v1/projects/:id returns status → GET /api/v1/projects/:id/walkthrough returns viewer URL.
Acceptance Scenarios:
- Given I have an API key, When I POST photos to
/api/v1/projects, Then I receive a project ID and aLocationheader for status polling. - Given a project is processing, When I GET
/api/v1/projects/:id, Then I receive{status: "processing", progress: 45, estimatedCompletion: "..."}. - Given a project is complete, When I GET
/api/v1/projects/:id/walkthrough, Then I receive the viewer URL and embed snippet.
User Story 5 — Measurements & Floor Plans (Priority: P3)
As a buyer, I can see room dimensions overlaid on the walkthrough and download a floor plan, so I can evaluate if furniture fits without visiting.
Why this priority: Differentiates from pure 360° tours but requires accurate reconstruction. Comes after core pipeline is proven.
Independent Test: Open walkthrough → toggle measurements → see room dimensions in meters.
Acceptance Scenarios:
- Given a walkthrough with LiDAR data, When I toggle "Show Measurements", Then room dimensions appear as overlays on walls and floor (±5% accuracy).
- Given a completed walkthrough, When I click "Download Floor Plan", Then I receive a PDF/DXF floor plan with labeled rooms and dimensions.
User Story 6 — Subscription & Billing (Priority: P3)
As an agent, I subscribe to a plan (Free/Pro/Enterprise) that determines how many walkthroughs I can create per month, so I only pay for what I use.
Why this priority: Revenue model, but not needed to validate the core pipeline.
Acceptance Scenarios:
- Given I am on the Free plan, When I attempt to create my 4th walkthrough, Then I see an upgrade prompt with Pro plan pricing.
- Given I upgrade to Pro, When payment is confirmed via Stripe, Then my walkthrough limit increases to 25/month and the badge updates.
Edge Cases
- Fewer than 20 photos: System rejects with guidance on minimum coverage
- Corrupt/unreadable photos: System skips corrupt files, warns user, continues with valid ones
- Processing failure: System retries once, then marks as "failed" with error details and refund option
- Very large spaces (>200 photos): System queues with estimated time, processes in chunks
- Mobile browser without WebGL: Fallback to 360° photo carousel (progressive enhancement)
- Duplicate photos: System deduplicates by perceptual hash before processing
Requirements
Functional Requirements
- FR-001: System MUST accept 20-500 JPEG/PNG photos per project via web upload or API
- FR-002: System MUST reconstruct 3D mesh from photos using COLMAP/OpenMVS pipeline
- FR-003: System MUST provide first-person navigation (WASD + mouse) in desktop browsers
- FR-004: System MUST provide tap-to-walk navigation in mobile browsers
- FR-005: System MUST generate shareable public links for completed walkthroughs
- FR-006: System MUST provide oEmbed-embeddable iframe code
- FR-007: System MUST show processing status: queued → processing → complete (with progress %)
- FR-008: System MUST handle processing failures gracefully with retry + notification
- FR-009: System MUST export walkthrough data in open formats (OBJ minimum)
- FR-010: System MUST work on iPhone, Android, desktop Chrome, Firefox, Safari
Non-Functional Requirements
- NFR-001: Walkthrough viewer MUST load initial mesh in <5 seconds on 4G
- NFR-002: Navigation MUST run at ≥30 FPS on mid-range 2024 devices
- NFR-003: Processing MUST complete within 60 minutes for 100 photos
- NFR-004: System MUST handle 10 concurrent processing jobs
- NFR-005: Walkthrough links MUST work without authentication (public)
- NFR-006: API MUST follow OpenAPI 3.1 spec with Zod-validated schemas
Success Criteria
- SC-001: First tester uploads 40 photos → walks through reconstructed kitchen in <10 min total
- SC-002: Unauthenticated visitor opens shareable link → navigates fluently at 30+ FPS
- SC-003: Processing pipeline produces visual quality comparable to Matterport's basic tier
- SC-004: 3 of monyi's tester friends complete a walkthrough creation within 1 hour of onboarding