Skip to content

CSE499_Requirements_Specification.md

Latest commit

 

History

History
230 lines (170 loc) · 20.3 KB

CSE499_Requirements_Specification.md

File metadata and controls

230 lines (170 loc) · 20.3 KB

CSE 499 Requirements Specification — Goose3D

Title Page

Field Content
Project Name Goose3D
Team Members [To be filled — e.g., team lead and any collaborators]
Description Goose3D is an Android application that turns a phone into a 3D scanner. The user captures multiple camera frames around an object, runs a BoofCV-based reconstruction pipeline (structure-from-motion, bundle adjustment, dense point cloud), views the resulting 3D model in an in-app viewer, and can export or share it or save it to an in-app gallery. Optional camera calibration via a checkerboard improves reconstruction quality. The app supports opening external .ply files via “Open with” for viewing.

Section 1: Introduction — Purpose of Project

Problem: Creating 3D models of physical objects usually requires expensive hardware or desktop software. Many users need a simple way to capture real-world objects as 3D models on a device they already own (e.g., a smartphone) for sharing, archiving, or further use in other apps.

Solution: Goose3D is an Android app that uses the device camera and BoofCV-based reconstruction to produce 3D point clouds (PLY) from multiple photos. Users get a single, integrated flow: capture frames → process → view → export or save to gallery. Optional checkerboard calibration improves accuracy. The app stores everything on-device (no cloud dependency) and supports export to Downloads and system Share, plus an in-app gallery to manage saved scans. By running entirely on the device with a wizard-style UI, Goose3D makes 3D scanning accessible without specialized hardware or subscriptions.

Section 2a: Must Have Requirements

The following are functional requirements that can be demonstrated by running the app. Each has a clear success measure and demonstration method.

  1. Capture camera frames during a scan

    • Requirement: The app shall allow the user to start a scan, see a live camera preview, and capture multiple frames while moving around the object; the user can finish the scan when done.
    • Success measure: Run the app → New scan → Start → move the device and observe frame count increasing → Finish scan. Verification: scan proceeds to processing and/or frames are stored (e.g., in app storage for the session).
    • Demonstration: Start a scan, capture at least 10–15 frames, finish; confirm transition to the processing screen and that reconstruction runs or that frame files exist for the session.

  2. Run 3D reconstruction and show progress

    • Requirement: The app shall run a reconstruction pipeline (e.g., BoofCV: similar images, pairwise, metric, bundle adjustment, dense point cloud) on the captured frames and show progress to the user until completion.
    • Success measure: After finishing a scan, a processing screen shows progress (e.g., progress bar and/or status text); when done, the user can open the result (e.g., “View result”).
    • Demonstration: Complete a scan with sufficient frames → observe processing UI → on success, tap “View result” and reach the 3D viewer with a visible mesh/point cloud.

  3. Display 3D model in an interactive viewer

    • Requirement: The app shall display the reconstructed 3D model (PLY) in a viewer where the user can rotate and zoom to inspect the model.
    • Success measure: In the viewer screen, the 3D model is visible and responds to touch (rotate/zoom).
    • Demonstration: After a successful scan or from the gallery, open a scan → confirm the model renders and that gesture controls change the view.

  4. Export: Save to Downloads and Share

    • Requirement: From the viewer, the user shall be able to save the 3D model to an app-accessible location (e.g., Downloads/Goose3D) and to share it via the system share sheet (e.g., Drive, email).
    • Success measure: Tap “Save to Downloads” → file appears in the app’s export folder (e.g., Downloads/Goose3D); tap “Share” → system share UI appears and a file can be sent to another app.
    • Demonstration: View a scan → Save to Downloads → verify file in export folder; Share → choose a target app and confirm the file is shared.

  5. Gallery: list, open, rename, and delete saved scans

    • Requirement: The app shall maintain a gallery of saved scans (thumbnails and titles), allow opening a scan in the same viewer, and support renaming and deleting entries.
    • Success measure: Save a scan to gallery → it appears in Gallery with thumbnail and title; tap to open in viewer; rename and delete work and persist after app restart.
    • Demonstration: Complete a scan → Save to gallery with a name → open Gallery → see the item → open in viewer → rename → confirm new name → delete another item → confirm it is removed and that list state persists after restart.

  6. Optional camera calibration and use in scans

    • Requirement: The app shall allow the user to capture checkerboard calibration images (with on-screen guidance), run calibration, and save it per camera/resolution; when available, reconstruction shall use this calibration.
    • Success measure: Open Calibrate → follow instructions → add at least 5 checkerboard images → Run calibration → see success; perform a new scan and confirm reconstruction runs (with or without calibration key as implemented).
    • Demonstration: Calibrate using a printed checkerboard (e.g., 8×6 inner corners, 3 cm squares) → run calibration → start a new scan and complete reconstruction to show calibration is used when present.

  7. Open external .ply files in the viewer

    • Requirement: The app shall accept “Open with” for .ply files (file or content URI) and display the mesh in the same 3D viewer.
    • Success measure: From another app or file manager, open a .ply file with Goose3D; the viewer opens with that model.
    • Demonstration: Use “Open with” from a file manager or share sheet with a .ply file → Goose3D opens and shows the model in the viewer.

  8. Show BoofCV attribution

    • Requirement: The app shall display attribution for 3D reconstruction (e.g., BoofCV) in a user-visible location (e.g., Home screen).
    • Success measure: On the main/home screen, attribution text (e.g., “3D reconstruction uses BoofCV”) is visible.
    • Demonstration: Open app → Home → confirm attribution text is present.

