efeitos de altura no 360

Author: dinizime

CLAUDE.md

@@ -23,6 +23,7 @@ npm run dev            # Dev server with auto-restart (--watch)
 npm run migrate        # Import JSON metadata + JPG images into SQLite
 npm run generate-pmtiles  # Generate PMTiles for map markers
 npm run verify         # Validate database integrity
+npm run estimate-slope-roll  # Estimate mesh_rotation_z from elevation data
 npm test               # Run tests (node:test built-in)
 npm run lint           # ESLint (--max-warnings 0)
 npm run lint:fix       # ESLint auto-fix
@@ -51,6 +52,7 @@ src/
 scripts/
 ├── migrate.js             # JSON+JPG → SQLite migration (7-phase)
 ├── generate-pmtiles.js    # PMTiles generation for mapping
+├── estimate-slope-roll.js # Estimate mesh_rotation_z from elevation between consecutive photos
 └── verify.js              # Data validation
 
 public/calibration/        # Calibration web interface
@@ -71,7 +73,7 @@ tests/
 - **projects** — slug, name, location, center coordinates, entry photo ID, photo count
 - **photos** — coordinates, heading, camera_height, mesh_rotation_y/x/z, distance_scale, calibration_reviewed, sequence number
 - **photos_rtree** — R-tree spatial index for geographic queries
-- **targets** — Navigation graph (source→target with distance, bearing, override bearing/distance, hidden flag)
+- **targets** — Navigation graph (source→target with distance, bearing, override bearing/distance/height, hidden flag)
 
 ### {slug}.db (Per-project images)
 - **images** — photo_id → full_webp BLOB + preview_webp BLOB
@@ -89,6 +91,7 @@ tests/
 - Renames `override_heading`/`override_pitch` → `override_bearing`/`override_distance` in `targets`
 - Clamps old `override_pitch < 0.5` values to `5m` default
 - Adds `hidden` column to `targets` (default 0)
+- Adds `override_height` column to `targets` (default NULL)
 
 ## API Endpoints
 
@@ -112,7 +115,7 @@ tests/
 | `PUT /api/v1/photos/:uuid/distance-scale` | Update distance_scale (0.1–5.0) |
 | `PUT /api/v1/photos/:uuid/marker-scale` | Update marker_scale (0.1–5.0) |
 | `PUT /api/v1/photos/:uuid/reviewed` | Mark photo reviewed/unreviewed |
-| `PUT /api/v1/targets/:sourceId/:targetId/override` | Set bearing (0–360°) / distance (0.5–500 m) overrides |
+| `PUT /api/v1/targets/:sourceId/:targetId/override` | Set bearing (0–360°) / distance (0.5–500 m) / height (−10–10 m) overrides |
 | `DELETE /api/v1/targets/:sourceId/:targetId/override` | Clear overrides |
 | `PUT /api/v1/targets/:sourceId/:targetId/visibility` | Set target hidden state (hidden: bool) |
 | `GET /api/v1/photos/:uuid/nearby?radius=100` | Find nearby unconnected photos within radius |
@@ -141,7 +144,7 @@ tests/
     "lon": -55.79, "lat": -29.78, "ele": 100.0,
     "display_name": "IMG_0002",
     "next": true, "distance": 12.5, "bearing": 45.0,
-    "override_bearing": null, "override_distance": null,
+    "override_bearing": null, "override_distance": null, "override_height": null,
     "hidden": false, "is_original": true
   }]
 }
@@ -232,20 +235,27 @@ const imgDb = getProjectDb('alegrete.db');  // Cached per filename
 |-----------|--------|-------|---------|-------------|
 | Heading (Y) | `mesh_rotation_y` | 0–360 | 180 | Yaw correction applied to panorama sphere |
 | Pitch (X) | `mesh_rotation_x` | −30–30 | 0 | Pitch tilt correction |
-| Roll (Z) | `mesh_rotation_z` | −30–30 | 0 | Roll tilt correction |
+| Roll (Z) | `mesh_rotation_z` | −30–30 | 0 | Roll tilt correction (auto-estimated from slope) |
 | Camera height | `camera_height` | 0.1–20 | 2.5 | Height above ground in meters |
 | Distance scale | `distance_scale` | 0.1–5.0 | 1.0 | Multiplier for target distances |
 | Marker scale | `marker_scale` | 0.1–5.0 | 1.0 | Multiplier for navigation marker visual size |
 | Override bearing | `override_bearing` | 0–360 | NULL | Manual target bearing (degrees, 0=North) |
 | Override distance | `override_distance` | 0.5–500 | NULL | Manual target ground distance (meters) |
