User Guides/USER_GUIDE.md

# Blueprint Diamond Detector — User Guide

## What Does This Tool Do?

The Blueprint Diamond Detector scans construction blueprint PDFs for diamond-shaped unit symbols (e.g. A1, B2, C3) using computer vision and optical character recognition (OCR). It finds every diamond on every page, reads the letter-number code inside each one, counts how many of each code appear, and produces annotated output files you can review and export.

---

## Step 1 — Open the App

Navigate to the app URL in your browser. You will see three tabs at the top:

- **Input** — where you upload files and start the analysis
- **Output (locked)** — where results and downloads appear after analysis
- **Validate (locked)** — where you can review and correct individual detections

The Output and Validate tabs show **(locked)** until an analysis has completed.

---

## Step 2 — Upload Your Files

All uploading is done on the **Input** tab.

### Blueprint PDF (required)

Click **Browse files** under "Blueprint PDF" and select the PDF containing your construction blueprints. Only PDF files are accepted. Multi-page PDFs are fully supported.

Once a file is selected, the app will display how many pages were detected and an estimated processing time.

### Legend Image (optional but recommended)

The legend, sometimes called a window schedule or type mark schedule, is a table that lists all valid unit codes used on the blueprints. Uploading a screenshot or scan of this table allows the tool to:

- Mark each detected code as **confirmed** (found in the legend) or **flagged** (not found in the legend)
- Apply colour coding to the output files so you can visually identify which detections are correct

Accepted formats: PNG, JPG, JPEG, BMP, TIFF, WEBP.

If you do not upload a legend, the tool still detects all diamonds but cannot tell you whether a detected code is expected or not.

---

## Step 3 — Run the Analysis

Click the **Run Analysis** button. The button is disabled if no blueprint PDF has been uploaded.

Once clicked, the app re-renders with all inputs disabled and a progress section appears above the tabs showing:

- A progress bar that advances as each page completes
- A status line for each page indicating whether it is currently being processed or has finished, along with the time taken

**Processing time** is approximately 5–8 minutes per page on a single CPU. Pages are analysed two at a time in parallel, so the estimated total time is roughly `ceil(pages / 2) × 5–8 minutes`. Do not close the browser tab while analysis is running.

---

## Step 4 — Review Results in the Output Tab

When analysis completes the Output and Validate tabs unlock automatically and you are taken to the Output tab.

### Detection Summary Table

A pivot table is shown with:

- **Rows** — one per detected code (e.g. A1, B2)
- **Columns** — one per page of the blueprint, plus a Total column
- **Values** — how many times each code appears on each page

If a legend was uploaded, each row label shows one of three states:

| Label suffix | Meaning |
|---|---|
| `[valid]` | Code was found in the legend — expected detection |
| `[flagged]` | Code was detected but is not in the legend — may be an error |
| `?` | A diamond shape was found but OCR could not read the code inside |

The bottom row of the table shows totals across all codes.

> **Note:** The summary table and CSV download reflect any corrections you make in the Validate tab in real time.

### Downloads

Three files are available to download:

#### Annotated PDF
The original blueprint pages with a coloured bounding box drawn around each detected diamond and the recognised code printed above it.

Colour coding:
- **Green** — confirmed (code is in the legend, or no legend was uploaded)
- **Red** — flagged (code was read but is not in the legend)
- **Blue** — shape only (diamond outline detected but OCR could not read the code)

#### CSV Report
A spreadsheet-ready pivot table of detection counts, one row per code and one column per page. If a legend was uploaded, the legend's own columns are included alongside the counts.

> The CSV always reflects the most recent validated state — any corrections made in the Validate tab are included automatically without needing to regenerate.

#### Detections-Only PDF
One page per blueprint page, showing every detected diamond crop arranged in a grid from left to right, top to bottom on a white background. The same green/red/blue colour coding is applied to the bounding boxes. This file is useful for a quick visual scan to catch false positives or misread codes.

---

## Step 5 — Validate and Correct Detections

The **Validate** tab lets you review every individual detection and make corrections before exporting your final files.

### Opening a Page Section

Detections are grouped by blueprint page. Each page appears as a collapsed section labelled:

> Page N — X detection(s), Y included

Click any section header to expand it. The section stays open while you make changes — it only collapses if you explicitly click the header again or press **Apply Changes**.

### Scrolling Through Detections

Inside each expanded section, the detection crops are shown in a scrollable area. You can scroll up and down within this area to review all matches without the rest of the page moving. The **Apply Changes** button is always visible below the scrollable area.

### Reading Each Detection Card

Each detection is shown as a small card containing:

1. **The crop image** — a zoomed-in view of that diamond on the original blueprint, with its coloured bounding box visible. Detections are ordered green first, then red, then blue so the most confident matches appear at the top.
2. **Include checkbox** — checked by default. Uncheck this if the detection is a false positive (i.e. the tool found a shape that is not actually a diamond unit symbol).
3. **Code field** — the code the OCR read from inside the diamond. Edit this directly if the code was misread (e.g. change `E1` to `F1`).

### Applying Changes for a Page

After reviewing and editing a page's detections, read the instruction caption beneath the scrollable area, then press:

> **Apply Changes — Page N**

This commits your checkbox and code edits for that page to the app. The Detection Summary table and CSV in the Output tab update immediately to reflect your changes.

Repeat this for each page you wish to correct.

### Regenerating the PDFs

After applying changes across all pages, press the **Regenerate PDFs** button at the bottom of the Validate tab:

> *Once you have applied changes across all pages, press this button to rebuild the annotated and detections-only PDFs so the downloads in the Output tab reflect your edits.*

A success message will confirm the PDFs have been rebuilt. Go to the Output tab to download the updated files.

> **Important:** The CSV download updates live as you apply changes. The two PDF downloads only update when you press Regenerate PDFs.

---

## Running a New Analysis

To analyse a different PDF, go back to the **Input** tab, upload the new file, and press **Run Analysis** again. All previous results, validated edits, and downloaded files from the previous run are cleared automatically when the new analysis starts.

---

## Frequently Asked Questions

**How long will it take?**
Approximately 5–8 minutes per page. Two pages are processed simultaneously, so a 7-page document takes roughly 20–28 minutes.

**Do I have to upload a legend?**
No. Without a legend, the tool still detects all diamonds and reads their codes. The difference is that without a legend there is no confirmed/flagged distinction — all successfully read codes appear in green.

**The code field in the Validate tab shows "?" — what does that mean?**
The tool found a diamond-shaped outline but the OCR could not confidently read the text inside. You can type the correct code directly into the field and press Apply Changes.

**I corrected codes in the Validate tab but the PDFs still show the old codes.**
Press **Regenerate PDFs** in the Validate tab. The summary table and CSV update automatically, but the PDF files are only rebuilt on demand because the process takes a few seconds.

**Can I re-validate after regenerating PDFs?**
Yes. The Validate tab remains active and all your previous checkbox and code edits are preserved. You can continue making changes and regenerating as many times as you like within the same session.

**What happens if I close the browser?**
The session ends and all results are lost. Download your files before closing.