🪑 Overview

FurnishView is a web-based room design tool built for in-store furniture consultations. A designer logs in, inputs a customer's room specifications, places furniture on a 2D top-down canvas, then generates a full 3D walkthrough-ready scene — all in the browser, with no installation required.

Built as coursework for PUSL3122 — HCI & Computer Graphics (2025–26), the project demonstrates layered MVC architecture, hand-coded 2D canvas algorithms, Three.js 3D rendering with proper lighting and shading, and a full user-centred design process backed by formative and summative usability studies.

✨ Key Features

📸 Screenshots & Demos

Landing Page — clean, minimal entry point	Authentication — role-based login (Designer / Admin)
2D Editor — top-down drag-and-drop furniture layout	3D View — orbit-able Three.js scene with shadows
Comparison Mode — two designs rendered side-by-side	Dashboard — design portfolio with saved room cards

🏗️ Architecture

FurnishView enforces strict Model–View–Controller separation. Each layer has a defined responsibility — crossing boundaries is a code smell and is actively avoided.

flowchart TD
    subgraph Models["📦 Models (js/models/)"]
        R[Room.js]
        F[FurnitureItem.js]
        D[Design.js]
    end

    subgraph Views["🖼️ Views (js/views/)"]
        LV[LoginView.js]
        DV[DashboardView.js]
        EV[EditorView.js]
        subgraph Components["components/"]
            TB[Toolbar.js]
            SB[Sidebar.js]
            M[Modal.js]
            T[Toast.js]
        end
    end

    subgraph Controllers["🎮 Controllers (js/controllers/)"]
        DC[DesignController.js]
        CC[CanvasController.js]
    end

    subgraph Graphics["🎨 Graphics (js/graphics/)"]
        R2D[Renderer2D.js]
        R3D[Renderer3D.js]
        CM[ColourManager.js]
    end

    subgraph Utils["🛠️ Utils (js/utils/)"]
        ST[storage.js]
        SC[scaleCalculator.js]
        CN[constants.js]
    end

    app.js -->|initialises| Views
    Views -->|calls| Controllers
    Controllers -->|mutates| Models
    Controllers -->|triggers| Graphics
    Graphics -->|reads| Models
    Graphics -->|uses| Utils
    Controllers -->|uses| Utils
    Models -->|serialised by| ST

Separation of Concerns

Key Design Decisions

• Zero build step — no Webpack, Vite, or npm. Open index.html and it works. Assessed work must run offline.
• Three.js r160 bundled locally in lib/ — CDN failure cannot break submissions.
• MeshStandardMaterial enforced — no MeshBasicMaterial anywhere. All geometry responds to lighting for visible shading.
• preserveDrawingBuffer: true on the WebGL renderer — enables PNG export without a blank canvas bug.

🛠️ Tech Stack

Layer	Technology	Version	Why
Language		ES2022	Module-leader approved, fastest iteration, native browser support
2D Rendering		Native	Hand-coded algorithms demonstrate computer graphics knowledge
3D Rendering		r160	Industry-standard WebGL library; orbit controls, lighting, PBR materials
Styling		CSS3	Design tokens via CSS custom properties, no framework overhead
Storage		Browser API	No backend required; full CRUD on designs as serialised JSON
Build		—	Zero setup for the marker. Clone → open → done.

⚡ Quick Start

Prerequisites

• A modern browser: Chrome 90+ or Firefox 88+ (WebGL and ES modules required)
• For ES module support without a server: use VS Code Live Server extension

Option 1 — Direct File Open (Simplest)

# Clone the repository
git clone https://github.com/deaneeth/furnish-view-hci-project.git
cd furnish-view-hci-project

# Open in your browser
# On Windows:
start index.html
# On macOS:
open index.html
# On Linux:
xdg-open index.html

⚠️ Some browsers block ES module imports from file:// URLs. If the app shows a blank screen, use Option 2.

Option 2 — VS Code Live Server (Recommended)

1. Open the project folder in VS Code
2. Install the Live Server extension if not already installed
3. Right-click index.html → Open with Live Server
4. App opens at http://127.0.0.1:5500