+| Override height | `override_height` | −10–10 | NULL | Manual target vertical offset (meters, positive = above ground) |
 | Hidden | `hidden` | 0/1 | 0 | Whether target is hidden from navigation (per source→target pair) |
 | Reviewed | `calibration_reviewed` | 0/1 | 0 | Whether calibration has been reviewed |
 
 ### Three.js Rotation Order
 The panorama sphere uses Euler order `ZXY` — matrix `Rz·Rx·Ry` — meaning Y (heading) is applied first to pixels, then X (pitch), then Z (roll) in the corrected frame. Both `viewer.js` (calibration) and `street_view_viewer.js` (ebgeo_web) must use the same order.
 
+### Elevation Delta in Projection
+When both camera and target have `ele` data, the elevation difference `ΔE = target.ele - camera.ele` offsets the target marker vertically: `y = -cameraHeight + ΔE`. This affects marker Y position, flatten ratio, and slant distance for marker sizing. Clamped to ±2m (`MAX_ELEVATION_DELTA`) to protect against GPS noise. When either `ele` is null, `ΔE = 0` (flat ground fallback).
+
+### Slope Roll Estimation
+`scripts/estimate-slope-roll.js` estimates `mesh_rotation_z` (roll) from elevation data between a photo and its `next` target: `θ = atan2(ΔE, distance)`. Slopes beyond `--max-angle` (default 15°, recommended 10°) are **discarded** as GPS noise (set to 0), not clamped. Supports `--dry-run`, `--clear`, `--project <slug>`, `--max-angle <N>`.
+
 ### Target Override Projection
-Override markers use a **ground-plane model**: bearing + ground distance are projected onto `y = -cameraHeight` plane, NOT spherical coordinates. Both `navigator.js` (calibration) and `navigation/navigator.js` (ebgeo_web) use `projectFromOverride()` for this.
+Override markers use a **ground-plane model**: bearing + ground distance + height are projected onto `y = -cameraHeight + overrideHeight` plane, NOT spherical coordinates. Both `navigator.js` (calibration) and `navigation/navigator.js` (ebgeo_web) use `projectFromOverride()` for this. Override markers do **not** use GPS elevation delta — the height is manually controlled via a slider in the calibration UI. When `override_height` is NULL/0, the marker sits on the ground plane exactly where the user clicked.
 
 ## Calibration UI Architecture
 
@@ -273,10 +283,10 @@ app.js (orchestrator)
 3. Grid toggle — perspective grid on/off
 4. Save/Discard buttons — enabled when dirty
 5. Review actions — mark reviewed, reviewed → next
-6. **Collapsible**: Parametros de Calibracao — 6 sliders (rotation_y/x/z, height, distance/marker_scale)
+6. **Collapsible**: Parametros de Calibração — 6 sliders (rotation_y/x/z, height, distance/marker_scale)
 7. **Collapsible**: Aplicar ao Projeto — batch update buttons
 8. **Collapsible**: Targets (N) — clickable target list with override/hidden badges
-9. Override editor — bearing/distance sliders, set-from-click, hide/show, delete (when target selected)
+9. Override editor — bearing/distance/height sliders, set-from-click, hide/show, delete (when target selected)
 10. **Collapsible**: Fotos Proximas (N) — nearby unconnected photos with Preview toggle
 11. Fotos do Projeto — full photo list with review status
 

EXPANDING.md

@@ -208,7 +208,7 @@ curl -o test_preview.webp "http://localhost:8081/api/v1/photos/<entryPhotoId>/im
 curl -o test_full.webp "http://localhost:8081/api/v1/photos/<entryPhotoId>/image?quality=full"
 ```
 
-### Testar calibracao
+### Testar Calibração
 
 Abra `http://localhost:8081/calibration/` no navegador e selecione o novo projeto no seletor.
 

package.json

@@ -9,6 +9,7 @@
     "dev": "node --env-file=.env --watch src/server.js",
     "migrate": "node scripts/migrate.js",
     "recalculate-targets": "node scripts/recalculate-targets.js",
+    "estimate-slope-roll": "node scripts/estimate-slope-roll.js",
     "generate-pmtiles": "node scripts/generate-pmtiles.js",
     "verify": "node scripts/verify.js",
     "test": "node --test tests/**/*.test.js",

public/calibration/js/api.js

