Skip to content

Register now for

# Reference for `ultralytics/utils/patches.py`

Note

This file is available at https://github.com/ultralytics/ultralytics/blob/main/ultralytics/utils/patches.py. If you spot a problem please help fix it by contributing a Pull Request 🛠️. Thank you 🙏!

## `` ultralytics.utils.patches.imread

    imread(filename: str, flags: int = cv2.IMREAD_COLOR) -> np.ndarray | None

Read an image from a file with multilanguage filename support.

Parameters:

Name | Type | Description | Default
--- | --- | --- | ---
`filename` | `str` | Path to the file to read. | required
`flags` | `int` | Flag that can take values of cv2.IMREAD_*. Controls how the image is read. | `IMREAD_COLOR`

Returns:

Type | Description
--- | ---
`ndarray | None` | The read image array, or None if reading fails.

Examples:

    >>> img = imread("path/to/image.jpg")
    >>> img = imread("path/to/image.jpg", cv2.IMREAD_GRAYSCALE)

Source code in `ultralytics/utils/patches.py`

    20
    21
    22
    23
    24
    25
    26
    27
    28
    29
    30
    31
    32
    33
    34
    35
    36
    37
    38
    39
    40
    41
    42
    43
    44
    def imread(filename: str, flags: int = cv2.IMREAD_COLOR) -> np.ndarray | None:
        """
        Read an image from a file with multilanguage filename support.

        Args:
            filename (str): Path to the file to read.
            flags (int, optional): Flag that can take values of cv2.IMREAD_*. Controls how the image is read.

        Returns:
            (np.ndarray | None): The read image array, or None if reading fails.

        Examples:
            >>> img = imread("path/to/image.jpg")
            >>> img = imread("path/to/image.jpg", cv2.IMREAD_GRAYSCALE)
        """
        file_bytes = np.fromfile(filename, np.uint8)
        if filename.endswith((".tiff", ".tif")):
            success, frames = cv2.imdecodemulti(file_bytes, cv2.IMREAD_UNCHANGED)
            if success:
                # Handle RGB images in tif/tiff format
                return frames[0] if len(frames) == 1 and frames[0].ndim == 3 else np.stack(frames, axis=2)
            return None
        else:
            im = cv2.imdecode(file_bytes, flags)
            return im[..., None] if im is not None and im.ndim == 2 else im  # Always ensure 3 dimensions

## `` ultralytics.utils.patches.imwrite

    imwrite(filename: str, img: ndarray, params: list[int] | None = None) -> bool

Write an image to a file with multilanguage filename support.

Parameters:

Name | Type | Description | Default
--- | --- | --- | ---
`filename` | `str` | Path to the file to write. | required
`img` | `ndarray` | Image to write. | required
`params` | `list[int]` | Additional parameters for image encoding. | `None`

Returns:

Type | Description
--- | ---
`bool` | True if the file was written successfully, False otherwise.

Examples:

    >>> import numpy as np
    >>> img = np.zeros((100, 100, 3), dtype=np.uint8)  # Create a black image
    >>> success = imwrite("output.jpg", img)  # Write image to file
    >>> print(success)
    True

Source code in `ultralytics/utils/patches.py`

    47
    48
    49
    50
    51
    52
    53
    54
    55
    56
    57
    58
    59
    60
    61
    62
    63
    64
    65
    66
    67
    68
    69
    70
    def imwrite(filename: str, img: np.ndarray, params: list[int] | None = None) -> bool:
        """
        Write an image to a file with multilanguage filename support.

        Args:
            filename (str): Path to the file to write.
            img (np.ndarray): Image to write.
            params (list[int], optional): Additional parameters for image encoding.

        Returns:
            (bool): True if the file was written successfully, False otherwise.

        Examples:
            >>> import numpy as np
            >>> img = np.zeros((100, 100, 3), dtype=np.uint8)  # Create a black image
            >>> success = imwrite("output.jpg", img)  # Write image to file
            >>> print(success)
            True
        """
        try:
            cv2.imencode(Path(filename).suffix, img, params)[1].tofile(filename)
            return True
        except Exception:
            return False

