Updated all notes

Author: Warren-SJ

README.md

@@ -1,17 +1,17 @@
 # Apex Grid
 
-## Live app
+## 🚀 Live app
 
 - Production (deployed): <https://apex-grid-transformer-tracker.vercel.app/>
 - Want to run everything locally? Use the instructions in `Instructions.md`.
 
-## Auth
+## 🔒 Auth
 
 - Log in with `user1`..`user5` using the same value as the password (e.g., `user3`/`user3`).
 - Backend handles user creation/verification on first successful login at `/api/login`.
 - The UI shows “Logged in as username” and records `uploadedBy` for created/updated entities and images.
 
-## Features
+## 💫 Features
 
 - Transformers and Inspections CRUD (App Router API routes with Prisma)
 - Image uploads stored as base64 in the DB; baseline images can be added/removed
@@ -25,7 +25,7 @@
 - Cascade delete: deleting a Transformer removes its Inspections
 - Now available in dark mode!
 
-## Project structure (high level)
+## 🤖 Project structure (high level)
 
 - `frontend/` — Next.js frontend
   - `app/` — App Router pages
@@ -41,7 +41,7 @@
     - `repository/` — Spring Data JPA repositories
     - `service/` — business logic services
 
-## Project Description
+## 📖 Project Description
 
 - The project has 2 main pages: transformers and inspections.
 - The transformers page allows users to create, read, update, and delete (CRUD) transformer records.
@@ -55,7 +55,21 @@
 - An AI model can be used to analyze and generate insights from the thermal images of transformers.
 ![Screenshot of AI inference page](ai_inference.png)
 
-## For Improvements
+## 🔁 CI / CD
+
+This project uses automated deployments for both frontend and backend:
+
+- Frontend (Next.js) — deployed on Vercel
+  - The `frontend/` directory is connected to Vercel via the GitHub integration. Pushes to `main` (or PR merges depending on your Vercel settings) trigger Vercel builds and automatic deployments of the site.
+
+- Backend (Spring Boot) — deployed on Render via DockerHub
+  - A GitHub Actions workflow builds the backend and pushes a Docker image to Docker Hub. See `.github/workflows/docker-image-deployed.yml` for the workflow (it sets up Java, runs `mvn -DskipTests package`, builds the image, and pushes it to Docker Hub).
+  - The workflow expects the following GitHub Secrets to be configured in this repository:
+    - `DOCKERHUB_USERNAME` — Docker Hub account name
+    - `DOCKERHUB_TOKEN` — Docker Hub access token or password
+  - Docker Hub is configured with a repository that Render watches. When the image is pushed, Docker Hub calls the Render deploy hook which triggers Render to deploy the new container image.
+
+## 🤗 For Improvements
 
 - Feel free to open issues or submit PRs for any bugs, improvements, or new features.
 - For your own use, you are free to customize the project as needed.

Working.md

@@ -115,8 +115,26 @@
 - Triggered by `PUT /api/inspections/{id}/boxes/bulk` (unless the caller sets `tuneModel=false`).
 - Archives the previous AI snapshot via `archivePreviousAnalysis`, then records a `ParameterFeedback` row capturing AI/user box counts, diffs, serialized snapshots, and notes.
 - Writes the candidate image to disk, computes added/removed box sets (tolerant to ±0.5 px), and builds a payload with previous/final boxes, faults, annotators, comments, box tolerance, and the current parameter snapshot.