@@ -83,18 +83,23 @@ export async function saveCameraHeight(photoId, cameraHeight) {
 }
 
 /**
- * Saves a target bearing/distance override.
+ * Saves a target bearing/distance/height override.
  * @param {string} sourceId - Source photo UUID
  * @param {string} targetId - Target photo UUID
  * @param {number} bearing - Override bearing in degrees (0-360)
  * @param {number} distance - Override ground distance in meters (0.5-500)
+ * @param {number} [height=0] - Vertical offset in meters (-10 to +10)
  * @returns {Promise<Object>} Server response
  */
-export async function saveTargetOverride(sourceId, targetId, bearing, distance) {
+export async function saveTargetOverride(sourceId, targetId, bearing, distance, height = 0) {
     const response = await fetch(`${BASE}/targets/${sourceId}/${targetId}/override`, {
         method: 'PUT',
         headers: { 'Content-Type': 'application/json' },
-        body: JSON.stringify({ override_bearing: bearing, override_distance: distance }),
+        body: JSON.stringify({
+            override_bearing: bearing,
+            override_distance: distance,
+            override_height: height || null,
+        }),
     });
     if (!response.ok) {
         const text = await response.text().catch(() => '');

public/calibration/js/app.js

@@ -105,7 +105,7 @@ async function showProjectSelector() {
         });
 
         projectSelector.innerHTML = `
-            <h1 class="project-selector__title">Street View 360 — Calibracao</h1>
+            <h1 class="project-selector__title">Street View 360 — Calibração</h1>
             <p class="project-selector__subtitle">Selecione um projeto para iniciar</p>
             <div class="project-selector__grid">
                 ${projects.map(p => {
@@ -498,8 +498,9 @@ async function handleSave() {
             const original = state.originalTargetOverrides.get(targetId);
             const origB = original?.bearing ?? null;
             const origD = original?.distance ?? null;
+            const origH = original?.height ?? 0;
 
-            if (edited.bearing !== origB || edited.distance !== origD) {
+            if (edited.bearing !== origB || edited.distance !== origD || (edited.height ?? 0) !== origH) {
                 if (edited.bearing === null && edited.distance === null) {
                     // Override cleared
                     promises.push(
@@ -510,7 +511,8 @@ async function handleSave() {
                     promises.push(
                         saveTargetOverride(
                             state.currentPhotoId, targetId,
-                            edited.bearing, edited.distance
+                            edited.bearing, edited.distance,
+                            edited.height ?? 0
                         )
                     );
                 }

public/calibration/js/calibration-panel.js

@@ -7,7 +7,7 @@ import {
     state, onChange, isDirty,
     setMeshRotationY, setCameraHeight,
     setMeshRotationX, setMeshRotationZ, setDistanceScale, setMarkerScale,
-    setTargetOverride, clearTargetOverrideEdit,
+    setTargetOverride, setTargetOverrideHeight, clearTargetOverrideEdit,
     selectTarget, deselectTarget, setSetFromClickMode,
     setTargetHidden, isTargetHidden,
     getCurrentPhotoIndex, resetAllReviewedState,
@@ -372,7 +372,7 @@ function renderSlidersSection(s) {
         </div>
     `;
 
-    return renderCollapsibleSection('sliders', 'Parametros de Calibracao', content);
+    return renderCollapsibleSection('sliders', 'Parametros de Calibração', content);
 }
 
 function renderBatchSection(s) {
@@ -464,15 +464,16 @@ function renderTargetItem(target, s) {
 function renderOverrideEditor(target, s) {
     const edited = s.editedTargetOverrides.get(target.id);
     const original = s.originalTargetOverrides.get(target.id);
-    const effective = edited || original || { bearing: null, distance: null };
+    const effective = edited || original || { bearing: null, distance: null, height: 0 };
 
     const hasEffectiveOverride = effective.bearing !== null;
     const hidden = isTargetHidden(target.id);
     const isManual = target.is_original === false;
 
-    // bearing (degrees), distance = ground distance (meters)
+    // bearing (degrees), distance = ground distance (meters), height = vertical offset (meters)
     const bearingVal = effective.bearing ?? 0;
     const distanceVal = effective.distance ?? 5;
+    const heightVal = effective.height ?? 0;
 
     return `
         <div class="cal-panel__section cal-panel__section--override">
@@ -498,6 +499,16 @@ function renderOverrideEditor(target, s) {
                         min="0.5" max="500" step="0.1"
                         value="${distanceVal.toFixed(1)}" />
                 </div>
+
+                <div class="cal-panel__slider-group">
+                    <label class="cal-panel__label">Altura (m)</label>
+                    <input type="range" id="override-height-slider" class="cal-panel__slider"
+                        min="-5" max="5" step="0.1"
+                        value="${heightVal}" />
+                    <input type="number" id="override-height-input" class="cal-panel__input cal-panel__input--narrow"
+                        min="-10" max="10" step="0.1"
+                        value="${heightVal.toFixed(1)}" />
+                </div>
             ` : `
                 <p class="cal-panel__hint">Sem override definido. Clique no viewer para posicionar.</p>
             `}
@@ -864,23 +875,28 @@ function attachEvents() {
         }
     });
 
-    // Override bearing/distance sliders
+    // Override bearing/distance/height sliders
     const bearingSlider = document.getElementById('override-bearing-slider');
     const bearingInput = document.getElementById('override-bearing-input');
     const distanceSlider = document.getElementById('override-distance-slider');
     const distanceInput = document.getElementById('override-distance-input');
+    const heightSlider = document.getElementById('override-height-slider');
+    const heightInput = document.getElementById('override-height-input');
+
+    /** Helper to read current height value from slider */
+    const getHeightVal = () => parseFloat(heightSlider?.value ?? 0);
 
     if (bearingSlider) {
         bearingSlider.addEventListener('input', (e) => {
             const bearing = parseFloat(e.target.value);
             if (bearingInput) bearingInput.value = bearing.toFixed(1);
             const distVal = parseFloat(distanceSlider?.value ?? 0);
-            setTargetOverride(state.selectedTargetId, bearing, distVal, true);
+            setTargetOverride(state.selectedTargetId, bearing, distVal, getHeightVal(), true);
         });
         bearingSlider.addEventListener('change', (e) => {
             const bearing = parseFloat(e.target.value);
             const distVal = parseFloat(distanceSlider?.value ?? 0);
-            setTargetOverride(state.selectedTargetId, bearing, distVal);
+            setTargetOverride(state.selectedTargetId, bearing, distVal, getHeightVal());
         });
     }
 
@@ -890,7 +906,7 @@ function attachEvents() {
             if (isNaN(bearing)) bearing = 0;
             bearing = Math.max(0, Math.min(360, bearing));
             const distVal = parseFloat(distanceSlider?.value ?? 0);
-            setTargetOverride(state.selectedTargetId, bearing, distVal);
+            setTargetOverride(state.selectedTargetId, bearing, distVal, getHeightVal());
         });
     }
 