Option 3 — Simple HTTP Server

# Python 3
python -m http.server 8080
# Then visit http://localhost:8080

# Node.js (npx, no install needed)
npx serve .
# Then visit http://localhost:3000

Test Credentials

🔐 Authentication

FurnishView uses a client-side, role-based authentication system backed entirely by localStorage.

furnishview_users    → Array of registered designer credentials
furnishview_session  → Currently active session (cleared on logout)
furnishview_designs  → All saved Design objects (filtered per designer on load)

Session persists across browser refreshes until the user explicitly logs out. No cookies, no tokens, no network calls.

🔬 Feature Deep-Dive

scaleFactor = canvasWidth / roomWidthInMeters
pixelX = realWorldX × scaleFactor
pixelY = realWorldY × scaleFactor

isHit = (clickX >= item.x) && (clickX <= item.x + item.width)
     && (clickY >= item.y) && (clickY <= item.y + item.depth)

item.x = clamp(item.x, 0, room.width - item.width)
item.y = clamp(item.y, 0, room.depth - item.depth)

offset.x = mouseX - item.x
offset.y = mouseY - item.y

// Core pipeline
Scene → PerspectiveCamera → WebGLRenderer (preserveDrawingBuffer: true) → OrbitControls

// Lighting (critical for shading marks)
AmbientLight(0xffffff, 0.6)      // Base illumination
DirectionalLight(0xffffff, 0.8)  // Creates shadows + visible shading

const dataURL = renderer.domElement.toDataURL('image/png')
// Works because preserveDrawingBuffer: true was set on construction

📁 Project Structure

furnish-view-hci-project/
├── index.html                    # Entry point — loads js/app.js as ES module
│
├── css/
│   ├── main.css                  # Global styles, CSS custom properties, layout
│   ├── components.css            # Toolbar, Sidebar, Modal, Toast styles
│   └── canvas.css                # 2D/3D canvas container sizing
│
├── js/
│   ├── app.js                    # Initialisation, view routing (login → dashboard → editor)
│   │
│   ├── auth/
│   │   └── auth.js               # Login validation, session management
│   │
│   ├── models/                   # ── Pure data objects, zero DOM/rendering ──
│   │   ├── Room.js               # Dimensions, shape, wall/floor colour
│   │   ├── FurnitureItem.js      # Type, position, dimensions, colour, rotation
│   │   └── Design.js             # One Room + FurnitureItem[] + metadata
│   │
│   ├── views/                    # ── DOM rendering, HTML generation ──
│   │   ├── LoginView.js
│   │   ├── DashboardView.js
│   │   ├── EditorView.js
│   │   └── components/
│   │       ├── Toolbar.js        # Furniture catalogue + action buttons
│   │       ├── Sidebar.js        # Room & furniture property panels
│   │       ├── Modal.js          # Reusable confirmation / wizard modals
│   │       └── Toast.js          # Non-blocking action notifications
│   │
│   ├── controllers/              # ── Event handling, logic orchestration ──
│   │   ├── DesignController.js   # CRUD design workflow
│   │   └── CanvasController.js   # Mouse/touch events on 2D canvas
│   │
│   ├── graphics/                 # ── All rendering logic ──
│   │   ├── Renderer2D.js         # HTML5 Canvas 2D engine (hand-coded algorithms)
│   │   ├── Renderer3D.js         # Three.js scene manager
│   │   └── ColourManager.js      # Colour sync across 2D + 3D views
│   │
│   ├── utils/
│   │   ├── storage.js            # localStorage CRUD wrapper
│   │   ├── scaleCalculator.js    # Real-world ↔ pixel/unit conversions
│   │   └── constants.js          # App-wide constants, default values
│   │
│   └── data/
│       ├── furnitureCatalogue.js # Furniture type definitions + default dimensions
│       └── roomPresets.js        # Pre-built room templates (innovation feature)
│
├── lib/                          # Three.js r160 — committed, works offline
│   ├── three.module.js
│   ├── three.min.js
│   └── OrbitControls.js
│
├── assets/
│   ├── screenshots/              # App screenshots for README and report
│   ├── textures/                 # Optional floor/wall texture maps
│   └── sample-data/              # Pre-loaded designs for demo (video)
│
├── formative-docs/               # Formative usability study documentation
│   ├── P1.md / P2.md             # Raw observer session notes
│   ├── participant-P1.md         # Structured observation sheet — P1
│   ├── participant-P2.md         # Structured observation sheet — P2
│   ├── observer-sheet.md         # Study summary and findings
│   └── observation-sheet-RESEARCHER-USE.md  # Filled researcher log
│
└── requirements/
    ├── PROJECT OVERVIEW.md       # Full project blueprint and architecture spec
    ├── End-to-End-Project-Roadmap.md  # Phase-by-phase implementation roadmap
    └── REPO_WORKFLOW.md          # Branch, commit, and PR conventions

