pixelflow 0.6.0__tar.gz → 0.7.0__tar.gz

{pixelflow-0.6.0 → pixelflow-0.7.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pixelflow
-Version: 0.6.0
+Version: 0.7.0
 Summary: Computer vision processing library for visualizing and analyzing detection results from ML models
 Author-email: Emrah Nazif <emrah@datamarkin.com>
 License: MIT
@@ -156,7 +156,7 @@ result = pf.from_ultralytics_classification(model.predict("dog.jpg"))
 
 result.top1.class_name              # 'golden retriever'
 result.top_k(5)                     # -> Classifications, best first
-result.to_json()
+result.to_json()                    # pf.Classifications.from_json() reads it back
 
 # Plain scores - CLIP zero-shot, a vendored ResNet, anything with a score vector
 prompts = ["a photo of a cat", "a photo of a dog"]
@@ -445,6 +445,10 @@ df = pd.DataFrame(data)
 
 # With metrics
 report = detections.to_json_with_metrics()
+
+# And back - masks decoded, keypoints rebuilt, every field restored
+detections = pf.Detections.from_json(json_str)
+detections = pf.Detections.from_dict(data)
 ```
 
 ## Supported Frameworks

{pixelflow-0.6.0 → pixelflow-0.7.0}/README.md

@@ -119,7 +119,7 @@ result = pf.from_ultralytics_classification(model.predict("dog.jpg"))
 
 result.top1.class_name              # 'golden retriever'
 result.top_k(5)                     # -> Classifications, best first
-result.to_json()
+result.to_json()                    # pf.Classifications.from_json() reads it back
 
 # Plain scores - CLIP zero-shot, a vendored ResNet, anything with a score vector
 prompts = ["a photo of a cat", "a photo of a dog"]
@@ -408,6 +408,10 @@ df = pd.DataFrame(data)
 
 # With metrics
 report = detections.to_json_with_metrics()
+
+# And back - masks decoded, keypoints rebuilt, every field restored
+detections = pf.Detections.from_json(json_str)
+detections = pf.Detections.from_dict(data)
 ```
 
 ## Supported Frameworks

{pixelflow-0.6.0 → pixelflow-0.7.0}/pixelflow/__init__.py

@@ -1,4 +1,4 @@
-__version__ = "0.6.0"
+__version__ = "0.7.0"
 __author__ = "Emrah NAZIF"
 
 # Import core modules

{pixelflow-0.6.0 → pixelflow-0.7.0}/pixelflow/classifications/classifications.py

@@ -11,6 +11,7 @@ localisation that never happened.
 import copy as copy_module
 import json
 
+from pixelflow.serialization import constructor_fields, own
 from pixelflow.validators import round_to_decimal
 from typing import Any, Dict, Iterator, List, Optional, Union
 
@@ -94,6 +95,10 @@ class Classification:
             >>> import pixelflow as pf
             >>> pf.Classification(207, "golden retriever", 0.94).to_dict()
             {'class_id': 207, 'class_name': 'golden retriever', 'confidence': 0.94, 'metadata': None}
+
+        Notes:
+            - `metadata` is the classification's own dictionary, not a copy. Treat
+              the result as read-only, or rebuild with `from_dict()`, which copies it
         """
         return {
             "class_id": self.class_id,
@@ -102,6 +107,29 @@ class Classification:
             "metadata": self.metadata,
         }
 
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> "Classification":
+        """
+        Rebuild a Classification from the dictionary `to_dict()` produces.
+
+        Args:
+            data (Dict[str, Any]): A classification dictionary. Unknown keys are
+                ignored and missing keys take the constructor's defaults, so
+                dictionaries written by other pixelflow versions still read.
+
+        Returns:
+            Classification: A new classification with its own metadata.
+
+        Example:
+            >>> import pixelflow as pf
+            >>> row = pf.Classification(class_id=207, class_name="golden retriever", confidence=0.94)
+            >>> pf.Classification.from_dict(row.to_dict()).to_dict() == row.to_dict()
+            True
+            >>> pf.Classification.from_dict({"class_name": "cat"}).confidence is None
+            True
+        """
+        return cls(**own(constructor_fields(cls, data)))
+
     def __repr__(self) -> str:
         return (f"Classification(class_id={self.class_id!r}, "
                 f"class_name={self.class_name!r}, confidence={self.confidence!r})")
@@ -310,5 +338,53 @@ class Classifications:
         """
         return json.dumps(self.to_dict(), indent=4)
 
+    @classmethod
+    def from_dict(cls, items: List[Dict[str, Any]]) -> "Classifications":
+        """
+        Rebuild a Classifications collection from the list `to_dict()` produces.
+
+        Args:
+            items (List[Dict[str, Any]]): Classification dictionaries, each read
+                with `Classification.from_dict`.
+
+        Returns:
+            Classifications: A new collection holding the rows in the order given.
+
+        Example:
+            >>> import pixelflow as pf
+            >>> result = pf.from_scores([0.1, 0.9], labels=["cat", "dog"])
+            >>> restored = pf.Classifications.from_dict(result.to_dict())
+            >>> restored.top1.class_name
+            'dog'
+
+        Notes:
+            - `to_dict()` writes the rows only. The collection's own `inference_id`
+              and `metadata` are not part of it, so they come back as None; set
+              them on the result if you stored them yourself.
+        """
+        return cls([Classification.from_dict(item) for item in items])
+
+    @classmethod
+    def from_json(cls, text: Union[str, bytes]) -> "Classifications":
+        """
+        Rebuild a Classifications collection from the JSON string `to_json()` produces.
+
+        Args:
+            text (Union[str, bytes]): JSON array of classification dictionaries.
+
+        Returns:
+            Classifications: A new collection holding the rows in the order given.
+
+        Raises:
+            json.JSONDecodeError: If `text` is not valid JSON.
+
+        Example:
+            >>> import pixelflow as pf
+            >>> result = pf.from_scores([0.1, 0.9], labels=["cat", "dog"])
+            >>> pf.Classifications.from_json(result.to_json()).top1.class_name
+            'dog'
+        """
+        return cls.from_dict(json.loads(text))
+
     def __repr__(self) -> str:
         return f"Classifications({len(self.classifications)} rows)"

{pixelflow-0.6.0 → pixelflow-0.7.0}/pixelflow/detections/detections.py

@@ -19,6 +19,7 @@ from pixelflow.validators import (validate_bbox,
                                   round_coord,
                                   round_to_decimal)
 from pixelflow.masks import mask_to_polygon, simplify_polygon
+from pixelflow.serialization import constructor_fields, own
 from typing import (List,
                     Iterator, Optional, Union, Any, Dict)
 
@@ -155,6 +156,32 @@ class KeyPoint:
             "confidence": float(self.confidence) if self.confidence is not None else None,
         }
 
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> "KeyPoint":
+        """
+        Rebuild a KeyPoint from the dictionary `to_dict()` produces.
+
+        Args:
+            data (Dict[str, Any]): A keypoint dictionary. `x`, `y` and `id` are
+                                  required; `name` and `confidence` default to None.
+                                  Unknown keys are ignored.
+
+        Returns:
+            KeyPoint: A new keypoint with the dictionary's values.
+
+        Raises:
+            TypeError: If `x`, `y` or `id` is missing.
+            ValueError: If a coordinate is not a finite number.
+
+        Example:
+            >>> import pixelflow as pf
+            >>> keypoint = pf.KeyPoint(100, 200, 0, "nose", 0.9)
+            >>> restored = pf.KeyPoint.from_dict(keypoint.to_dict())
+            >>> restored.to_dict() == keypoint.to_dict()
+            True
+        """
+        return cls(**own(constructor_fields(cls, data)))
+
 
 class Detection:
     """
@@ -363,6 +390,9 @@ class Detection:
             - All NumPy numeric types (int32, float32, etc.) converted to native Python types
             - All optional fields are included even if None for consistent API responses
             - Output is fully JSON-serializable (can use json.dumps() directly)
+            - Lists and dictionaries such as `metadata`, `zones` and `segments` are
+              the detection's own objects, not copies. Treat the result as read-only,
+              or rebuild with `from_dict()`, which copies them
         """
         # Helper function to convert numpy types to native Python types
         def to_python_type(value):