@@ -899,12 +915,12 @@ function attachEvents() {
             const distance = parseFloat(e.target.value);
             if (distanceInput) distanceInput.value = distance.toFixed(1);
             const bearingVal = parseFloat(bearingSlider?.value ?? 0);
-            setTargetOverride(state.selectedTargetId, bearingVal, distance, true);
+            setTargetOverride(state.selectedTargetId, bearingVal, distance, getHeightVal(), true);
         });
         distanceSlider.addEventListener('change', (e) => {
             const distance = parseFloat(e.target.value);
             const bearingVal = parseFloat(bearingSlider?.value ?? 0);
-            setTargetOverride(state.selectedTargetId, bearingVal, distance);
+            setTargetOverride(state.selectedTargetId, bearingVal, distance, getHeightVal());
         });
     }
 
@@ -914,7 +930,28 @@ function attachEvents() {
             if (isNaN(distance)) distance = 5;
             distance = Math.max(0.5, Math.min(500, distance));
             const bearingVal = parseFloat(bearingSlider?.value ?? 0);
-            setTargetOverride(state.selectedTargetId, bearingVal, distance);
+            setTargetOverride(state.selectedTargetId, bearingVal, distance, getHeightVal());
+        });
+    }
+
+    if (heightSlider) {
+        heightSlider.addEventListener('input', (e) => {
+            const height = parseFloat(e.target.value);
+            if (heightInput) heightInput.value = height.toFixed(1);
+            setTargetOverrideHeight(state.selectedTargetId, height, true);
+        });
+        heightSlider.addEventListener('change', (e) => {
+            const height = parseFloat(e.target.value);
+            setTargetOverrideHeight(state.selectedTargetId, height);
+        });
+    }
+
+    if (heightInput) {
+        heightInput.addEventListener('change', (e) => {
+            let height = parseFloat(e.target.value);
+            if (isNaN(height)) height = 0;
+            height = Math.max(-10, Math.min(10, height));
+            setTargetOverrideHeight(state.selectedTargetId, height);
         });
     }