feat(poi): index POIs by level names + warn on enum without level_*_info

unpack_poi_id now resolves a key part via level_one_info/level_two_info enum names
(when set) before the descriptor's definition, so poi[idx, 'level2name'] and
poi['level1name', 'level2name'] work for get/set/contains alongside ids and Enums.
Using an Enum key while the matching level_*_info is still 'Any' (unset) now emits a
warning (the .value is still used). 100 POI tests pass.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Author: Hendrik-code

TPTBox/core/poi_fun/poi_abstract.py

@@ -79,16 +79,51 @@ def __init__(
         self.subregion_name2idx = {value: key for key, value in subregion.items()}
 
 
-def unpack_poi_id(key: POI_ID, definition: _Abstract_POI_Definition) -> tuple[int, int]:
+def _resolve_poi_part(part, name2idx: dict, level_info=None) -> int:
+    """Resolve one half of a POI key (region or subregion) to its integer id.
+
+    Order: Enum -> ``.value``; numeric string -> int; other string -> ``level_info`` enum
+    name (when ``level_info`` is a concrete enum), then ``name2idx``. When ``level_info`` is
+    the ``Any`` wildcard and an Enum is used, a warning is emitted (the level info is not set).
+    """
+    if isinstance(part, Enum):
+        if level_info is Any:
+            import warnings
+
+            warnings.warn(
+                f"Indexing a POI with the enum {part!r} but the matching level_one_info/level_two_info is not set "
+                f"(it is 'Any'); the integer value {part.value} is used.",
+                stacklevel=4,
+            )
+        return part.value
+    if isinstance(part, str):
+        try:
+            return int(part)
+        except ValueError:
+            pass
+        if level_info is not None and level_info is not Any:
+            try:
+                return level_info._get_id(part, no_raise=False)
+            except Exception:
+                pass
+        return name2idx[part]
+    return part
+
+
+def unpack_poi_id(key: POI_ID, definition: _Abstract_POI_Definition, level_one_info=None, level_two_info=None) -> tuple[int, int]:
     """Convert any supported POI key type to a ``(region, subregion)`` integer pair.
 
     Accepted key forms: plain integer (packed label), ``slice(region, subregion)``,
     2-tuple of ints, 2-tuple of ``Abstract_lvl`` / ``Enum`` members, or mixed tuples.
-    String values are resolved via ``definition``'s name-to-index mappings.
+    String values resolve via ``level_one_info``/``level_two_info`` enum names (when given)
+    and otherwise via ``definition``'s name-to-index mappings, so ``poi[idx, "level2name"]``
+    and ``poi["level1name", "level2name"]`` work in addition to ids and Enums.
 
     Args:
         key: POI identifier in any of the supported formats.
         definition: Name-to-integer mapping used to resolve string labels.
+        level_one_info: Optional region-level enum class for name/enum resolution + warnings.
+        level_two_info: Optional subregion-level enum class for name/enum resolution + warnings.
 
     Returns:
         ``(region, subregion)`` tuple of plain Python integers.
@@ -101,20 +136,8 @@ def unpack_poi_id(key: POI_ID, definition: _Abstract_POI_Definition) -> tuple[in
         subregion = key.stop
     else:
         region, subregion = key
-    if isinstance(region, str):
-        try:
-            region = int(region)
-        except ValueError:
-            region = definition.region_name2idx[region]
-    if isinstance(region, Enum):
-        region = region.value
-    if isinstance(subregion, str):
-        try:
-            subregion = int(subregion)
-        except ValueError:
-            subregion = definition.subregion_name2idx[subregion]
-    if isinstance(subregion, Enum):
-        subregion = subregion.value
+    region = _resolve_poi_part(region, definition.region_name2idx, level_one_info)
+    subregion = _resolve_poi_part(subregion, definition.subregion_name2idx, level_two_info)
     return region, subregion
 
 
@@ -731,17 +754,20 @@ def __iter__(self):
         """Iterate over all ``(region, subregion)`` key pairs."""
         return iter(self.centroids.keys())
 
+    def _resolve_key(self, key: POI_ID) -> tuple[int, int]:
+        """Resolve any key (ids, Enums, or ``level_one_info``/``level_two_info`` names) to ``(region, subregion)`` ints."""
+        return unpack_poi_id(key, self.centroids.definition, self.level_one_info, self.level_two_info)
+
     def __contains__(self, key: POI_ID) -> bool:
-        key = unpack_poi_id(key, self.centroids.definition)
-        return key in self.centroids
+        return self._resolve_key(key) in self.centroids
 
     def __getitem__(self, key: POI_ID) -> COORDINATE:
-        return tuple(self.centroids[key])
+        return tuple(self.centroids[self._resolve_key(key)])
 
     def __setitem__(self, key: POI_ID, value: tuple[float, float, float] | Sequence[float] | np.ndarray) -> None:
         if len(value) != DIMENSIONS:
             raise ValueError(value)
-        self.centroids[key] = tuple(value)
+        self.centroids[self._resolve_key(key)] = tuple(value)
 
     def __len__(self) -> int:
         return self.centroids.__len__()

unit_tests/test_poi_label_names.py

@@ -107,5 +107,41 @@ def test_metadata_survives_ops(self):
             self._check(q)
 
 
+class TestNameIndexing(unittest.TestCase):
+    def test_index_by_level_names(self):
+        p = _poi()
+        self.assertEqual(p[1, "Vertebra_Corpus"], (1.0, 2.0, 3.0))  # [idx, "level2name"]
+        self.assertEqual(p["C1", "Vertebra_Corpus"], (1.0, 2.0, 3.0))  # ["level1name", "level2name"]
+        self.assertEqual(p["C2", "Vertebra_Corpus"], (4.0, 5.0, 6.0))
+        self.assertIn(("C2", "Vertebra_Corpus"), p)
+        p["C1", "Vertebra_Disc"] = (7.0, 8.0, 9.0)
+        self.assertEqual(p[1, 100], (7.0, 8.0, 9.0))  # Vertebra_Disc == 100
+
+    def test_enum_with_level_set_no_warning(self):
+        import warnings
+
+        p = _poi()
+        with warnings.catch_warnings():
+            warnings.simplefilter("error")
+            self.assertEqual(p[Vertebra_Instance.C1, Location.Vertebra_Corpus], (1.0, 2.0, 3.0))
+
+    def test_enum_without_level_warns(self):
+        import warnings
+
+        from TPTBox.core.vert_constants import Any
+
+        q = POI(
+            centroids={1: {50: (1.0, 2.0, 3.0)}},
+            orientation=("R", "A", "S"),
+            zoom=(1.0, 1.0, 1.0),
+            shape=(10.0, 10.0, 10.0),
+        )
+        self.assertIs(q.level_one_info, Any)
+        with warnings.catch_warnings(record=True) as w:
+            warnings.simplefilter("always")
+            _ = q[Vertebra_Instance.C1, Location.Vertebra_Corpus]
+        self.assertTrue(any("not set" in str(x.message) for x in w))
+
+
 if __name__ == "__main__":
     unittest.main()