Note: Six is the minimum; eight are listed to align with the current feature set. Grading can use all must-have requirements in this document.

Section 2b: Stretch Requirements

  1. Turntable sync (optional)

    • Requirement: The app may support a “turntable” mode where it waits for the object to stop moving (or a trigger) before capturing each frame, to improve alignment.
    • Success measure: If implemented: enable turntable mode, place object on turntable, run scan; frames are captured at stable poses.
    • Demonstration: Use turntable sync (if available) and show that frame capture is gated as designed; if not implemented, this section does not apply and can state “Not implemented.”

  2. Fixed world frame and scaled output (e.g., for 3D printing)

    • Requirement: The app may support a fixed checkerboard world frame so that reconstruction scale is known (e.g., in mm) and suitable for 3D printing.
    • Success measure: If implemented: perform calibration with world frame, run scan; exported model has correct scale (e.g., known dimensions).
    • Demonstration: Calibrate with world frame, scan an object of known size, export and verify scale in a third-party tool; if not implemented, state “Not implemented.”

  3. STL (and/or OBJ) export

    • Requirement: The app may export the 3D model in STL or OBJ format in addition to (or instead of) PLY for compatibility with other tools.
    • Success measure: From the viewer, user can save or share in STL/OBJ; the file opens correctly in another application.
    • Demonstration: Export as STL/OBJ and open in a 3D viewer or slicer; if only PLY is implemented, state “PLY only; STL/OBJ not implemented.”

  4. Mesh cleanup / watertight option

    • Requirement: The app may offer mesh cleanup or watertight conversion to improve usability for 3D printing or other downstream use.
    • Success measure: If implemented: run cleanup/watertight on a scan; exported mesh is closed or otherwise improved.
    • Demonstration: Run the option on a scan and compare before/after in an external tool; if not implemented, state “Not implemented.”

Four stretch requirements are listed; you may have more. Any that do not apply should state why (e.g., “Not implemented for this release”).

Section 2c: Schedule

Weekly overview of project progress. Overall status has remained on schedule.

Week Date Accomplishments / Focus Status
1 [Pre–1/24] Setup, research, project proposal. —
2 [Pre–1/24] Continued setup and planning. —
3 1/24/26 Wireframe made for the UI. UML created. Photogrammetry tools chosen (BoofCV). Plans: Get BoofCV working independently (Structure from Motion); create the UI. On schedule
4 1/31/26 UI implemented. BoofCV explored and working. Plans: Get a prototype of the UI working; start implementing BoofCV into the app. On schedule
5 2/7/26 Prototype app with opening screen and options for scanning and viewing gallery; scanning and gallery still in progress. Near-complete BoofCV prototype (simulation issues in progress). Plans: Get BoofCV simulation to work; implement BoofCV into the app. On schedule
6 2/14/26 Camera calibration set up: checkerboard printed and calibration implemented in the app. Point cloud currently sporadic; improvement needed. Plans: Finish calibration integration; improve 3D rendering. Exploring turntable + checkerboard-background setup for scanning. On schedule
7 2/21/26 [Improve 3D rendering; complete calibration integration; export and gallery polish.] —
8 2/28/26 [Open with .ply; BoofCV attribution; full scan → view → export flow verified.] —
9 3/7/26 [Gallery rename/delete; stretch goals or refinement; begin requirement verification.] —
10 3/14/26 [Requirement verification and testing per Section 4; fix issues.] —
11 3/21/26 [Final testing; edge cases (reconstruction failure, permissions, empty gallery).] —
12 3/28/26 [Documentation finalization; demo script and data preparation.] —
13 4/4/26 [Demo rehearsal; requirements document and submission prep; buffer for slip.] —

