code-loader 1.0.185__tar.gz → 1.0.186__tar.gz

{code_loader-1.0.185 → code_loader-1.0.186}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: code-loader
-Version: 1.0.185
+Version: 1.0.186
 Summary: 
 License: MIT
 Author: dorhar

{code_loader-1.0.185 → code_loader-1.0.186}/code_loader/contract/visualizer_classes.py

@@ -32,12 +32,14 @@ class LeapImage:
     Visualizer representing an image for Tensorleap.
 
     Attributes:
-    data (npt.NDArray[np.float32] | npt.NDArray[np.uint8]): The image data.
+    data (npt.NDArray[np.float32] | npt.NDArray[np.uint8]): The image data, shaped [H, W, 3] or [H, W, 1].
+        Expected pixel range is [0, 255]. Float values are cast to int (truncated, not scaled), so a
+        normalized [0, 1] float image renders near-black - scale it to [0, 255] or pass uint8.
     type (LeapDataType): The data type, default is LeapDataType.Image.
     compress: Optional[bool]: Whether to compress the image (.jpg) or not (.png)
 
     Example:
-        image_data = np.random.rand(100, 100, 3).astype(np.float32)
+        image_data = (np.random.rand(100, 100, 3) * 255).astype(np.float32)  # [0, 255]
         leap_image = LeapImage(data=image_data)
     """
     data: Union[npt.NDArray[np.float32], npt.NDArray[np.uint8]]
@@ -60,10 +62,12 @@ class LeapVideo:
 
     Attributes:
     data (npt.NDArray[np.float32] | npt.NDArray[np.uint8]): The video data, shaped [T, H, W, C], where T is the number of frames.
+        Note the range differs from still images: float video is expected in [0, 1] (it is scaled by 255),
+        while uint8 is used as-is in [0, 255]. Float values above 1 saturate to white.
     type (LeapDataType): The data type, default is LeapDataType.Video.
 
     Example:
-        video_data = np.random.rand(10, 100, 100, 3).astype(np.float32)
+        video_data = np.random.rand(10, 100, 100, 3).astype(np.float32)  # [0, 1]
         leap_video = LeapVideo(data=video_data)
     """
     data: Union[npt.NDArray[np.float32], npt.NDArray[np.uint8]]
@@ -84,11 +88,13 @@ class LeapImageWithBBox:
 
     Attributes:
     data (npt.NDArray[np.float32] | npt.NDArray[np.uint8]): The image data, shaped [H, W, 3] or [H, W, 1].
+        Expected pixel range is [0, 255]. Float values are cast to int (truncated, not scaled), so a
+        normalized [0, 1] float image renders near-black - scale it to [0, 255] or pass uint8.
     bounding_boxes (List[BoundingBox]): List of Tensorleap bounding boxes objects in relative size to image size.
     type (LeapDataType): The data type, default is LeapDataType.ImageWithBBox.
 
     Example:
-        image_data = np.random.rand(100, 100, 3).astype(np.float32)
+        image_data = (np.random.rand(100, 100, 3) * 255).astype(np.float32)  # [0, 255]
         bbox = BoundingBox(x=0.5, y=0.5, width=0.2, height=0.2, confidence=0.9, label="object")
         leap_image_with_bbox = LeapImageWithBBox(data=image_data, bounding_boxes=[bbox])
     """
@@ -231,6 +237,8 @@ class LeapImageMask:
     Attributes:
     mask (npt.NDArray[np.uint8]): The mask data, shaped [H, W].
     image (npt.NDArray[np.float32] | npt.NDArray[np.uint8]): The image data, shaped [H, W, 3] or shaped [H, W, 1].
+        Any pixel range is accepted: the image is min-max normalized to [0, 255] for display, so unlike the
+        plain Image visualizer, a normalized [0, 1] float renders fine here.
     labels (List[str]): Labels associated with the mask regions; e.g., class names for segmented objects. The length of `labels` should match the number of unique values in `mask`.
     type (LeapDataType): The data type, default is LeapDataType.ImageMask.
 
@@ -304,12 +312,14 @@ class LeapImageWithHeatmap:
 
     Attributes:
     image (npt.NDArray[np.float32]): The image data, shaped [H, W, C], where C is the number of channels.
+        Expected pixel range is [0, 255] (float is truncated to int, not scaled), so a normalized [0, 1] float
+        base image renders near-black - scale it to [0, 255]. The overlaid heatmaps are normalized separately.
     heatmaps (npt.NDArray[np.float32]): The heatmap data, shaped [N, H, W], where N is the number of heatmaps.
     labels (List[str]): Labels associated with the heatmaps; e.g., feature names or attention regions. The length of `labels` should match the number of heatmaps, N.
     type (LeapDataType): The data type, default is LeapDataType.ImageWithHeatmap.
 
     Example:
-        image_data = np.random.rand(100, 100, 3).astype(np.float32)
+        image_data = (np.random.rand(100, 100, 3) * 255).astype(np.float32)  # [0, 255]
         heatmaps = np.random.rand(3, 100, 100).astype(np.float32)
         labels = ["heatmap1", "heatmap2", "heatmap3"]
         leap_image_with_heatmap = LeapImageWithHeatmap(image=image_data, heatmaps=heatmaps, labels=labels)

{code_loader-1.0.185 → code_loader-1.0.186}/code_loader/inner_leap_binder/leapbinder_decorators.py

@@ -1102,19 +1102,33 @@ def _viz_prefix(viz_name: str, leap_type_name: str) -> str:
     return f"Visualizer '{viz_name}' ({leap_type_name}):"
 
 
+def _warn_nonfinite(arr, viz_name: str, leap_type_name: str, field_name: str = "image data") -> None:
+    """Warn when a float array contains NaN/Inf. Applies to every image-like visualizer, including
+    ImageMask (whose min-max normalization also can't render non-finite values)."""
+    if not isinstance(arr, np.ndarray) or arr.size == 0:
+        return
+    if np.issubdtype(arr.dtype, np.floating) and not np.all(np.isfinite(arr)):
+        store_general_warning(
+            key=("viz_nonfinite", viz_name, leap_type_name, field_name),
+            message=f"{_viz_prefix(viz_name, leap_type_name)} {field_name} contains NaN or Inf values, "
+                    f"which will render incorrectly.",
+            link_to_docs=_VIZ_DOCS,
+        )
+
+
 def _warn_image_value_range(image, viz_name: str, leap_type_name: str, field_name: str = "image data") -> None:
-    """Warn when image pixel values sit in a range that will render near-black or clipped."""
+    """Warn when still-image pixel values sit in a range that renders near-black or clipped.
+
+    Applies to Image / ImageWithBBox / ImageWithHeatmap, which the engine encodes with cv2
+    (saturate_cast float->uint8, no scaling). Float is therefore expected in [0, 255]; a
+    normalized [0, 1] float renders near-black. (Video and ImageMask use different conventions.)
+    """
     if not isinstance(image, np.ndarray) or image.size == 0:
         return
     prefix = _viz_prefix(viz_name, leap_type_name)
 
     if np.issubdtype(image.dtype, np.floating):
-        if not np.all(np.isfinite(image)):
-            store_general_warning(
-                key=("viz_image_nonfinite", viz_name, leap_type_name, field_name),
-                message=f"{prefix} {field_name} contains NaN or Inf values, which will render incorrectly.",
-                link_to_docs=_VIZ_DOCS,
-            )
+        _warn_nonfinite(image, viz_name, leap_type_name, field_name)
         finite = image[np.isfinite(image)]
         if finite.size == 0:
             return
@@ -1147,6 +1161,42 @@ def _warn_image_value_range(image, viz_name: str, leap_type_name: str, field_nam
             )
 
 
+def _warn_video_value_range(video, viz_name: str, leap_type_name: str, field_name: str = "video data") -> None:
+    """Warn when video pixel values won't survive the engine's float->uint8 scaling.
+
+    Unlike still images, the engine scales float video by 255 (videoencoder.py), so float is
+    expected in [0, 1]; values above 1 saturate to white and negatives clip to black. uint8 is
+    used as-is in [0, 255].
+    """
+    if not isinstance(video, np.ndarray) or video.size == 0:
+        return
+    prefix = _viz_prefix(viz_name, leap_type_name)
+
+    if np.issubdtype(video.dtype, np.floating):
+        _warn_nonfinite(video, viz_name, leap_type_name, field_name)
+        finite = video[np.isfinite(video)]
+        if finite.size == 0:
+            return
+        mn, mx = float(finite.min()), float(finite.max())
+        if mn < 0.0 or mx > 1.0:
+            store_general_warning(
+                key=("viz_video_range", viz_name, leap_type_name, field_name),
+                message=(f"{prefix} {field_name} is float with values in [{mn:.3g}, {mx:.3g}], outside the "
+                         f"expected [0,1] range. Tensorleap scales float video by 255, so values > 1 saturate "
+                         f"to white and negatives clip to black. Provide float video in [0,1], or uint8 in [0,255]."),
+                link_to_docs=_VIZ_DOCS,
+            )
+    elif np.issubdtype(video.dtype, np.integer):
+        mn, mx = int(video.min()), int(video.max())
+        if mx <= 1:
+            store_general_warning(
+                key=("viz_video_int_low", viz_name, leap_type_name, field_name),
+                message=(f"{prefix} {field_name} is uint8 but values span only [{mn}, {mx}] - this will appear "
+                         f"near-black. uint8 video is used as-is in [0,255]; scale to [0,255] before casting."),
+                link_to_docs=_VIZ_DOCS,
+            )
+
+
 def _warn_bbox_coords(bounding_boxes, viz_name: str, leap_type_name: str) -> None:
     """Warn when bbox coords are not relative [0,1] (i.e. look like absolute pixels)."""
     for bbox in bounding_boxes:
@@ -1247,9 +1297,14 @@ def _emit_visualizer_warnings(result, viz_name: str, visualizer_type: LeapDataTy
             _warn_image_value_range(result.data, viz_name, leap_type_name)
             _warn_bbox_coords(result.bounding_boxes, viz_name, leap_type_name)
         elif visualizer_type == LeapDataType.Video:
-            _warn_image_value_range(result.data, viz_name, leap_type_name, field_name="video data")
+            # Engine scales float video by 255 (videoencoder.py), so float is expected in [0,1] here,
+            # the opposite of the still-image convention.
+            _warn_video_value_range(result.data, viz_name, leap_type_name)
         elif visualizer_type == LeapDataType.ImageMask:
-            _warn_image_value_range(result.image, viz_name, leap_type_name)
+            # Engine min-max normalizes the mask image (MaskEngineVisualizer._rescale_min_max), so any
+            # finite value range renders fine - no range warning here. NaN/Inf still break normalization,
+            # so keep that check alongside the structural mask checks.
+            _warn_nonfinite(result.image, viz_name, leap_type_name)
             _warn_image_mask(result, viz_name, leap_type_name)
         elif visualizer_type == LeapDataType.ImageWithHeatmap:
             _warn_image_with_heatmap(result, viz_name, leap_type_name)

{code_loader-1.0.185 → code_loader-1.0.186}/code_loader/plot_functions/plot_functions.py

@@ -21,6 +21,25 @@ import math
 
 from code_loader.contract.visualizer_classes import LeapImage, LeapImageWithBBox, LeapGraph, LeapText, \
     LeapHorizontalBar, LeapImageMask, LeapTextMask, LeapImageWithHeatmap, LeapVideo
+from code_loader.utils import rescale_min_max
+
+
+def _to_engine_image(image: np.ndarray) -> np.ndarray:
+    """Match the engine's still-image encoding (cv2 saturate_cast): round + clip to [0,255],
+    no scaling, returned as uint8. Float is expected in [0,255]; a normalized [0,1] float
+    therefore renders near-black, exactly as it would on the platform."""
+    if np.issubdtype(image.dtype, np.floating):
+        return np.clip(np.rint(image), 0, 255).astype(np.uint8)
+    return np.clip(image, 0, 255).astype(np.uint8)
+
+
+def _to_engine_video(video: np.ndarray) -> np.ndarray:
+    """Match the engine's video encoding (videoencoder.py): float is scaled by 255 then clipped,
+    uint8 is used as-is. Float is expected in [0,1]."""
+    if np.issubdtype(video.dtype, np.floating):
+        return (video * 255).clip(0, 255).astype(np.uint8)
+    return np.clip(video, 0, 255).astype(np.uint8)
+
 
 def run_only_on_non_mapping_mode():
     """
@@ -51,7 +70,7 @@ def plot_image_with_b_box(leap_data: LeapImageWithBBox, title: str) -> None:
         visualize(leap_image_with_bbox, title)
     """
 
-    image = leap_data.data
+    image = _to_engine_image(leap_data.data)
     bounding_boxes = leap_data.bounding_boxes
 
     # Create figure and axes
@@ -107,7 +126,7 @@ def plot_image(leap_data: LeapImage, title: str) -> None:
         title = "Image"
         visualize(leap_image, title)
     """
-    image_data = leap_data.data
+    image_data = _to_engine_image(leap_data.data)
 
     # If the image has one channel, convert it to a 3-channel image for display
     if image_data.shape[2] == 1:
@@ -305,7 +324,8 @@ def plot_image_mask(leap_data: LeapImageMask, title: str) -> None:
             visualize(leap_image_mask, title)
         """
 
-    image = leap_data.image
+    # Engine min-max normalizes the mask image to [0,255] (MaskEngineVisualizer._rescale_min_max)
+    image = rescale_min_max(leap_data.image)
     mask = leap_data.mask
     labels = leap_data.labels
 
@@ -390,7 +410,7 @@ def plot_text_mask(leap_data: LeapTextMask, title: str) -> None:
 
 @run_only_on_non_mapping_mode()
 def plot_video(leap_data: LeapVideo, title: str) -> None:
-    video_data = leap_data.data
+    video_data = _to_engine_video(leap_data.data)
     fig, ax = plt.subplots()
     fig.patch.set_facecolor('black')
     ax.set_facecolor('black')
@@ -416,7 +436,7 @@ def plot_image_with_heatmap(leap_data: LeapImageWithHeatmap, title: str) -> None
             title = "Image With Heatmap"
             visualize(leap_image_with_heatmap, title)
         """
-    image = leap_data.image
+    image = _to_engine_image(leap_data.image)
     heatmaps = leap_data.heatmaps
     labels = leap_data.labels
 

{code_loader-1.0.185 → code_loader-1.0.186}/pyproject.toml

@@ -1,7 +1,7 @@
 [tool.poetry]
 name = "code-loader"
 
-version = "1.0.185"
+version = "1.0.186"
 description = ""
 authors = ["dorhar <doron.harnoy@tensorleap.ai>"]
 license = "MIT"