@@ -495,6 +525,78 @@ class Detection:
         else:
             raise ValueError(f"Unknown mask format: {mask_dict['format']}")
 
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> "Detection":
+        """
+        Rebuild a Detection from the dictionary `to_dict()` produces.
+
+        The inverse of `to_dict()`: masks are decoded back into arrays, keypoints
+        become `KeyPoint` objects again, and every other field is handed to the
+        constructor. Reads stored or transmitted results without the caller having
+        to know which fields a detection has or how its masks were encoded.
+
+        Args:
+            data (Dict[str, Any]): A detection dictionary, as written by `to_dict()`
+                                  or parsed from `to_json()`. Unknown keys are
+                                  ignored and missing keys take the constructor's
+                                  defaults, so dictionaries written by other
+                                  pixelflow versions still read.
+
+        Returns:
+            Detection: A new detection, independent of `data`.
+
+        Raises:
+            ValueError: If a mask uses a format `decode_mask` does not know, or a
+                        keypoint coordinate is not a finite number.
+            TypeError: If a keypoint is missing `x`, `y` or `id`.
+
+        Example:
+            >>> import numpy as np
+            >>> import pixelflow as pf
+            >>>
+            >>> mask = np.zeros((480, 640), dtype=bool)
+            >>> mask[100:200, 50:300] = True
+            >>> detection = pf.Detection(bbox=[50, 100, 300, 200], masks=[mask],
+            ...                          class_name="car", confidence=0.9)
+            >>>
+            >>> # Round trip through a plain dictionary
+            >>> restored = pf.Detection.from_dict(detection.to_dict())
+            >>> np.array_equal(restored.masks[0], mask)
+            True
+            >>>
+            >>> # Partial dictionaries read too; the rest take defaults
+            >>> pf.Detection.from_dict({"bbox": [10, 20, 30, 40]}).class_name is None
+            True
+            >>>
+            >>> # Keys this version does not know are ignored
+            >>> pf.Detection.from_dict({"bbox": [10, 20, 30, 40], "added_later": 1}).bbox
+            [10.0, 20.0, 30.0, 40.0]
+
+        Notes:
+            - Values pass through the same validation as any new detection: an
+              invalid `bbox` becomes None, coordinates round to two decimals and
+              confidence to three. Values that came out of `to_dict()` were already
+              rounded, so they come back unchanged
+            - Raster masks come back with the pixels, dtype and shape they were
+              written with
+            - A mask entry that is not an encoded dictionary is taken as already
+              decoded: a polygon list is copied, an array is kept as it is
+            - Lists and dictionaries are copied, so changing the restored
+              detection never reaches `data`, or the detection `data` came from
+        """
+        fields = constructor_fields(cls, data)
+        # Each keypoint is rebuilt from its own dictionary below, and copies it there.
+        keypoints = fields.pop("keypoints", None)
+        fields = own(fields)
+
+        if fields.get("masks") is not None:
+            fields["masks"] = [cls.decode_mask(mask) if isinstance(mask, dict) else mask
+                               for mask in fields["masks"]]
+        if keypoints is not None:
+            fields["keypoints"] = [KeyPoint.from_dict(kp) for kp in keypoints]
+
+        return cls(**fields)
+
     def simplify_masks(self, tolerance: float = 2.0, preserve_topology: bool = True) -> None:
         """
         Simplify polygon masks to reduce complexity while preserving essential shape characteristics.
@@ -1043,6 +1145,94 @@ class Detections:
         """
         return [detection.to_dict() for detection in self.detections]
 