## `` ultralytics.utils.patches.imshow

    imshow(winname: str, mat: ndarray) -> None

Display an image in the specified window with multilanguage window name support.

This function is a wrapper around OpenCV's imshow function that displays an image in a named window. It handles multilanguage window names by encoding them properly for OpenCV compatibility.

Parameters:

Name | Type | Description | Default
--- | --- | --- | ---
`winname` | `str` | Name of the window where the image will be displayed. If a window with this name already exists, the image will be displayed in that window. | required
`mat` | `ndarray` | Image to be shown. Should be a valid numpy array representing an image. | required

Examples:

    >>> import numpy as np
    >>> img = np.zeros((300, 300, 3), dtype=np.uint8)  # Create a black image
    >>> img[:100, :100] = [255, 0, 0]  # Add a blue square
    >>> imshow("Example Window", img)  # Display the image

Source code in `ultralytics/utils/patches.py`

    73
    74
    75
    76
    77
    78
    79
    80
    81
    82
    83
    84
    85
    86
    87
    88
    89
    90
    91
    def imshow(winname: str, mat: np.ndarray) -> None:
        """
        Display an image in the specified window with multilanguage window name support.

        This function is a wrapper around OpenCV's imshow function that displays an image in a named window. It handles
        multilanguage window names by encoding them properly for OpenCV compatibility.

        Args:
            winname (str): Name of the window where the image will be displayed. If a window with this name already
                exists, the image will be displayed in that window.
            mat (np.ndarray): Image to be shown. Should be a valid numpy array representing an image.

        Examples:
            >>> import numpy as np
            >>> img = np.zeros((300, 300, 3), dtype=np.uint8)  # Create a black image
            >>> img[:100, :100] = [255, 0, 0]  # Add a blue square
            >>> imshow("Example Window", img)  # Display the image
        """
        _imshow(winname.encode("unicode_escape").decode(), mat)

## `` ultralytics.utils.patches.torch_load

    torch_load(*args, **kwargs)

Load a PyTorch model with updated arguments to avoid warnings.

This function wraps torch.load and adds the 'weights_only' argument for PyTorch 1.13.0+ to prevent warnings.

Parameters:

Name | Type | Description | Default
--- | --- | --- | ---
`*args` | `Any` | Variable length argument list to pass to torch.load. | `()`
`**kwargs` | `Any` | Arbitrary keyword arguments to pass to torch.load. | `{}`

Returns:

Type | Description
--- | ---
`Any` | The loaded PyTorch object.

Notes

For PyTorch versions 2.0 and above, this function automatically sets 'weights_only=False' if the argument is not provided, to avoid deprecation warnings.

Source code in `ultralytics/utils/patches.py`

     98
     99
    100
    101
    102
    103
    104
    105
    106
    107
    108
    109
    110
    111
    112
    113
    114
    115
    116
    117
    118
    119
    120
    def torch_load(*args, **kwargs):
        """
        Load a PyTorch model with updated arguments to avoid warnings.

        This function wraps torch.load and adds the 'weights_only' argument for PyTorch 1.13.0+ to prevent warnings.

        Args:
            *args (Any): Variable length argument list to pass to torch.load.
            **kwargs (Any): Arbitrary keyword arguments to pass to torch.load.

        Returns:
            (Any): The loaded PyTorch object.

        Notes:
            For PyTorch versions 2.0 and above, this function automatically sets 'weights_only=False'
            if the argument is not provided, to avoid deprecation warnings.
        """
        from ultralytics.utils.torch_utils import TORCH_1_13

        if TORCH_1_13 and "weights_only" not in kwargs:
            kwargs["weights_only"] = False

        return torch.load(*args, **kwargs)

## `` ultralytics.utils.patches.torch_save

    torch_save(*args, **kwargs)

Save PyTorch objects with retry mechanism for robustness.