Hours (as reported): Week 3 total 21 hrs; Week 4 total 30 hrs; Week 5 total 39 hrs; Week 6 total 48 hrs. Anticipated total at completion (as of Week 6): ~78 hrs.

Section 3: Overview of the Product

Workflow

  • Inputs: Device camera (back), optional checkerboard for calibration; optional external .ply file (Open with).
  • Process A — New scan: User opens app → Home → New scan → Start → captures frames while moving around object → Finish scan → app stores frames (and optional calibration key) → Process screen runs reconstruction (BoofCV pipeline) → output PLY saved.
  • Output of A / Input to B: Reconstructed PLY (and scan session data).
  • Process B — View and export: User sees “View result” → Viewer shows 3D model (rotate/zoom) → user can Save to Downloads, Share, or Save to gallery. Saving to gallery adds the scan to the gallery index and file storage.
  • Process C — Gallery: User goes Home → Gallery → sees list of saved scans → tap to open in same Viewer → from there, export/share, or return and use Rename/Delete. Gallery data is persisted (e.g., index.json + mesh/thumbnail files).
  • Process D — Calibration (optional): Home → Calibrate → (optional) View calibration instructions → Add image (×5 or more) with checkerboard in frame → Run calibration → result saved per camera/resolution and used in subsequent scans when available.
  • Process E — Open with: User selects a .ply file in another app → “Open with” Goose3D → app opens Viewer with that mesh (no scan session).

Requirements map to these phases: capture (Req 1), reconstruction (Req 2), viewer (Req 3), export (Req 4), gallery (Req 5), calibration (Req 6), Open with (Req 7), attribution (Req 8).

Resources

  • In the product:
    • Camera (back): Used for scan frames and calibration images (Camera2 API).
    • Storage: App-private filesDir (scan sessions, gallery index and files, calibration YAML); cacheDir for opened-from-external PLY; app-specific Downloads folder (e.g., .../Downloads/Goose3D) for export.
    • BoofCV: Used for calibration, structure-from-motion, metric reconstruction, bundle adjustment, dense point cloud (and mesh if applicable). BoofCV can be from Maven or a local clone (e.g., -PuseLocalBoofcv=true).
    • Android SDK: Min SDK 26+, target SDK 35; Navigation Component, ViewModel, Lifecycle, Material components, ConstraintLayout, RecyclerView, etc.
    • Third-party: BoofCV (boofcv-android, reconstruction, io, types); AndroidX libraries (see build.gradle).
  • Tiers: Single-tier, client-only (Android app). No server or cloud; all processing and storage on device.

Data at Rest

  • User profile / login: Not applicable — no user accounts or login.
  • Application data:
    • Scan sessions: Under filesDir/goose3d_scans/<scanId>/: frame images, frames.txt, meta.txt, optional calibrationKey.txt, output cloud.ply.
    • Gallery: filesDir/gallery/: index.json (id, title, meshPath, thumbnailPath, createdAt), mesh copies (e.g., g_<id>.ply), thumbnails (e.g., g_<id>_thumb.png).
    • Calibration: filesDir/goose3d_calibration/: one YAML per camera+resolution (e.g., {cameraId}_{width}x{height}.yaml).
    • Export: App-specific Downloads folder (e.g., getExternalFilesDir(DIRECTORY_DOWNLOADS)/Goose3D/) or legacy public Downloads; files named with timestamp.
    • Opened .ply: Copy in cacheDir (e.g., opened_<timestamp>.ply) when opened via content URI.
  • Storage model: File-based only (no Room/SQLite or SharedPreferences for scan/gallery/calibration data).

Data on the Wire

  • Not applicable. All data stays on the device. No central server, no cloud sync, no network transmission of scan or gallery data. Export and Share send files only when the user explicitly saves or shares (e.g., to another app or cloud app chosen by the user).

Data State / Process Flow