+    @classmethod
+    def from_dict(cls, items: List[Dict[str, Any]]) -> "Detections":
+        """
+        Rebuild a Detections collection from the list `to_dict()` produces.
+
+        The inverse of `to_dict()`. Reads results that were stored or sent as plain
+        data back into a collection that filters, annotates and converts like one
+        that came straight from a model.
+
+        Args:
+            items (List[Dict[str, Any]]): Detection dictionaries, as written by
+                                         `to_dict()`. Each is read with
+                                         `Detection.from_dict`.
+
+        Returns:
+            Detections: A new collection holding the detections in the order given.
+
+        Raises:
+            ValueError: If a mask uses an unknown format, or a keypoint coordinate
+                        is not a finite number.
+            TypeError: If a keypoint is missing `x`, `y` or `id`.
+
+        Example:
+            >>> import pixelflow as pf
+            >>>
+            >>> detections = pf.from_arrays(boxes, scores, masks=masks)
+            >>>
+            >>> # Store as plain data, read back later
+            >>> stored = detections.to_dict()
+            >>> restored = pf.Detections.from_dict(stored)
+            >>> len(restored) == len(detections)
+            True
+            >>>
+            >>> # A restored result behaves like any other
+            >>> confident = restored.filter_by_confidence(0.5)
+            >>> restored.masks_to_segments()
+            >>>
+            >>> # Hand-written rows work too
+            >>> pf.Detections.from_dict([{"bbox": [10, 20, 30, 40], "class_name": "car"}])
+
+        Notes:
+            - Everything `to_dict()` writes comes back: boxes, masks, segments,
+              keypoints, classes, text, tracking, zones and timing
+            - Detections are added through `add_detection`, so a dictionary without
+              a valid `bbox`, or with a NaN confidence, is dropped as it would be
+              from any converter. Nothing `to_dict()` wrote is affected: a
+              collection never holds such a detection
+            - Raster masks are decoded eagerly, one array per mask
+        """
+        detections = cls()
+        for item in items:
+            detections.add_detection(Detection.from_dict(item))
+        return detections
+
+    @classmethod
+    def from_json(cls, text: Union[str, bytes]) -> "Detections":
+        """
+        Rebuild a Detections collection from the JSON string `to_json()` produces.
+
+        Args:
+            text (Union[str, bytes]): JSON array of detection dictionaries.
+
+        Returns:
+            Detections: A new collection holding the detections in the order given.
+
+        Raises:
+            json.JSONDecodeError: If `text` is not valid JSON.
+            ValueError: If a mask uses an unknown format, or a keypoint coordinate
+                        is not a finite number.
+
+        Example:
+            >>> import pixelflow as pf
+            >>>
+            >>> # Write results to disk, read them back in another process
+            >>> with open("results.json", "w") as f:
+            ...     f.write(detections.to_json())
+            >>> with open("results.json") as f:
+            ...     restored = pf.Detections.from_json(f.read())
+            >>>
+            >>> # Or straight from an HTTP response body
+            >>> restored = pf.Detections.from_json(response.content)
+
+        Notes:
+            - Parses the JSON and hands the result to `from_dict`; see it for what
+              is restored and what is dropped
+        """
+        return cls.from_dict(json.loads(text))
+
     def to_json_with_metrics(self) -> str:
         """
         Convert detections to JSON with additional analytics metrics for comprehensive reporting.

pixelflow-0.7.0/pixelflow/serialization.py

@@ -0,0 +1,72 @@
+"""Reading a result type back from the plain dictionary its ``to_dict()`` wrote.
+
+Every result type pixelflow serializes - KeyPoint, Detection, Classification - is
+restored by the same two rules: take the keys its constructor accepts and leave the
+rest, and share no list or dictionary with the data it was read from. Both rules live
+here so the three ``from_dict`` methods cannot come to disagree about them.
+"""
+
+import functools
+import inspect
+from typing import Any, Dict, Tuple
+
+__all__ = ["constructor_fields", "own"]
+
+_CONTAINERS = (list, dict)
+
+
+@functools.lru_cache(maxsize=None)
+def _constructor_arguments(cls: type) -> Tuple[str, ...]:
+    """The argument names `cls` is built from, read once per class."""
+    return tuple(inspect.signature(cls).parameters)
+
+
+def constructor_fields(cls: type, data: Dict[str, Any]) -> Dict[str, Any]:
+    """
+    Pick out of `data` the entries that `cls`'s constructor accepts.
+
+    The constructor is the single statement of what a result type is made of, so the
+    field list is read from it rather than kept as a second copy: a field added to the
+    class is restored without anyone remembering to list it. Keys the constructor does
+    not know are left behind, which is what lets a dictionary written by a newer
+    pixelflow still read, and keys that are absent are simply not passed, so they take
+    the constructor's defaults.
+
+    Args:
+        cls (type): The class about to be constructed.
+        data (Dict[str, Any]): A dictionary as written by that class's `to_dict()`.
+
+    Returns:
+        Dict[str, Any]: A new dictionary of keyword arguments for `cls`. Its values
+            are still the ones in `data`; pass it through `own` to separate them.
+    """
+    return {key: data[key] for key in _constructor_arguments(cls) if key in data}
+
+
+def own(value: Any) -> Any:
+    """
+    Copy a list or dictionary and every list and dictionary inside it.
+
+    `to_dict()` hands containers such as `metadata` out by reference - it runs once
+    per frame and usually feeds `json.dumps`, where a copy would be wasted - so the
+    copy is made on the way back in, and a restored object never shares state with
+    the one it was written from. Copying whatever is a container, not a named few
+    fields, keeps that true for fields added later.
+
+    Serialized data is lists, dictionaries and scalars, and for that shape this is
+    several times faster than `copy.deepcopy`, which tracks every object it visits
+    in case the structure refers back to itself. Anything that is not a container -
+    a string, a number, an array a caller put in by hand - is shared, not copied.
+    Scalars are tested for in the loop, not by a call that returns them unchanged:
+    they are nearly all of what a result holds.
+
+    Args:
+        value: A list or dictionary of plain data.
+
+    Returns:
+        A new container of the same shape, sharing no list or dictionary with `value`.
+    """
+    if isinstance(value, list):
+        return [own(item) if isinstance(item, _CONTAINERS) else item for item in value]
+    return {key: own(item) if isinstance(item, _CONTAINERS) else item
+            for key, item in value.items()}

{pixelflow-0.6.0 → pixelflow-0.7.0}/pixelflow.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pixelflow
-Version: 0.6.0
+Version: 0.7.0
 Summary: Computer vision processing library for visualizing and analyzing detection results from ML models
 Author-email: Emrah Nazif <emrah@datamarkin.com>
 License: MIT
@@ -156,7 +156,7 @@ result = pf.from_ultralytics_classification(model.predict("dog.jpg"))
 
 result.top1.class_name              # 'golden retriever'
 result.top_k(5)                     # -> Classifications, best first
-result.to_json()
+result.to_json()                    # pf.Classifications.from_json() reads it back
 
 # Plain scores - CLIP zero-shot, a vendored ResNet, anything with a score vector
 prompts = ["a photo of a cat", "a photo of a dog"]
@@ -445,6 +445,10 @@ df = pd.DataFrame(data)
 
 # With metrics
 report = detections.to_json_with_metrics()
+
+# And back - masks decoded, keypoints rebuilt, every field restored
+detections = pf.Detections.from_json(json_str)
+detections = pf.Detections.from_dict(data)
 ```
 
 ## Supported Frameworks

{pixelflow-0.6.0 → pixelflow-0.7.0}/pixelflow.egg-info/SOURCES.txt

@@ -9,6 +9,7 @@ pixelflow/crossings.py
 pixelflow/labels.py
 pixelflow/masks.py
 pixelflow/media.py
+pixelflow/serialization.py
 pixelflow/slicer.py
 pixelflow/smoother.py
 pixelflow/strategies.py