-- Invokes `backend/AI/tune_parameters.py`, which measures HSV statistics for each added/removed box and suggests parameter deltas (e.g., relax warm thresholds for missed hotspots, tighten thresholds for false positives). Small deltas (<1e-6) are filtered out.
-- Applies suggested deltas through `AiParameterService.adjustValue`, which clamps to configured min/max and persists to `ai_model_parameters` (Postgres). Updated values are immediately cached and will be used by subsequent analyses.
+- Invokes `backend/AI/tune_parameters.py`. The tuner runs a deterministic, heuristic adjustment routine based on per-box HSV statistics and the current parameter snapshot. Key points:
+  - Input: the candidate PNG plus a JSON payload containing `parameters` (current values), `addedBoxes` and `removedBoxes` (arrays of `[x,y,w,h]`). The script computes a global `mean_value` from the candidate image's V channel and then measures each box.
+  - Per-box measurements (from `measure_box`) returned for each box include: `pixel_count`, `area_ratio` (box area / image area), `mean_saturation`, `mean_value`, `mean_delta_value` (V − global mean), `warm_fraction` (fraction of pixels whose hue is inside the warm window), `mean_hue` (circular mean in [0,1]) and `max_value`.
+  - Tuning constants (implemented in the script):
+    - SATURATION_MARGIN = 0.01, VALUE_MARGIN = 0.01, CONTRAST_MARGIN = 0.01
+    - HUE_STEP = 0.01, AREA_RATIO_STEP = 0.0005
+  - Adjustment strategy (high-level):
+    - For `added` boxes (human labeled hotspots that the AI missed) the tuner assumes thresholds are too strict. It decreases thresholds to make detection more permissive:
+      - If `warm_sat_threshold - mean_saturation > SATURATION_MARGIN` then `warm_sat_threshold` is decreased by delta = -min(0.05, max(0.005, sat_diff * 0.5)).
+      - Equivalent logic applies to `warm_val_threshold` and `contrast_threshold` using `mean_value` and `mean_delta_value`.
+      - If `min_area_pixels` is larger than the observed `pixel_count`, it is reduced with a bounded step (delta = -min(50.0, max(5.0, pixel_diff * 0.25))).
+      - If the observed area ratios are smaller than `min_area_ratio`, the script reduces `min_area_ratio` by a small step.
+      - If the box's `warm_fraction >= 0.5`, tune the hue window by nudging `warm_hue_low` up or `warm_hue_high` down toward the measured `mean_hue` (bounded by `HUE_STEP`).
+    - For `removed` boxes (AI boxes the user removed) the tuner assumes thresholds are too permissive. It increases thresholds to tighten detection:
+      - If `mean_saturation - warm_sat_threshold < -SATURATION_MARGIN` then `warm_sat_threshold` is increased by a bounded delta (making it harder to count a pixel as warm).
+      - Similar symmetric adjustments are applied for `warm_val_threshold`, `contrast_threshold`, `min_area_pixels` and `min_area_ratio` (using slightly different step factors and bounds).
+      - Hue adjustments mirror the added-case logic but move the hue bounds away from the problematic `mean_hue`.
+  - Update bookkeeping: updates are accumulated per-parameter (the `apply` helper) and tiny deltas (< 1e-6) are filtered out before returning.
+  - Output: the script prints a JSON object containing `parameter_updates` (map of parameter → delta), `notes` (a short summary string), and counts (`addedCount`, `removedCount`).
+- The backend receives these suggested deltas, then `AiParameterService.adjustValue` clamps each new value to configured min/max, persists the update to `ai_model_parameters` (Postgres), and refreshes the in-memory cache so subsequent analyses immediately use the new parameters.
 
 ### Tuning Workflow
 

backend/AI/README.md

@@ -115,6 +115,32 @@ Annotation edit endpoints (server‑side):
 - `DELETE /api/inspections/{id}/boxes?x=&y=&w=&h=` removes a box by geometry (with small tolerance) and updates `faulttypes` accordingly.
 - `POST /api/inspections/{id}/clear-analysis` clears `imageurl`, `boundingboxes`, `faulttypes`, and `lastanalysisweather`.
 
