scale observation update to v4.1 research, scene mask annotation, docs cleanup

Author: OlafenwaMoses

docs/annotation/object_mask_annotation_3d.md

@@ -628,10 +628,12 @@ Recommended use:
   and higher closed-set COCO segmentation accuracy is preferred.
 - Use `yoloe-26l-seg-pf.pt` when broad prompt-free annotation is more important
   than COCO-only precision.
-- Treat `yoloe-26l-seg-pf.pt` as an annotation model for now. It is not yet a
-  strong fit for ScaleObservation, because most of its 4,585 labels do not yet
-  have calibrated metric object-size priors. ScaleObservation-specific guidance
-  will be documented separately.
+- For ScaleObservation, `yoloe-26l-seg-pf.pt` can provide additional useful
+  labels such as desks, cabinets, monitors, doors, and appliances. Most of its
+  4,585 labels still do not have calibrated metric priors, so unsupported labels
+  are ignored by the scale estimator. See
+  [Scale Observation](../observation/scale_observation.md#supported-scale-priors)
+  for the current prior list.
 
 The supported prompt-free labels are listed and grouped here:
 

docs/annotation/scene_mask_annotation_3d.md

@@ -210,6 +210,13 @@ Each task lives in its own module under `vizion3d/<category>/` and exposes exact
 | Task | Status | Docs |
 |---|---|---|
 | Object mask annotation 3D | Stable | [Object Mask Annotation 3D](annotation/object_mask_annotation_3d.md) |
+| Scene mask annotation 3D | Stable | [Scene Mask Annotation 3D](annotation/scene_mask_annotation_3d.md) |
+
+### Observation
+
+| Task | Status | Docs |
+|---|---|---|
+| Scale Observation | Stable | [Scale Observation](observation/scale_observation.md) |
 
 ---
 

docs/assets/images/scene_roomhd_mask.png

@@ -1,7 +1,7 @@
 # Scale Observation
 
 **Category:** Observation  
-**Experimental:** Yes
+**Experimental:** No
 
 `ScaleObservation` estimates a single metric scale factor for a generated point
 cloud. It is intended for monocular-depth point clouds whose shape is plausible
@@ -12,9 +12,10 @@ The task consumes a point cloud plus object annotations from
 evidence, and can return the estimated scale, candidate diagnostics, a scaled
 point cloud, and a reprojected scaled depth image.
 
-> **Experimental status:** Scale Observation is still being improved. Accuracy,
-> candidate selection, and reporting are expected to get better as evaluation
-> expands, with the goal of reaching a stable non-experimental state soon.
+> **Accuracy note:** Scale Observation is a rough metric-scale estimator, not a
+> measurement system. It can put a relative monocular-depth cloud into a more
+> plausible physical size range, but confidence and candidate diagnostics should
+> stay visible in downstream applications.
 
 ---
 
@@ -160,8 +161,11 @@ object is reliable enough to produce metric scale candidates.
 
 ## Inference Features
 
-The runtime estimator evaluates the same evidence used by the promoted V4
-research path:
+The runtime estimator follows the promoted V4.1 research path:
+`v4_1_yoloe_strong_dimension_class_trimmed_huber`. V4.1 preserves the promoted
+V4 results while removing the dormant scene-extent cap, so the final scale flows
+from object evidence, trimmed Huber aggregation, and prior blending without an
+upper scene-size guard.
 
 | Feature | Purpose |
 |---|---|
@@ -175,26 +179,34 @@ research path:
 | Dimension reliability | Gives each class/dimension a learned trust weight. |
 | Learned calibration | Applies per-class/per-dimension scale correction factors. |
 | Scene plausibility | Downweights candidates that imply implausible scene dimensions. |
-| Scene extent guard | Optionally limits the final scale if configured. |
+| Final prior blend | Blends object evidence with a weak global prior when confidence is low. |
 
 ---
 
 ## Supported Scale Priors
 
-The default annotation checkpoint can detect 80 COCO classes, but only a subset
-has useful metric-size priors for scale estimation. Objects outside this table
-can still appear in annotation results, but they are marked as missing a scale
-prior and do not produce scale candidates.
+Scale candidates are created only for labels with metric-size priors. The table
+contains the COCO-aligned labels used by the default object annotation model and
+the expanded prompt-free YOLOE labels that V4.1 can consume when
+`ObjectMaskAnnotation3D` is run with the YOLOE prompt-free checkpoint. Objects
+outside these priors can still appear in annotation results, but they are marked
+as missing a scale prior and do not produce scale candidates.
 
 | Group | Classes with scale priors |
 |---|---|
 | People | `person` |
-| Furniture | `chair`, `couch`, `bed`, `dining table`, `toilet` |
-| Electronics | `tv`, `laptop`, `keyboard`, `mouse` |
-| Indoor objects | `book`, `vase`, `potted plant` |
-| Appliances and fixtures | `refrigerator`, `microwave`, `oven`, `sink` |
+| Core COCO furniture | `chair`, `couch`, `bed`, `dining table`, `toilet` |
+| Expanded furniture and fixtures | `armchair`, `office chair`, `stool`, `bench`, `desk`, `office desk`, `computer desk`, `side table`, `coffee table`, `cabinet`, `file cabinet`, `kitchen cabinet`, `bookshelf`, `bookcase`, `shelf`, `dresser`, `nightstand`, `door`, `window`, `mirror` |
+| Electronics | `tv`, `laptop`, `keyboard`, `mouse`, `monitor`, `computer monitor`, `computer`, `desktop computer`, `printer`, `phone`, `smartphone`, `tablet`, `remote` |
+| Appliances and fixtures | `refrigerator`, `microwave`, `oven`, `sink`, `toaster`, `blender`, `coffee machine`, `dish washer`, `washing machine`, `faucet`, `shower`, `bathtub` |
+| Indoor objects | `book`, `vase`, `potted plant`, `lamp`, `table lamp`, `trash bin`, `waste container`, `backpack`, `suitcase`, `luggage`, `pillow`, `mattress`, `basket`, `bucket`, `box`, `plant`, `houseplant` |
 | Tableware | `bottle`, `cup`, `bowl` |
 
+Common aliases are normalised before lookup. Examples include `sofa` → `couch`,
+`fridge` → `refrigerator`, `table` → `dining table`, `screen` → `monitor`,
+`swivel chair` → `office chair`, `washer` → `washing machine`, and `mug` →
+`cup`.
+
 ---
 
 ## Command Parameters
@@ -209,7 +221,7 @@ prior and do not produce scale candidates.
 | `return_scaled_point_cloud` | `bool` | No | `False` | If `True`, returns a point cloud whose coordinates are multiplied by `scale_factor`. |
 | `return_scaled_depth` | `bool` | No | `False` | If `True`, projects the scaled cloud back into a camera-space depth image. Requires advanced camera fields. |
 | `return_report` | `bool` | No | `True` | If `True`, includes bounds, accepted candidates, and rejected candidates in `scale_report`. |
-| `config` | `ScaleObservationConfig` | No | promoted V4 defaults | Algorithm-level scale-estimation settings. |
+| `config` | `ScaleObservationConfig` | No | promoted V4.1 defaults | Algorithm-level scale-estimation settings. |
 | `advanced_config` | `ScaleObservationAdvancedConfig` | No | empty | Camera/image settings. See [Advanced config](#advanced-config). |
 
 ---
@@ -467,7 +479,7 @@ Common rejection reasons:
 | `weak_multi_axis_agreement` | Candidate dimensions disagree too much. |
 | `object_dimensions_disagree` | Candidate dimensions are incompatible. |
 | `below_variant_weight_threshold` | Candidate weight was too low. |
-| `not_selected_by_variant` | Candidate did not pass final V4 selection. |
+| `not_selected_by_variant` | Candidate did not pass final V4.1 selection. |
 
 ---
 

docs/assets/images/scene_roomhd_overlay.png

@@ -15,6 +15,7 @@ has a direct Python facade and, where available, REST and gRPC adapters.
 | Task | Python import | REST |
 |---|---|---|
 | [Object Mask Annotation 3D](../annotation/object_mask_annotation_3d.md) | `vizion3d.annotation.ObjectMaskAnnotation3D` | `/annotation/object-mask-annotation-3d` |
+| [Scene Mask Annotation 3D](../annotation/scene_mask_annotation_3d.md) | `vizion3d.annotation.SceneMaskAnnotation3D` | `/annotation/scene-mask-annotation-3d` |
 
 ## Observation
 

docs/assets/pointclouds/scene_annotated_roomhd_result.ply

@@ -36,6 +36,7 @@ nav:
           - Depth Estimation vs Stereo Depth: features/depth_estimation_vs_stereo_depth.md
       - Annotation:
           - Object Mask Annotation 3D: annotation/object_mask_annotation_3d.md
+          - Scene Mask Annotation 3D: annotation/scene_mask_annotation_3d.md
           - YOLOE-26L Prompt-Free Classes: annotation/yoloe_26l_prompt_free_classes.md
       - Observation:
           - Scale Observation: observation/scale_observation.md

docs/index.md

@@ -228,6 +228,45 @@ def local_annotation_model_path(tmp_path_factory) -> str:
     return str(dest)
 
 
+@pytest.fixture(scope="session")
+def local_scene_model_path(tmp_path_factory) -> str:
+    """Provide a local .bin path for the SegFormer-B4 scene model.
+
+    Resolution order: the vizion3d cache, then the vendored research copy at
+    ``research/2D_SEGMENTATION/segformer_b4_ade20k.bin``, then a fresh download
+    from the release URL.  Skips the test if none is available.
+    """
+    from vizion3d.annotation.scene_defaults import (
+        DEFAULT_SCENE_MODEL_FILENAME,
+        DEFAULT_SCENE_MODEL_URL,
+    )
+    from vizion3d.lifting.defaults import default_model_cache_dir, download_model
+
+    default_cache = default_model_cache_dir() / DEFAULT_SCENE_MODEL_FILENAME
+    research_copy = (
+        Path(__file__).parent.parent.parent
+        / "research"
+        / "2D_SEGMENTATION"
+        / DEFAULT_SCENE_MODEL_FILENAME
+    )
+    tmp_dir = tmp_path_factory.mktemp("local_scene_model")
+    dest = tmp_dir / DEFAULT_SCENE_MODEL_FILENAME
+
+    if default_cache.exists():
+        dest.symlink_to(default_cache.resolve())
+    elif research_copy.exists():
+        dest.symlink_to(research_copy.resolve())
+    else:
+        try:
+            download_model(DEFAULT_SCENE_MODEL_URL, cache_dir=tmp_dir)
+        except Exception as exc:  # pragma: no cover - network/release dependent
+            pytest.skip(f"SegFormer scene model unavailable: {exc}")
+
+    if not (dest.exists() or dest.is_symlink()):
+        pytest.skip(f"Scene model not found at {dest}")
+    return str(dest)
+
+
 # ──────────────────────────────────────────────────────────────────────────────
 # gRPC server + client stub fixture
 # ──────────────────────────────────────────────────────────────────────────────