cortex-loom 0.3.0rc1__tar.gz

cortex_loom-0.3.0rc1/PKG-INFO

@@ -0,0 +1,53 @@
+Metadata-Version: 2.4
+Name: cortex-loom
+Version: 0.3.0rc1
+Summary: Package for developing and publishing custom Kelvin Cortex Flows.
+Author: MMT Analytics
+Author-email: support@machinemedicine.com
+Requires-Python: >=3.11, <3.13
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Provides-Extra: full
+Requires-Dist: cloudpickle (==3.1.1)
+Requires-Dist: cortex-types (==0.6.4)
+Requires-Dist: jupyter (>=1.0,<2.0) ; extra == "full"
+Requires-Dist: lightgbm (>=4.1,<5.0) ; extra == "full"
+Requires-Dist: matplotlib (>=3.8,<4.0) ; extra == "full"
+Requires-Dist: pandas (>=2.1,<3.0) ; extra == "full"
+Requires-Dist: requests (==2.32.4)
+Requires-Dist: scikit-learn (>=1.4,<2.0) ; extra == "full"
+Requires-Dist: scipy (>=1.12,<2.0) ; extra == "full"
+Requires-Dist: seaborn (>=0.13,<0.14) ; extra == "full"
+Requires-Dist: xgboost (>=2.0,<3.0) ; extra == "full"
+Description-Content-Type: text/markdown
+
+# README #
+
+This README would normally document whatever steps are necessary to get your application up and running.
+
+### What is this repository for? ###
+
+* Quick summary
+* Version
+* [Learn Markdown](https://bitbucket.org/tutorials/markdowndemo)
+
+### How do I get set up? ###
+
+* Summary of set up
+* Configuration
+* Dependencies
+* Database configuration
+* How to run tests
+* Deployment instructions
+
+### Contribution guidelines ###
+
+* Writing tests
+* Code review
+* Other guidelines
+
+### Who do I talk to? ###
+
+* Repo owner or admin
+* Other community or team contact

cortex_loom-0.3.0rc1/README.md

@@ -0,0 +1,29 @@
+# README #
+
+This README would normally document whatever steps are necessary to get your application up and running.
+
+### What is this repository for? ###
+
+* Quick summary
+* Version
+* [Learn Markdown](https://bitbucket.org/tutorials/markdowndemo)
+
+### How do I get set up? ###
+
+* Summary of set up
+* Configuration
+* Dependencies
+* Database configuration
+* How to run tests
+* Deployment instructions
+
+### Contribution guidelines ###
+
+* Writing tests
+* Code review
+* Other guidelines
+
+### Who do I talk to? ###
+
+* Repo owner or admin
+* Other community or team contact

cortex_loom-0.3.0rc1/cortex_loom/__init__.py

@@ -0,0 +1,10 @@
+r"""
+This package provides Python interfaces and utilities for interacting with
+the Kelvin Cortex platform, particularly for:
+
+- Loading and manipulating custom data objects (see [available types](types/__init__.md))
+- Implementing and publishing custom processing Flows (see [FlowBuilder](flow_builder.md))
+- Local development and testing of Cortex-compatible functions
+"""
+
+from cortex_loom.flow_builder import FlowBuilder

cortex_loom-0.3.0rc1/cortex_loom/flow_builder.py

@@ -0,0 +1,356 @@
+import inspect
+import json
+from importlib.metadata import version
+from io import BytesIO
+from typing import Any, Callable, Dict, Optional, Tuple
+
+import cloudpickle
+import requests
+
+from cortex_loom.types.data_object import DataObject
+from cortex_loom.types.utils import (
+    PROVIDER_REGISTRY,
+    get_type_path,
+    init_defaults,
+)
+
+
+class FlowBuilder:
+    r"""FlowBuilder helps validate custom functions meant for publishing in
+    Cortex and provides an interface for the publishing API."""
+
+    _API_URL = "https://api.cortex.machinemedicine.com"
+    _PUBLISH_ENDPOINT = "argo/publish_flow"
+
+    def __init__(
+        self,
+        api_token: str,
+    ):
+        """
+        Parameters
+        ----------
+        api_token : str
+            API token to validate the Flow publishing requests with.
+
+        Examples
+        --------
+        Basic publishing of a simple function
+
+        >>> def extract_video_metadata(
+        ...     video: VideoObject,
+        ... ) -> float:
+        ...     '''Reads metadata of the video (duration and frame dimensions).'''
+        ...     return video.duration, video.height, video.width
+        ...
+        >>> builder = FlowBuilder(api_token="your-long-api-token-here")
+        >>> response = builder.publish(
+        ...     extract_video_metadata,
+        ...     flow_display_name="Video Metadata Extraction",
+        ...     flow_description="Extracts metadata of the video.",
+        ...     output_display_name="Video Metadata",
+        ... )
+
+        Validate function signature & serialization before publishing
+
+        >>> serialised_func, param_spec = builder.build(extract_video_metadata)
+        >>> print(param_spec)
+        {'video': {
+            'data_type': 'VideoObject',
+            'provider_type': 'cortex_loom.types.video_object.VideoObjectProvider',
+            'provider_parameters': { # Filled with Provider's defaults
+                "stream_index": 0,
+                "pixel_format": "rgb24",
+                "rotation": None,
+                "height": None,
+                "width": None,
+            }
+        }}
+
+        Publishing with custom VideoObjectProvider parameters
+        (force RGB format, resize to 640×360, rotate 90° clockwise)
+
+
+        >>> # Tell the platform to load input videos with specific transformations
+        >>> custom_params = {
+        ...     "video": {                       # name of the function parameter
+        ...         "width": 640,
+        ...         "height": 360,
+        ...         "rotation": 90,              # clockwise
+        ...     }
+        ... }
+        ...
+        >>> response = builder.publish(
+        ...     extract_video_metadata,
+        ...     custom_provider_parameters=custom_params,
+        ...     ...,
+        ... )
+        >>>
+        >>> # Or just validate without publishing
+        >>> serialised, spec = builder.build(
+        ...     extract_upper_half,
+        ...     custom_provider_parameters=custom_params,
+        ... )
+        >>> print(spec["video"]["provider_parameters"])
+        {
+            'stream_index': 0,
+            'pixel_format': 'rgb24',
+            'width': 640,
+            'height': 360,
+            'rotation': 90
+        }
+        """
+        self.api_token = api_token
+
+    def build(
+        self,
+        func: Callable,
+        custom_provider_parameters: Dict[str, Dict[str, Any]] = {},
+    ) -> Tuple[BytesIO, Dict[str, dict]]:
+        """Validates the signature of the function and prepares its input
+        specification. If successful, returns the serialised function
+        and parameter details. Can be used to validate the function before
+        publishing.
+
+        Parameters
+        ----------
+        func : Callable
+            Function to be serialised. Its parameters need to be strictly
+            type-hinted and the output has to be JSON-serialisable.
+
+        custom_provider_parameters : Dict[str, Dict[str, Any]]
+            Mapping of function input names to a dictionary of the input's
+            `DataObjectProvider` parameters. Used to overwrite default parameter
+            values of the Providers.
+
+        Returns
+        -------
+        BytesIO
+            Buffer containing the serialised `func` code.
+        Dict[str, dict]
+            Mapping of function parameter names to their details including
+            type name and Provider parameters.
+        """
+        # Validate the signature of the function, extract its parameters
+        parameter_info = self._validate_func_signature(func=func)
+        # Validate DataProviders' parameters
+        provider_parameters = self._validate_provider_parameters(
+            func_parameter_info=parameter_info,
+            custom_provider_parameters=custom_provider_parameters,
+        )
+        # Format the required function data parameters and their providers
+        required_data = dict()
+        for name, data_type in parameter_info.items():
+            # Save specification of the required parameter
+            required_data[name] = {
+                "data_type": data_type.__qualname__,
+                "provider_type": get_type_path(
+                    PROVIDER_REGISTRY[data_type.__qualname__]
+                ),
+                "provider_parameters": provider_parameters[name],
+            }
+        # Serialise the function into bytes
+        serialised_func = self._serialise(func=func)
+
+        return serialised_func, required_data
+
+    def publish(
+        self,
+        func: Callable,
+        custom_provider_parameters: Dict[str, Dict[str, Any]] = {},
+        flow_display_name: Optional[str] = None,
+        flow_description: Optional[str] = None,
+        output_display_name: Optional[str] = None,
+        output_description: Optional[str] = None,
+    ) -> Dict[str, Any]:
+        """Publishes the given function as a custom Cortex Flow.
+
+        Parameters
+        ----------
+        func : Callable
+            Function to be published. Its parameters need to be strictly
+            type-hinted and the output has to be JSON-serialisable. Once
+            published, it will be available for use in Kelvin Cortex.
+        custom_provider_parameters : Dict[str, Dict[str, Any]]
+            Mapping of function input names to a dictionary of the input's
+            `DataObjectProvider` parameters. Used to overwrite default parameter
+            values of the Providers.
+        flow_display_name : Optional[str]
+            Name of the function to be displayed in Cortex. If None, a name
+            will be generated.
+        flow_description : Optional[str]
+            Optional description of the Flow shown to users in Cortex.
+        output_display_name : Optional[str]
+            Name of the output of the function. If None, a name will be
+            generated.
+        output_description : Optional[str]
+            Optional description of the Flow's output visible to Cortex users.
+
+        Returns
+        -------
+        Dict[str, Any]
+            Response of the publishing API.
+        """
+        # Prepare the function for publishing by building it
+        serialised_func, required_data = self.build(
+            func=func, custom_provider_parameters=custom_provider_parameters
+        )
+
+        # Get the version of the cortex-loom and cortex-types package
+        builder_version = version("cortex_loom")
+        types_version = version("cortex_types")
+
+        # Construct the publishing request
+        headers = {"Authorization": f"Bearer {self.api_token}"}
+        data = {
+            "required_data": required_data,
+            "builder_version": builder_version,
+            "types_version": types_version,
+            "flow_display_name": flow_display_name,
+            "flow_description": flow_description,
+            "output_display_name": output_display_name,
+            "output_description": output_description,
+        }
+        files = {
+            "file": (
+                "serialised_func.pkl",
+                serialised_func,
+                "application/octet-stream",
+            ),
+        }
+        # Send a request to the publishing API
+        response = requests.request(
+            method="POST",
+            url=f"{self._API_URL}/{self._PUBLISH_ENDPOINT}",
+            headers=headers,
+            files=files,
+            data={"info": json.dumps(data)},
+        )
+        # Handle API respnse
+        response.raise_for_status()
+        return response.json()
+
+    @staticmethod
+    def _validate_func_signature(
+        func: Callable,
+    ) -> Dict[str, DataObject]:
+        """Validate the signature of the function ensuring that it only expects
+        parameters of specific types.
+
+        Parameters
+        ----------
+        func : Callable
+            Function which signature is to be verified.
+
+        Returns
+        -------
+        Dict[str, DataObject]
+            Mapping of function parameter names to the expected DataObject type.
+
+        Raises
+        ------
+        ValueError
+            All parameters need to have a type specified.
+        """
+        # Get the signature of the function
+        signature = inspect.signature(func)
+
+        # Check if all parameters have types specified
+        missing_type = [
+            x for x in signature.parameters.values() if x == inspect._empty
+        ]
+        if missing_type:
+            raise ValueError(
+                "All parameters need to have a type specified. "
+                f"Types missing for the following parameters: {missing_type}."
+            )
+
+        # Gather information about the parameters
+        parameter_info, invalid = {}, []
+        for parameter in signature.parameters.values():
+            # Check if the type is one of the provided data objects
+            if issubclass(parameter.annotation, DataObject):
+                parameter_info[parameter.name] = parameter.annotation
+            # If not, raise an error for invalid parameters
+            else:
+                invalid.append((parameter.name, parameter.annotation))
+        # Check if any parameters were found to be invalid
+        if invalid:
+            invalid_str = ", ".join(
+                [f"({n}: {t.__name__})" for n, t in invalid]
+            )
+            raise ValueError(
+                "Some of the requested parameters are not DataObjects. "
+                f"Parameters causing errors: [{invalid_str}]."
+            )
+
+        return parameter_info
+
+    @staticmethod
+    def _validate_provider_parameters(
+        func_parameter_info: Dict[str, DataObject],
+        custom_provider_parameters: Dict[str, Dict[str, Any]],
+    ) -> Dict[str, Dict[str, Any]]:
+        """Validates Provider parameters for function inputs specified in
+        `func_parameter_info`.
+
+        Parameters
+        ----------
+        func_parameter_info : Dict[str, DataObject]
+            Mapping of function parameter names to their type.
+        custom_provider_parameters : Dict[str, Dict[str, Any]]
+            User-specified Provider parameters, will overwrite any defaults.
+
+        Returns
+        -------
+        Dict[str, Dict[str, Any]]
+            Mapping of function parameter names to dictionaries of corresponding
+            Provider parameters.
+
+        Raises
+        ------
+        RuntimeError
+            Invalid Provider parameters detected.
+        """
+
+        # Track all validated Provider parameters
+        provider_parameters = dict()
+        # Validate for every function input parameter
+        for name, data_type in func_parameter_info.items():
+            # Get the corresponding Provider
+            provider_type = PROVIDER_REGISTRY[data_type.__qualname__]
+            # Get the Provider's __init__ defaults
+            defaults = init_defaults(provider_type)
+            # Get the user-provided custom parameter values
+            parameters = defaults | custom_provider_parameters.get(name, {})
+            # Verify that the Provider can be initialised
+            try:
+                provider_type(**parameters)
+            except Exception as error:
+                raise RuntimeError(
+                    f"Provider parameters for `{name}` are invalid."
+                    f"(Input: {name}, Type: {data_type.__qualname__}, "
+                    f"Provider: {provider_type.__qualname__})"
+                ) from error
+            # Save the Provider's parameters
+            provider_parameters[name] = parameters
+
+        return provider_parameters
+
+    @staticmethod
+    def _serialise(func: Callable) -> BytesIO:
+        """Serialise the function using the `cloudpickle` module.
+
+        Parameters
+        ----------
+        func : Callable
+            Function to be serialised.
+
+        Returns
+        -------
+        BytesIO
+            Buffer containing the serialised function.
+        """
+        buffer = BytesIO()
+        cloudpickle.dump(obj=func, file=buffer)
+        buffer.seek(0)
+        return buffer

cortex_loom-0.3.0rc1/cortex_loom/types/__init__.py

@@ -0,0 +1,41 @@
+r"""Cortex-native data types which include:
+
+- [`VideoObject`](video_object.md/#cortex_loom.types.video_object.VideoObject)
+- [`PoseObject`](pose_object.md/#cortex_loom.types.pose_object.PoseObject)
+- [`FaceObject`](face_object.md/#cortex_loom.types.face_object.FaceObject)
+
+Specifying them as inputs to a custom Flow allows Cortex to correctly provide
+data to your function. For example, in order to write a function that uses
+a human pose estimated based on an assignemt video one can write:
+
+``` py
+from cortex_loom.types import PoseObject
+
+def my_function(pose: PoseObject):
+    ...
+```
+
+---
+
+DataObject Providers, which can be used to construct instances of specific
+DataObjects, are defined alongside the data types. For example:
+
+``` py
+from cortex_loom.types import PoseObjectProvider
+
+# Initialise the Provider
+provider = PoseObjectProvider()
+
+# Use it to construct the DataObject from a local file
+pose = provider.get_data(file_path="./pose.json")
+
+# Interact with the PoseObject
+print(pose.pose_features)
+# ["x", "y", "z"]
+```
+
+"""
+
+from cortex_loom.types.face_object import FaceObject, FaceObjectProvider
+from cortex_loom.types.pose_object import PoseObject, PoseObjectProvider
+from cortex_loom.types.video_object import VideoObject, VideoObjectProvider

cortex_loom-0.3.0rc1/cortex_loom/types/data_object.py

@@ -0,0 +1,116 @@
+from abc import abstractmethod
+from typing import Any, Dict, Optional, Tuple
+
+from cortex_types import DataObject as BaseDataObject
+
+
+class DataObject(BaseDataObject):
+    pass
+
+
+class DataObjectProvider:
+    """Base class for all `DataObject` Poviders. Use Providers specific to data
+    modality (e.g. `VideoObjectProvider`) to interact with data files."""
+
+    def get_data(
+        self,
+        file_path: str,
+        roi: Optional[Tuple[int, int]] = None,
+        **kwargs,
+    ) -> DataObject:
+        r"""Method for reading DataObjects. Provided a local file path
+        it constructs a DataObject.
+
+        Parameters
+        ----------
+        file_path : str
+            Path to a locally saved file based on which a DataObject is to be
+            constructed.
+        roi : Tuple[int, int] | None
+            An optional region of interest (ROI) to which the DataObject ought
+            to be limited. Specified as a tuple of integers (milliseconds).
+            For objects with a temporal dimension (e.g. VideoObject) it limits
+            the output to the specified interval. If None, no trim is applied.
+
+        Returns
+        -------
+        DataObject
+            Initialised DataObject.
+        """
+        # If provided, check if the ROI is valid
+        if roi is not None:
+            self._check_roi(roi=roi)
+        # Read the file data and return the DataObject
+        data = self._read_file(file_path=file_path)
+        data_object = self._get_data(data=data, roi=roi)
+        return data_object
+
+    @staticmethod
+    @abstractmethod
+    def _read_file(file_path: str) -> Any:
+        """Abstract method that needs to be implemented by child classes.
+        It ought to read the specified file into memory."""
+
+    @abstractmethod
+    def _get_data(
+        self,
+        data: Any,
+        roi: Optional[Tuple[int, int]],
+        **metadata: Dict[str, Any],
+    ) -> DataObject:
+        """Abstract method that needs to be implemented by child classes.
+        It ought to construct a DataObject from the read file data."""
+
+    def __call__(
+        self,
+        file_path: str,
+        roi: Optional[Tuple[int, int]] = None,
+        **metadata: Dict[str, Any],
+    ) -> DataObject:
+        """Constructs a DataObject from the specified file. Expects required
+        metadata parameters to be passed along the file path."""
+        return self.get_data(file_path=file_path, roi=roi, **metadata)
+
+    @staticmethod
+    def _check_roi(roi: Tuple[int, int]) -> None:
+        """Validates the format of the ROI.
+
+        Parameters
+        ----------
+        roi : Tuple[int, int]
+            A tuple of two, non-decreasing integers specifying the region of
+            interest.
+
+        Raises
+        ------
+        TypeError
+            ROI is not a tuple nor a list.
+        ValueError
+            ROI is not of length 2.
+        TypeError
+            ROI elements are not integers.
+        ValueError
+            ROI elements are negative or decreasing.
+        """
+        if not isinstance(roi, (list, tuple)):
+            raise TypeError(
+                "`roi` is expected to be (Tuple[int, int]), "
+                f"got ({type(roi).__name__}) instead."
+            )
+        if len(roi) != 2:
+            raise ValueError(
+                "`roi` Tuple is expected to be of length (2), "
+                f"got ({len(roi)}) instead."
+            )
+
+        start, end = roi
+        if not isinstance(start, int) or not isinstance(end, int):
+            raise TypeError(
+                "`roi` elements need to be integers, "
+                f"got ({type(start).__name__}, {type(end).__name__})."
+            )
+        if start > end or start < 0:
+            raise ValueError(
+                "`roi` elements need to be non-negative and non-decreasing, "
+                f"got (start: {start}, end: {end})."
+            )

cortex_loom-0.3.0rc1/cortex_loom/types/face_object.py

@@ -0,0 +1,96 @@
+import json
+from typing import Any, Dict, Optional, Tuple
+
+from typing_extensions import override
+
+from cortex_types import FaceObject as BaseFaceObject
+from cortex_types.face_object import _FaceObjectProvider
+from cortex_types.interfaces import FaceInterface
+
+from cortex_loom.types.data_object import DataObject, DataObjectProvider
+from cortex_loom.types.utils import _register_provider
+
+
+class FaceObject(BaseFaceObject, DataObject, FaceInterface):
+    r"""
+    FaceObject type represents a face mesh estimated based on a source
+    video/image.
+
+    Attributes
+    ----------
+    face_array : np.ndarray
+        Array of shape (T, K, C) containing face keypoints.
+    timestamps : np.ndarray
+        Array of shape (T,) containing timestamps [milliseconds].
+    blendshapes_array : Optional[np.ndarray], default=None
+        Array of shape (T, B) containing blendshapes' scores. Estimation of
+        blendshapes by the FaceLandmarker model is optional.
+    rotation_array : Optional[np.ndarray]
+        Array of shape (T, 3) containing rotation angles (pitch, yaw, roll),
+        if available.
+    face_features : List[str]
+        List containing feature names of the `face_array`; e.g., ["x", "y", "z"].
+    blendshapes_features : Optional[List[str]]
+        List containing feature names of the `blendshapes_array`;
+        e.g., ["NEUTRAL", "BROW_DOWN_LEFT"], if available.
+    rotation_features : Optional[List[str]]
+        List containing feature names of the `rotation_array`;
+        e.g., ["pitch", "yaw", "roll"], if available.
+
+    Notes
+    -----
+    - T: Number of time steps.
+    - K: Number of keypoints.
+    - C: Number of features per keypoint (e.g., x, y, z).
+    """
+
+
+@_register_provider(model_type=FaceObject)
+class FaceObjectProvider(_FaceObjectProvider, DataObjectProvider):
+    """
+    FaceObjectProvider expects a dictionary input representing a FaceObject
+    JSON and constructs a FaceObject instance.
+    """
+
+    FACE_OBJECT_TYPE = FaceObject
+
+    @override
+    def get_data(
+        self,
+        file_path: str,
+        roi: Optional[Tuple[int, int]] = None,
+        **kwargs,
+    ) -> FaceObject:
+        r"""Constructs a FaceObject from a local file.
+
+        Parameters
+        ----------
+        file_path : str
+            Local path to a file representing a FaceObject. Likely downloaded
+            from Kelvin Cortex.
+        roi : Optional[Tuple[int, int]], optional
+            An optional region of interest (ROI) to which the FaceObject ought
+            to be limited, specified as a tuple of integers (milliseconds).
+            The temporal dimension of the FaceObject will be limited to the
+            given time interval. If None, no trim is applied.
+
+        Returns
+        -------
+        FaceObject
+            An object holding an estimated human pose face mesh.
+
+        Examples
+        --------
+        >>> provider = FaceObjectProvider()
+        >>> face = provider.get_data(file_path="./face_object.json", roi=None)
+        >>> face.face_features
+        ["x", "y", "z"]
+        """
+        return super().get_data(file_path=file_path, roi=roi, **kwargs)
+
+    @staticmethod
+    def _read_file(file_path: str) -> Dict[str, Any]:
+        """Reads the serialised FaceObject JSON file into a dictionary."""
+        with open(file=file_path, mode="r") as fp:
+            data = json.load(fp=fp)
+        return data

cortex_loom-0.3.0rc1/cortex_loom/types/pose_object.py

@@ -0,0 +1,165 @@
+import json
+from typing import Any, Dict, Optional, Tuple
+
+from typing_extensions import override
+
+from cortex_types.interfaces import BodyContourInterface, PoseInterface
+from cortex_types.pose_object import PoseObject as BasePoseObject
+from cortex_types.pose_object import _PoseObjectProvider
+
+from cortex_loom.types.data_object import DataObject, DataObjectProvider
+from cortex_loom.types.utils import _register_provider
+
+
+class BodyContour(BodyContourInterface):
+    """A body contour interface holding its points and a threshold value used to
+    find it.
+
+    Attributes
+    ----------
+    points : np.ndarray
+        Array of 2D coordinates of points comprising the contours. Shaped as
+        (N, 2), where N is the number of contour points.
+
+    threshold : float
+        Threshold value used to convert a predicted body segmentation mask into
+        a binary one based on which the contour has been computed.
+    """
+
+
+class PoseObject(BasePoseObject, DataObject, PoseInterface):
+    r"""
+    PoseObject type represents human poses estimated based on a source
+    video/image.
+
+    Attributes
+    ----------
+    bbox_array : np.ndarray
+        Array of shape (T, len(bbox_features)) containing the bounding box for
+        the detected person over T timesteps.
+    pose_array : np.ndarray
+        Array of shape (T, K, len(pose_features)) containing the pose keypoints
+        for K keypoints over T timesteps.
+        Supports convenient string-based indexing using keypoint names from
+        `pose_mapping`:
+
+        - ``pose_array["nose"]`` → shape (T, C)
+        - ``pose_array[["left_wrist", "right_wrist"]]`` → shape (T, 2, C)
+    timestamps : np.ndarray
+        Array of shape (T,) containing a timestamp [milliseconds] for each index
+        of the pose.
+    valid_times: np.ndarray
+        Boolean array of shape (T,) indicating which timestamps correspond to
+        valid poses.
+    pose_mapping : Dict[str, int]
+        Dictionary mapping keypoint names to their indices in the pose array's K
+        dimension, e.g., ``{"left_eye": 0, "right_eye": 1, "nose": 15, ...}``.
+    bbox_features : List[str]
+        List containing the names of the features in the bounding box array,
+        e.g., ``["origin_x", "origin_y", "height", "width"]``.
+    pose_features : List[str]
+        List containing the names of the features in the pose array,
+        e.g., ``["x", "y", "confidence"]`` or ``["x", "y", "z", "visibility"]``.
+    body_contours : Optional[List[List[BodyContour]]]
+        Optional list of length T containing lists of body contour objects.
+        Each contour holds an array of 2D points and a threshold value used to
+        convert the float body segmentation mask into a boolean one.
+    source_width: int
+        Width of the source video/image based on which the pose has been
+        estimated.
+    source_height: int
+        Height of the source video/image based on which the pose has been
+        estimated.
+
+    Notes
+    -----
+    - T: Number of time steps (frames).
+    - K: Number of keypoints.
+    - C: Number of features per keypoint (usually 2-4, e.g. x, y, confidence).
+
+    Examples
+    --------
+    Keypoint name-based indexing (most common usage pattern):
+
+    >>> # Assume pose comes from PoseObjectProvider.get_data(...)
+    >>> pose
+    PoseObject(T: 240, K: 75, C: 4)
+
+    >>> # Single keypoint → returns (T, C) array
+    >>> nose = pose.pose_array["nose"]
+    >>> nose.shape
+    (240, 4)
+    >>> nose[0]          # first frame: [x, y, visibility, confidence]
+    array([512.3, 248.7, 0.95, 0.98])
+
+    >>> # Multiple keypoints → returns (T, N, C) array
+    >>> wrists = pose.pose_array[["left_wrist", "right_wrist"]]
+    >>> wrists.shape
+    (240, 2, 4)
+
+    >>> # Plot trajectory of both wrists over time
+    >>> import matplotlib.pyplot as plt
+    >>> plt.plot(wrists[:, 0, 0], wrists[:, 0, 1], label="left wrist")   # x,y
+    >>> plt.plot(wrists[:, 1, 0], wrists[:, 1, 1], label="right wrist")
+    >>> plt.legend()
+    >>> plt.show()
+
+    >>> # More complex selection
+    >>> core_points = ["nose", "left_shoulder", "right_shoulder",
+    ...                "left_hip", "right_hip"]
+    >>> torso = pose.pose_array[core_points]
+    >>> torso.shape
+    (240, 5, 4)
+    """
+
+
+@_register_provider(model_type=PoseObject)
+class PoseObjectProvider(_PoseObjectProvider, DataObjectProvider):
+    r"""
+    PoseObjectProvider expects a dictionary input representing a PoseObject
+    JSON and constructs a PoseObject instance.
+    """
+
+    POSE_OBJECT_TYPE = PoseObject
+
+    @override
+    def get_data(
+        self,
+        file_path: str,
+        roi: Optional[Tuple[int, int]] = None,
+        **kwargs,
+    ) -> PoseObject:
+        r"""Constructs a PoseObject from a local file.
+
+        Parameters
+        ----------
+        file_path : str
+            Local path to a file representing a PoseObject. Likely downloaded
+            from Kelvin Cortex.
+        roi : Optional[Tuple[int, int]], optional
+            An optional region of interest (ROI) to which the PoseObject ought
+            to be limited, specified as a tuple of integers (milliseconds).
+            The temporal dimension of the PoseObject will be limited to the
+            given time interval. If None, no trim is applied.
+
+        Returns
+        -------
+        PoseObject
+            An object holding an estimated human pose key-points and bounding
+            boxes.
+
+        Examples
+        --------
+        >>> provider = PoseObjectProvider()
+        >>> pose = provider.get_data(file_path="./pose_object.json", roi=None)
+        >>> pose
+        PoseObject(T: 100, K: 75, C: 4)
+        """
+        return super().get_data(file_path=file_path, roi=roi, **kwargs)
+
+    @staticmethod
+    def _read_file(file_path: str) -> Dict[str, Any]:
+        """Reads the serialised PoseObject JSON file into a dictionary."""
+        with open(file=file_path, mode="r") as fp:
+            data = json.load(fp=fp)
+        return data

cortex_loom-0.3.0rc1/cortex_loom/types/utils.py

@@ -0,0 +1,65 @@
+import inspect
+from typing import Any, Callable, Dict, Type, Union
+
+from cortex_loom.types.data_object import DataObject, DataObjectProvider
+
+PROVIDER_REGISTRY: Dict[str, Type[DataObjectProvider]] = dict()
+
+
+def init_defaults(cls_or_init: Union[Type, Callable]) -> Dict[str, Any]:
+    """
+    Extract default values of the parameters from a class __init__ method or
+    an __init__ function.
+
+    Parameters
+    ----------
+    cls_or_init : class or callable
+        The class whose __init__ method or an __init__ function to inspect.
+
+    Returns
+    -------
+    Dict[str, Any]
+        Dictionary mapping parameter names to their default values. Only
+        parameters with default values are included; 'self', *args, and **kwargs
+        are excluded.
+
+    Examples
+    --------
+    >>> class MyClass:
+    ...     def __init__(self, a, b=2, c=3, *args, **kwargs):
+    ...         pass
+    >>> init_defaults(MyClass)
+    {'b': 2, 'c': 3}
+    """
+    # Accept either a class or an __init__ method
+    init = (
+        cls_or_init.__init__ if inspect.isclass(cls_or_init) else cls_or_init
+    )
+
+    defaults: Dict[str, Any] = {}
+    for param in inspect.signature(init).parameters.values():
+        if param.name == "self" or param.kind in (
+            inspect.Parameter.VAR_POSITIONAL,
+            inspect.Parameter.VAR_KEYWORD,
+        ):
+            continue
+
+        if param.default is not inspect.Parameter.empty:
+            defaults[param.name] = param.default
+
+    return defaults
+
+
+def get_type_path(tp: type) -> str:
+    """Return the module path of the object."""
+    return f"{tp.__module__}.{tp.__qualname__}"
+
+
+def _register_provider(model_type: Type[DataObject]):
+    """Decorator used to register a Provider type for a DataObject"""
+
+    def wrapper(provider_cls: Type[DataObjectProvider]):
+        PROVIDER_REGISTRY[model_type.__qualname__] = provider_cls
+        return provider_cls
+
+    return wrapper

cortex_loom-0.3.0rc1/cortex_loom/types/video_object.py

@@ -0,0 +1,214 @@
+from typing import Optional, Tuple
+
+import av
+from av.container import InputContainer
+from typing_extensions import override
+
+from cortex_types.interfaces import VideoFrameInterface, VideoInterface
+from cortex_types.video_object import VideoFrame as BaseVideoFrame
+from cortex_types.video_object import VideoObject as BaseVideoObject
+from cortex_types.video_object import _VideoObjectProvider
+
+from cortex_loom.types.data_object import DataObject, DataObjectProvider
+from cortex_loom.types.utils import _register_provider
+
+
+class VideoFrame(BaseVideoFrame, VideoFrameInterface):
+    """Single video frame container holding the frame as a NumPy array, as well
+    as its presentiation and decoding timestamp.
+
+    Attributes
+    ----------
+    array : np.ndarray
+        NumPy array representation of the video frame.
+    pts : int
+        Presentation timestamp of the frame.
+    dts : int
+        Decoding timestamp of the frame.
+    """
+
+
+class VideoObject(BaseVideoObject, DataObject, VideoInterface):
+    r"""VideoObject type provides a simple interface for video frames
+    and attributes such as framerate or frame dimensions.
+
+    Attributes
+    ----------
+    frames : Generator[VideoFrame, None, None]
+        A generator yielding VideoFrame objects containing a frame NumPy array
+        and its presentation timestamp.
+    framerate : float
+        The effective framerate of the source video stream.
+    pixel_format : str
+        Format of the video frame pixels, e.g., "rgb24", "bgr24".
+    height : int
+        Height of the video frames yielded by the `frames` generator.
+    width : int
+        Width of the video frames yielded by the `frames` generator.
+    time_base : Fraction
+        The time base fraction indicating the duration represented by each
+        unit increment in `VideoFrame.pts`.
+    codec_name : str
+        Name of the codec of the source video stream, e.g. "h264", "hevc".
+    bit_rate : int
+        Bit rate of the source video stream.
+    duration : float
+        Duration (in seconds) of the VideoObject, roughly equal to the range
+        of the presentation timestamps of frames yielded by `frames`.
+    """
+
+
+@_register_provider(model_type=VideoObject)
+class VideoObjectProvider(_VideoObjectProvider, DataObjectProvider):
+    r"""
+    VideoObjectProvider expects a video input and constructs a
+    `VideoObject` instance.
+
+    This provider loads video files (via PyAV) and allows optional on-the-fly
+    transformations: pixel format conversion, resolution resizing, and frame
+    rotation. It is typically used to obtain frame iterators in a consistent
+    format suitable for downstream computer vision processing.
+
+    Methods
+    -------
+    get_data(file_path, roi=None, **kwargs)
+        Load a video file and return a `VideoObject` with the configured
+        transformations applied.
+
+    """
+
+    VIDEO_OBJECT_TYPE = VideoObject
+
+    def __init__(
+        self,
+        stream_index: int = 0,
+        pixel_format: Optional[str] = "rgb24",
+        rotation: Optional[int] = None,
+        height: Optional[int] = None,
+        width: Optional[int] = None,
+    ):
+        """
+        Parameters
+        ----------
+        stream_index : int, default=0
+            Index of the video stream to extract from the container (usually 0).
+        pixel_format : str or None, default="rgb24"
+            Target pixel format for the decoded frames(e.g. ``"rgb24"``,
+            ``"bgr24"``). If ``None``, preserves the source format.
+        rotation : int or None, default=None
+            Clockwise rotation to apply to each frame. Supported values: ``0``,
+            ``90``, ``180``, ``270``. If ``None``, no additional rotation is applied.
+        height : int or None, default=None
+            Target height for resizing frames. If ``None``, keeps original height.
+        width : int or None, default=None
+            Target width for resizing frames. If ``None``, keeps original width.
+
+        Notes
+        -----
+        - Resizing and rotation are applied in the order: decode → resize → format
+        → rotate conversion;
+        - This class is usually used through the `get_data` method.
+
+        Examples
+        --------
+        Basic usage with default settings (RGB24, no resize/rotation):
+
+        >>> provider = VideoObjectProvider()
+        >>> video = provider.get_data("./example.mp4")
+        >>> video
+        VideoObject(height=1080, width=1920, framerate=29.97, pixel_format='rgb24')
+
+        >>> for frame in video.frames:
+        ...     # frame.array is a numpy array with shape (H, W, 3)
+        ...     process_frame(frame.array)
+
+        With custom parameters (downscale + rotation + specific ROI):
+
+        >>> provider = VideoObjectProvider(
+        ...     pixel_format="rgb24",
+        ...     rotation=90,
+        ...     height=720,
+        ...     width=1280
+        ... )
+        >>> video = provider.get_data(
+        ...     file_path="./example.mp4",
+        ...     roi=(30000, 90000)   # 30s to 90s
+        ... )
+        >>> video
+        VideoObject(height=720, width=1280, framerate=30.0, pixel_format='rgb24')
+        """
+        super().__init__(
+            stream_index=stream_index,
+            pixel_format=pixel_format,
+            rotation=rotation,
+            height=height,
+            width=width,
+        )
+
+    @override
+    def get_data(
+        self,
+        file_path: str,
+        roi: Optional[Tuple[int, int]] = None,
+        **kwargs,
+    ) -> VideoObject:
+        r"""Constructs a `VideoObject` from a local video file.
+
+        Parameters
+        ----------
+        file_path : str
+            Path to a video file (mp4, avi, mov, etc.) that PyAV can decode.
+        roi : tuple of int or None, optional
+            Time interval (start_ms, end_ms) to trim the video to.
+            If ``None``, the full video is used.
+        **kwargs
+            Additional arguments passed to the underlying implementation
+            (rarely used directly).
+
+        Returns
+        -------
+        VideoObject
+            Object that provides video metadata and an iterator over frames.
+
+        Examples
+        --------
+        Default provider, full video:
+
+        >>> provider = VideoObjectProvider()
+        >>> video = provider.get_data("dance.mp4")
+        >>> video.framerate
+        59.94
+
+        Trimmed interval (first 10 seconds):
+
+        >>> video_short = provider.get_data("dance.mp4", roi=(0, 10000))
+        >>> video_short.duration
+        10.0
+
+        Custom provider with preprocessing:
+
+        >>> provider = VideoObjectProvider(pixel_format="rgb24", height=512, width=512)
+        >>> video = provider.get_data("input.mp4")
+        >>> video.pixel_format
+        'rgb24'
+        >>> video.height, video.width
+        (512, 512)
+        """
+        return super().get_data(file_path=file_path, roi=roi, **kwargs)
+
+    @staticmethod
+    def _read_file(file_path: str) -> InputContainer:
+        """Reads the video file and returns a PyAV container.
+
+        Parameters
+        ----------
+        file_path : str
+            Path to the video file.
+
+        Returns
+        -------
+        av.container.InputContainer
+            PyAV container for reading packets/frames.
+        """
+        data = av.open(file=file_path)
+        return data

cortex_loom-0.3.0rc1/pyproject.toml

@@ -0,0 +1,60 @@
+[project]
+name = "cortex-loom"
+version = "0.3.0rc1"
+description = "Package for developing and publishing custom Kelvin Cortex Flows."
+authors = [
+    { name = "MMT Analytics", email = "support@machinemedicine.com" },
+]
+readme = "README.md"
+requires-python = ">=3.11, <3.13"
+
+[tool.poetry]
+packages = [{include = "cortex_loom"}]
+
+[tool.poetry.dependencies]
+requests = "2.32.4"
+cloudpickle = "3.1.1"
+cortex-types = "0.6.4"
+
+# Optional ML dependencies
+pandas = { version = "^2.1", optional = true }
+scipy = { version = "^1.12", optional = true }
+scikit-learn = { version = "^1.4", optional = true }
+xgboost = { version = "^2.0", optional = true }
+lightgbm = { version = "^4.1", optional = true }
+matplotlib = { version = "^3.8", optional = true }
+seaborn = { version = "^0.13", optional = true }
+jupyter = { version = "^1.0", optional = true }
+
+[tool.poetry.extras]
+full = [
+  "pandas",
+  "scipy",
+  "scikit-learn",
+  "xgboost",
+  "lightgbm",
+  "matplotlib",
+  "seaborn",
+  "jupyter",
+]
+
+[dependency-groups]
+docs = [
+    "mkdocs (>=1.6.1,<2.0.0)",
+    "mkdocstrings[python] (>=1.0.2,<2.0.0)",
+    "mkdocs-material (>=9.7.1,<10.0.0)",
+    "mkdocs-gen-files (>=0.6.0,<0.7.0)",
+    "mkdocs-section-index (>=0.3.10,<0.4.0)",
+    "mkdocs-literate-nav (>=0.6.2,<0.7.0)"
+]
+
+[tool.isort]
+profile = "black"
+line_length = 79
+known_first_party = ["cortex_types"]
+known_local_folder = ["cortex_loom"]
+sections = ["FUTURE", "STDLIB", "THIRDPARTY", "FIRSTPARTY", "LOCALFOLDER"]
+
+[build-system]
+requires = ["poetry-core>=2.0.0,<3.0.0"]
+build-backend = "poetry.core.masonry.api"