+## AI Tuning Feedback Loop (`ParameterTuningService`)
+
+- Triggered by `PUT /api/inspections/{id}/boxes/bulk` (unless the caller sets `tuneModel=false`).
+- Archives the previous AI snapshot via `archivePreviousAnalysis`, then records a `ParameterFeedback` row capturing AI/user box counts, diffs, serialized snapshots, and notes.
+- Writes the candidate image to disk, computes added/removed box sets (tolerant to ±0.5 px), and builds a payload with previous/final boxes, faults, annotators, comments, box tolerance, and the current parameter snapshot.
+- Invokes `backend/AI/tune_parameters.py`. The tuner runs a deterministic, heuristic adjustment routine based on per-box HSV statistics and the current parameter snapshot. Key points:
+  - Input: the candidate PNG plus a JSON payload containing `parameters` (current values), `addedBoxes` and `removedBoxes` (arrays of `[x,y,w,h]`). The script computes a global `mean_value` from the candidate image's V channel and then measures each box.
+  - Per-box measurements (from `measure_box`) returned for each box include: `pixel_count`, `area_ratio` (box area / image area), `mean_saturation`, `mean_value`, `mean_delta_value` (V − global mean), `warm_fraction` (fraction of pixels whose hue is inside the warm window), `mean_hue` (circular mean in [0,1]) and `max_value`.
+  - Tuning constants (implemented in the script):
+    - SATURATION_MARGIN = 0.01, VALUE_MARGIN = 0.01, CONTRAST_MARGIN = 0.01
+    - HUE_STEP = 0.01, AREA_RATIO_STEP = 0.0005
+  - Adjustment strategy (high-level):
+    - For `added` boxes (human labeled hotspots that the AI missed) the tuner assumes thresholds are too strict. It decreases thresholds to make detection more permissive:
+      - If `warm_sat_threshold - mean_saturation > SATURATION_MARGIN` then `warm_sat_threshold` is decreased by delta = -min(0.05, max(0.005, sat_diff * 0.5)).
+      - Equivalent logic applies to `warm_val_threshold` and `contrast_threshold` using `mean_value` and `mean_delta_value`.
+      - If `min_area_pixels` is larger than the observed `pixel_count`, it is reduced with a bounded step (delta = -min(50.0, max(5.0, pixel_diff * 0.25))).
+      - If the observed area ratios are smaller than `min_area_ratio`, the script reduces `min_area_ratio` by a small step.
+      - If the box's `warm_fraction >= 0.5`, tune the hue window by nudging `warm_hue_low` up or `warm_hue_high` down toward the measured `mean_hue` (bounded by `HUE_STEP`).
+    - For `removed` boxes (AI boxes the user removed) the tuner assumes thresholds are too permissive. It increases thresholds to tighten detection:
+      - If `mean_saturation - warm_sat_threshold < -SATURATION_MARGIN` then `warm_sat_threshold` is increased by a bounded delta (making it harder to count a pixel as warm).
+      - Similar symmetric adjustments are applied for `warm_val_threshold`, `contrast_threshold`, `min_area_pixels` and `min_area_ratio` (using slightly different step factors and bounds).
+      - Hue adjustments mirror the added-case logic but move the hue bounds away from the problematic `mean_hue`.
+  - Update bookkeeping: updates are accumulated per-parameter (the `apply` helper) and tiny deltas (< 1e-6) are filtered out before returning.
+  - Output: the script prints a JSON object containing `parameter_updates` (map of parameter → delta), `notes` (a short summary string), and counts (`addedCount`, `removedCount`).
+- The backend receives these suggested deltas, then `AiParameterService.adjustValue` clamps each new value to configured min/max, persists the update to `ai_model_parameters` (Postgres), and refreshes the in-memory cache so subsequent analyses immediately use the new parameters.
+
 ## Known bugs / limitations
 
 - Alignment fragility: SIFT may fail on low‑texture or uniform images; homography requires sufficient matches. We fall back to unaligned comparison.

frontend/.env.example

@@ -1 +1 @@
-NEXT_PUBLIC_BACKEND_URL="<your-backend-url>"
+NEXT_PUBLIC_BACKEND_URL=<your-backend-url>