High-level flow:

  1. Scan: Camera → frames → stored in goose3d_scans/<scanId>/; optional calibration key reference.
  2. Reconstruction: Frames + calibration (if any) → BoofCV pipeline → cloud.ply in same scan dir.
  3. Viewer: Reads PLY (from scan dir, gallery copy, or cache for “Open with”) → renders in OpenGL; user actions (Save/Share/Save to gallery) read from same source.
  4. Gallery: Add = copy PLY + create thumbnail → update index.json and files in gallery/. Delete = remove entry and files. Rename = update title in index.json.
  5. Calibration: Images → BoofCV calibration → YAML saved in goose3d_calibration/; scan references it by camera+resolution.
  6. Export: Read PLY from current source → write to export folder and/or provide URI to Share.

A state flow diagram can be drawn with: Idle (Home) → Scanning → Processing → Viewing → (back to Idle or Gallery); Gallery → Viewing → (back to Gallery or Idle); Calibrate (sub-flow: capture images → run calibration → Idle). Data flow: Camera → Frames → Reconstruction → PLY → Viewer/Export/Gallery.

HMI / HCI / GUI

  • Shell: Single Activity (MainActivity) with Material toolbar and NavController; start destination = Home; back/up via toolbar.
  • Screens (prototypes / descriptions):
    • Home: App name; prominent buttons: New scan (primary), Gallery, Calibrate; BoofCV attribution at bottom.
    • New scan: Full-area camera preview (TextureView); bottom bar: frame count, tips (e.g., “fill frame, rotate slowly, 30+ frames”), Start / Finish scan.
    • Process: Progress bar and status text; on success: “View result” button.
    • Viewer: Full-screen 3D (GLSurfaceView); bottom bar: Save to Downloads, Share, Save to gallery, Open with….
    • Gallery: RecyclerView of cards (thumbnail, title, subtitle); per-item: Rename, Delete; empty state: “No scans yet. Create one from New scan.”
    • Calibrate: Camera preview; “View calibration instructions” link; Add image; Run calibration (enabled when enough images); image count (e.g., “Images: 5 / 5”).
    • Calibration instructions: Static text (checkerboard 8×6, 3 cm squares, 5+ images, lighting, etc.).

Include screenshots or wireframes in the final document when available; the above describes what the user will see.

Section 4: Verification

Demo

  • How: Run the app on a target device (e.g., Samsung Galaxy S24 Ultra or similar) and walk through the main flows with real data.
  • Data: Use a physical object (e.g., small figurine or box); use a printed checkerboard (8×6 inner corners, 3 cm squares) for calibration; have at least one .ply file for “Open with.”
  • Steps:
    1. New scan: Home → New scan → Start → capture 30+ frames around object → Finish → wait for processing → View result → confirm 3D model in viewer; rotate/zoom.
    2. Export: From viewer → Save to Downloads → confirm file in Goose3D folder; Share → send to another app.
    3. Gallery: Save to gallery with a name → Home → Gallery → open scan in viewer → Rename → Delete one item → restart app and confirm list state.
    4. Calibration: Calibrate with checkerboard → run a new scan and confirm reconstruction.
    5. Open with: Open a .ply from file manager with Goose3D → confirm viewer shows the model.
    6. Attribution: Confirm BoofCV text on Home.

Testing (per requirement)

  • Req 1 (Capture): Start scan, capture N frames, finish; verify processing starts and/or frame files exist. Failure: no frames stored or count does not increase.
  • Req 2 (Reconstruction): Run scan with sufficient frames; verify progress UI and “View result”; open viewer and see mesh. Failure: crash, hang, or no mesh after success.
  • Req 3 (Viewer): Open a scan or external PLY; verify render and touch (rotate/zoom). Failure: blank screen or no response to gestures.
  • Req 4 (Export): Save to Downloads and Share; verify file on disk and share target receives file. Failure: file missing or share intent does not provide file.
  • Req 5 (Gallery): Add, list, open, rename, delete; restart and re-check. Failure: missing item, wrong title, or delete not persisting.
  • Req 6 (Calibration): Complete calibration flow; run scan; verify reconstruction uses calibration when available. Failure: calibration not saved or not used.
  • Req 7 (Open with): Open .ply with Goose3D; verify viewer shows model. Failure: app does not open or model not displayed.
  • Req 8 (Attribution): Open Home; verify BoofCV text visible. Failure: text missing.

For each requirement, define acceptable range (e.g., “at least one scan can be completed end-to-end”) and when it is not fulfilled (e.g., crash, missing feature, or wrong behavior).

Sources / Citations / Resources

Document generated from analysis of the Goose3D Android app codebase. Team members and schedule should be filled in by the project team. Convert to Word as needed for submission.