This function wraps torch.save with 3 retries and exponential backoff in case of save failures, which can occur due to device flushing delays or antivirus scanning.

Parameters:

Name | Type | Description | Default
--- | --- | --- | ---
`*args` | `Any` | Positional arguments to pass to torch.save. | `()`
`**kwargs` | `Any` | Keyword arguments to pass to torch.save. | `{}`

Examples:

    >>> model = torch.nn.Linear(10, 1)
    >>> torch_save(model.state_dict(), "model.pt")

Source code in `ultralytics/utils/patches.py`

    123
    124
    125
    126
    127
    128
    129
    130
    131
    132
    133
    134
    135
    136
    137
    138
    139
    140
    141
    142
    143
    144
    def torch_save(*args, **kwargs):
        """
        Save PyTorch objects with retry mechanism for robustness.

        This function wraps torch.save with 3 retries and exponential backoff in case of save failures, which can occur
        due to device flushing delays or antivirus scanning.

        Args:
            *args (Any): Positional arguments to pass to torch.save.
            **kwargs (Any): Keyword arguments to pass to torch.save.

        Examples:
            >>> model = torch.nn.Linear(10, 1)
            >>> torch_save(model.state_dict(), "model.pt")
        """
        for i in range(4):  # 3 retries
            try:
                return _torch_save(*args, **kwargs)
            except RuntimeError as e:  # Unable to save, possibly waiting for device to flush or antivirus scan
                if i == 3:
                    raise e
                time.sleep((2**i) / 2)  # Exponential backoff: 0.5s, 1.0s, 2.0s

## `` ultralytics.utils.patches.arange_patch

    arange_patch(args)

Workaround for ONNX torch.arange incompatibility with FP16.

https://github.com/pytorch/pytorch/issues/148041.

Source code in `ultralytics/utils/patches.py`

    147
    148
    149
    150
    151
    152
    153
    154
    155
    156
    157
    158
    159
    160
    161
    162
    163
    164
    165
    @contextmanager
    def arange_patch(args):
        """
        Workaround for ONNX torch.arange incompatibility with FP16.

        https://github.com/pytorch/pytorch/issues/148041.
        """
        if args.dynamic and args.half and args.format == "onnx":
            func = torch.arange

            def arange(*args, dtype=None, **kwargs):
                """Return a 1-D tensor of size with values from the interval and common difference."""
                return func(*args, **kwargs).to(dtype)  # cast to dtype instead of passing dtype

            torch.arange = arange  # patch
            yield
            torch.arange = func  # unpatch
        else:
            yield

## `` ultralytics.utils.patches.override_configs

    override_configs(args, overrides: dict[str, Any] | None = None)

Context manager to temporarily override configurations in args.

Parameters:

Name | Type | Description | Default
--- | --- | --- | ---
`args` | `IterableSimpleNamespace` | Original configuration arguments. | required
`overrides` | `dict[str, Any]` | Dictionary of overrides to apply. | `None`

Yields:

Type | Description
--- | ---
`IterableSimpleNamespace` | Configuration arguments with overrides applied.

Source code in `ultralytics/utils/patches.py`

    168
    169
    170
    171
    172
    173
    174
    175
    176
    177
    178
    179
    180
    181
    182
    183
    184
    185
    186
    187
    188
    189
    @contextmanager
    def override_configs(args, overrides: dict[str, Any] | None = None):
        """
        Context manager to temporarily override configurations in args.

        Args:
            args (IterableSimpleNamespace): Original configuration arguments.
            overrides (dict[str, Any]): Dictionary of overrides to apply.

        Yields:
            (IterableSimpleNamespace): Configuration arguments with overrides applied.
        """
        if overrides:
            original_args = copy(args)
            for key, value in overrides.items():
                setattr(args, key, value)
            try:
                yield args
            finally:
                args.__dict__.update(original_args.__dict__)
        else:
            yield args

📅 Created 1 year ago ✏️ Updated 3 months ago