PROJECTION MAPPER  -  plain-English guide
=========================================

What it is
----------
A Windows program that turns your projector into a house-decorating machine.
Point the projector at the front of your house, and the app puts spooky (or
Christmas) animations exactly onto the windows, door, garage door, roofline,
trees and walls, with a hole cut out for each window so nothing spills over.

It uses your laptop's graphics card (your Nvidia GPU) to draw everything, and
a small AI model to find the windows, doors, walls and trees in a photo for you.

Nothing to install. Just run ProjectionMapper.exe. (It needs Microsoft Edge or
Google Chrome, which Windows 10/11 already has.)

First time starting it
----------------------
1. Double-click ProjectionMapper.exe.
   Windows may say "Windows protected your PC" because the program is new.
   Click "More info", then "Run anyway".
2. A control window opens on your laptop screen.
3. Plug in the projector. Press Win + P and choose "Extend".

Quick tour (try this first, no camera needed)
---------------------------------------------
1. Step 1, "Projector display": pick the projector in the list, click
   "Open on projector". A black window appears on the projector, fullscreen.
   Click "Test pattern": the red border should touch all 4 edges.
2. Step 2: click "Demo house". A pretend house shows up.
3. Step 6: click "Halloween preset" or "Christmas preset". The house lights up
   on the projector. Each preset has several scenes that play one after another.

Using your real house
---------------------
There are two ways. Webcam is automatic. A photo needs a little dragging.

A) With a webcam (best)
   1. Place the webcam where it can see the whole front of the house. Put it on
      something steady. Do not move it afterwards.
   2. Step 2: pick the webcam, click "Start webcam", and allow the camera when
      asked.
   3. Wait until it is fairly dark (dusk is best).
   4. Step 3: click "Auto-calibrate with webcam". The projector flashes 12 dots
      one by one (about 15 seconds). The webcam finds them and learns how the
      projector lines up with your house. It tells you how accurate it is.
   5. Step 4: click "Detect walls, windows, doors, roof, trees". The AI draws
      outlines on the picture. (The webcam picture becomes the house picture.)
   6. Fix anything it got wrong (see "Editing" below).

B) With a photo (no webcam)
   1. Step 2: "Load photo..." and choose a straight-on picture of the house.
   2. Step 4: run the AI detect.
   3. Step 3: click "Manual photo alignment". Switch to Projector view. A
      see-through copy of your photo is projected onto the house. Drag the 4
      yellow corners until the projected picture lines up with the real house.
      Click the button again when done.

Editing (the AI is never perfect)
---------------------------------
Click a surface in the list or in the preview.
 - White dots = the outline. Drag to move. Double-click an edge to add a dot.
   Right-click a dot to remove it. Hold Alt and drag to move the whole shape.
 - Colored squares = the 4 corners the animation is bent to. Drag to fix the
   fit on slanted or odd surfaces.
 - "House picture view" edits on the photo. "Projector view" edits what the
   projector actually shows, which is handy for fine nudging while you stand
   outside looking at the house.
 - "+ Rectangle" and "+ Draw shape" add your own surfaces. Delete key removes.

What can play on a surface
--------------------------
 Halloween: flames, lightning storm, ghostly fog, toxic slime, pumpkin glow,
   jack-o'-lantern face, haunted window with a moving silhouette, spider web,
   floating ghosts, dripping blood, glowing eyes in the bushes, creepy
   heartbeat, glowing roofline outline.
 Christmas: falling snow, twinkle lights, candy cane stripes, aurora, red and
   green chase, warm window glow, gold glitter, gift wrap with bow (great for a
   garage door), starry sky, roofline bulbs that chase, glowing outline.
 Your own videos and pictures: click "Add files..." in step 9 (mp4/webm/jpg/
   png). Then choose them in a surface's content list. They are stored in the
   "content" folder next to the EXE.
 You can change colors, speed, size and brightness for each surface.

Scenes and playlist (step 6)
----------------------------
A scene says what every surface plays. Add as many scenes as you like. With
"Play scenes in order" ticked, the show cycles through them and fades between
them. While you edit, "hold on the scene I'm editing" keeps the preview on the
scene you are working on.

Live error correction (step 7)
------------------------------
Projectors get bumped, tripods sag, wind shakes things. When this is on, the
projector briefly shows 12 small reference dots every few seconds (default 20).
The webcam measures where they land compared with right after calibration, and
the program shifts the whole show to cancel the drift. You will see a very quick
flicker of dots. Tick "Black screen during check" for a more reliable but more
noticeable reading. "Check now" does one right away. "Reset correction" undoes it.
Needs: webcam running, calibrated with the webcam, projector window open.
It assumes the WEBCAM stays still. If you bump the webcam, calibrate again.

Other settings
--------------
 Step 8: brightness, gamma, and edge blend (only for two overlapping projectors).
 Step 10: save and load projects (stored in the "projects" folder). Your work
   is also saved automatically, and restored the next time you start.
 Blackout (step 1) turns the whole show off instantly.

Folders next to the EXE
-----------------------
 content\   your own videos/pictures
 projects\  saved projects
 projection-mapper.log   what the program is doing. If anything goes wrong,
                         send a screenshot of the log (step 10, bottom of the
                         left panel) or this file.
 browser-profile\  the control window's settings and camera permission.

If something does not work
--------------------------
 - Projector window is on the wrong screen: Close it, pick another display in
   step 1, press Open again. Or click in it and press F for fullscreen.
 - Only one display listed: press Win+P, choose Extend, then "Refresh".
 - "Calibration failed / saw only N dots": make the area darker, aim the camera
   so it sees the lit house, lower the webcam's auto-exposure if it has a setting.
 - Camera asks permission every time: click Allow once; it remembers.
 - AI says it ran on CPU: that is normal and still takes only a few seconds.
 - Red banner at the top = an error. It is also in the log.
 - The program closes by itself when you close the control window.

Honest limits
-------------
 - Houses are not flat. Per-surface fit (step 3) helps. Large depth differences
   (porch vs. wall) may need a nudge of the colored corner squares.
 - The AI knows 150 common things (wall, window, door, tree, grass...). It does
   not know "garage door" by name; it guesses from shape. Roofline comes from the
   top edge of the biggest wall area.
 - Daylight washes out a projector. This is for after dark.
