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
134 lines
9.6 KiB
Markdown
134 lines
9.6 KiB
Markdown
# 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**:
|
|
1. **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.
|
|
2. **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.
|
|
3. **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**:
|
|
1. **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.
|
|
2. **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.
|
|
3. **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**:
|
|
1. **Given** a completed walkthrough, **When** I click "Share", **Then** I get a copyable link and an oEmbed-embeddable iframe snippet.
|
|
2. **Given** an embed snippet, **When** I paste it into a website, **Then** the InteriorScan viewer renders inline with all navigation controls functional.
|
|
3. **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**:
|
|
1. **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.
|
|
2. **Given** a project exists, **When** I edit its name or address, **Then** the changes persist and appear in the walkthrough metadata.
|
|
3. **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**:
|
|
1. **Given** I have an API key, **When** I POST photos to `/api/v1/projects`, **Then** I receive a project ID and a `Location` header for status polling.
|
|
2. **Given** a project is processing, **When** I GET `/api/v1/projects/:id`, **Then** I receive `{status: "processing", progress: 45, estimatedCompletion: "..."}`.
|
|
3. **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**:
|
|
1. **Given** a walkthrough with LiDAR data, **When** I toggle "Show Measurements", **Then** room dimensions appear as overlays on walls and floor (±5% accuracy).
|
|
2. **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**:
|
|
1. **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.
|
|
2. **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 |