🧪 Testing & Evaluation

FurnishView underwent a two-phase HCI evaluation following the think-aloud protocol and System Usability Scale (SUS) methodology.

Formative Study (Pre-Implementation)

Key findings that shaped the hi-fi design:

• The "3D View" toggle was labelled "Visualise" in the lo-fi prototype — participants did not associate it with 3D. → Renamed to "3D View" in hi-fi.
• The undo button was missing from the lo-fi toolbar — P1 accidentally deleted furniture and could not recover. → Undo added as a persistent toolbar action.
• Toolbar icons were considered too small on a tablet-sized display. → Icons enlarged to 32 × 32px minimum in hi-fi.
• P2 expected clicking a furniture item to open its properties automatically. → Sidebar refreshes on item selection in implementation.

Summative Study (Post-Implementation)

Key SUS interpretation: Score 78.75 places FurnishView in the "Good" tier (above the industry average of 68), indicating the interface is learnable, efficient, and satisfying for the target user demographic.

Areas for further improvement identified:

• 3D scene takes slightly longer to load for rooms with many items (optimisation opportunity)
• Rotation handle for furniture on the 2D canvas was not immediately discoverable (discoverability improvement needed)

🎯 HCI Framework Alignment

Nielsen's 10 Usability Heuristics (Nielsen, 1994)

Norman's Design Principles (Norman, 1988)

🤝 Contributing

This is academic coursework — external PRs are not expected, but team contributions are tracked via Git.

For team members:

1. Branch from dev — never commit directly to main

   git checkout dev
   git pull origin dev
   git checkout -b feature/your-feature-name

2. Follow the commit convention from requirements/REPO_WORKFLOW.md:

   feat(canvas): implement drag-and-drop furniture placement
   fix(3d): resolve shadow rendering on wall geometry
   docs(eval): add summative study observation notes
   

3. Open a PR to dev with a description that references the relevant task from the roadmap
4. Get at least one review before merging
5. Never merge broken code — verify index.html opens without console errors first

👥 Team

Dineth Hettiarachchi Lead Developer Architecture · 2D Engine · 3D Scene · Innovation Features

Lakindu Pahesara Design Lead Personas · Storyboards · Lo-Fi / Hi-Fi Prototypes · Report

Thanuji Kalanika Evaluation Lead Test Plans · User Studies · SUS Scoring · Consent Forms

📜 License & Credits

License

This project is submitted as academic coursework for PUSL3122 at Plymouth University Sri Lanka. All original source code is available under the MIT License for reference purposes.

MIT License — Copyright (c) 2026 Dineth Hettiarachchi and contributors

Third-Party Credits

Key References

• Nielsen, J. (1994). 10 Usability Heuristics for User Interface Design. NN/g.
• Norman, D. (1988). The Design of Everyday Things. Basic Books.
• Preece, J., Sharp, H. & Rogers, Y. (2019). Interaction Design. 5th ed. Wiley.
• Brooke, J. (1996). SUS: A Quick and Dirty Usability Scale.
• Dirksen, J. (2018). Learn Three.js. 3rd ed. Packt.
• Angel, E. & Shreiner, D. (2014). Interactive Computer Graphics. 7th ed. Pearson.
• MDN Web Docs — Canvas API
• Three.js Documentation — threejs.org/docs