Skip to content

ImageTensor

docarray.typing.tensor.image.image_ndarray

ImageNdArray

Bases: AbstractImageTensor, NdArray

Subclass of NdArray, to represent an image tensor. Adds image-specific features to the tensor. For instance the ability convert the tensor back to image bytes which are optimized to send over the wire.

from typing import Optional

from docarray import BaseDoc
from docarray.typing import ImageBytes, ImageNdArray, ImageUrl


class MyImageDoc(BaseDoc):
    title: str
    tensor: Optional[ImageNdArray]
    url: Optional[ImageUrl]
    bytes: Optional[ImageBytes]


# from url
doc = MyImageDoc(
    title='my_second_audio_doc',
    url="https://upload.wikimedia.org/wikipedia/commons/8/80/"
    "Dag_Sebastian_Ahlander_at_G%C3%B6teborg_Book_Fair_2012b.jpg",
)

doc.tensor = doc.url.load()

doc.bytes = doc.tensor.to_bytes()
Source code in docarray/typing/tensor/image/image_ndarray.py 
 8
 9
10
11
12
13
14
15
16
17
18
19
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
45
46
47
48
@_register_proto(proto_type_name='image_ndarray')
class ImageNdArray(AbstractImageTensor, NdArray):
    """
    Subclass of [`NdArray`][docarray.typing.NdArray], to represent an image tensor.
    Adds image-specific features to the tensor.
    For instance the ability convert the tensor back to image bytes which are
    optimized to send over the wire.


    ---

    ```python
    from typing import Optional

    from docarray import BaseDoc
    from docarray.typing import ImageBytes, ImageNdArray, ImageUrl


    class MyImageDoc(BaseDoc):
        title: str
        tensor: Optional[ImageNdArray]
        url: Optional[ImageUrl]
        bytes: Optional[ImageBytes]


    # from url
    doc = MyImageDoc(
        title='my_second_audio_doc',
        url="https://upload.wikimedia.org/wikipedia/commons/8/80/"
        "Dag_Sebastian_Ahlander_at_G%C3%B6teborg_Book_Fair_2012b.jpg",
    )

    doc.tensor = doc.url.load()

    doc.bytes = doc.tensor.to_bytes()
    ```

    ---
    """

    ...

docarray.typing.tensor.image.abstract_image_tensor

AbstractImageTensor

Bases: AbstractTensor, ABC

Source code in docarray/typing/tensor/image/abstract_image_tensor.py 
15
16
17
18
19
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
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
class AbstractImageTensor(AbstractTensor, ABC):
    def to_bytes(self, format: str = 'PNG') -> 'ImageBytes':
        """
        Convert image tensor to [`ImageBytes`][docarray.typing.ImageBytes].

        :param format: the image format use to store the image, can be 'PNG' , 'JPG' ...
        :return: an ImageBytes object
        """
        PIL = import_library('PIL', raise_error=True)  # noqa: F841
        from PIL import Image as PILImage

        if format == 'jpg':
            format = 'jpeg'  # unify it to ISO standard

        tensor = self.get_comp_backend().to_numpy(self)

        mode = 'RGB' if tensor.ndim == 3 else 'L'
        pil_image = PILImage.fromarray(tensor, mode=mode)

        with io.BytesIO() as buffer:
            pil_image.save(buffer, format=format)
            img_byte_arr = buffer.getvalue()

        from docarray.typing.bytes.image_bytes import ImageBytes

        return ImageBytes(img_byte_arr)

    def save(self, file_path: str) -> None:
        """
        Save image tensor to an image file.

        :param file_path: path to an image file. If file is a string, open the file by
            that name, otherwise treat it as a file-like object.
        """
        PIL = import_library('PIL', raise_error=True)  # noqa: F841
        from PIL import Image as PILImage

        comp_backend = self.get_comp_backend()
        np_img = comp_backend.to_numpy(self).astype(np.uint8)

        pil_img = PILImage.fromarray(np_img)
        pil_img.save(file_path)

    def display(self) -> None:
        """
        Display image data from tensor in notebook.
        """
        if is_notebook():
            PIL = import_library('PIL', raise_error=True)  # noqa: F841
            from PIL import Image as PILImage

            np_array = self.get_comp_backend().to_numpy(self)
            img = PILImage.fromarray(np_array)

            from IPython.display import display

            display(img)
        else:
            warnings.warn('Display of image is only possible in a notebook.')

display()

Display image data from tensor in notebook.

Source code in docarray/typing/tensor/image/abstract_image_tensor.py 
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
def display(self) -> None:
    """
    Display image data from tensor in notebook.
    """
    if is_notebook():
        PIL = import_library('PIL', raise_error=True)  # noqa: F841
        from PIL import Image as PILImage

        np_array = self.get_comp_backend().to_numpy(self)
        img = PILImage.fromarray(np_array)

        from IPython.display import display

        display(img)
    else:
        warnings.warn('Display of image is only possible in a notebook.')

save(file_path)

Save image tensor to an image file.

Parameters:

Name Type Description Default
file_path str

path to an image file. If file is a string, open the file by that name, otherwise treat it as a file-like object.

 required
Source code in docarray/typing/tensor/image/abstract_image_tensor.py 
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
def save(self, file_path: str) -> None:
    """
    Save image tensor to an image file.

    :param file_path: path to an image file. If file is a string, open the file by
        that name, otherwise treat it as a file-like object.
    """
    PIL = import_library('PIL', raise_error=True)  # noqa: F841
    from PIL import Image as PILImage

    comp_backend = self.get_comp_backend()
    np_img = comp_backend.to_numpy(self).astype(np.uint8)

    pil_img = PILImage.fromarray(np_img)
    pil_img.save(file_path)

to_bytes(format='PNG')

Convert image tensor to ImageBytes.

Parameters:

Name Type Description Default
format str

the image format use to store the image, can be 'PNG' , 'JPG' ...

 'PNG'

Returns:

Type Description
ImageBytes

an ImageBytes object
Source code in docarray/typing/tensor/image/abstract_image_tensor.py 
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
def to_bytes(self, format: str = 'PNG') -> 'ImageBytes':
    """
    Convert image tensor to [`ImageBytes`][docarray.typing.ImageBytes].

    :param format: the image format use to store the image, can be 'PNG' , 'JPG' ...
    :return: an ImageBytes object
    """
    PIL = import_library('PIL', raise_error=True)  # noqa: F841
    from PIL import Image as PILImage

    if format == 'jpg':
        format = 'jpeg'  # unify it to ISO standard

    tensor = self.get_comp_backend().to_numpy(self)

    mode = 'RGB' if tensor.ndim == 3 else 'L'
    pil_image = PILImage.fromarray(tensor, mode=mode)

    with io.BytesIO() as buffer:
        pil_image.save(buffer, format=format)
        img_byte_arr = buffer.getvalue()

    from docarray.typing.bytes.image_bytes import ImageBytes

    return ImageBytes(img_byte_arr)

docarray.typing.tensor.image.image_tensorflow_tensor

ImageTensorFlowTensor

Bases: TensorFlowTensor, AbstractImageTensor

Subclass of TensorFlowTensor, to represent an image tensor. Adds image-specific features to the tensor. For instance the ability convert the tensor back to ImageBytes which are optimized to send over the wire.

from typing import Optional

from docarray import BaseDoc
from docarray.typing import ImageBytes, ImageTensorFlowTensor, ImageUrl


class MyImageDoc(BaseDoc):
    title: str
    tensor: Optional[ImageTensorFlowTensor]
    url: Optional[ImageUrl]
    bytes: Optional[ImageBytes]


doc = MyImageDoc(
    title='my_second_image_doc',
    url="https://upload.wikimedia.org/wikipedia/commons/8/80/"
    "Dag_Sebastian_Ahlander_at_G%C3%B6teborg_Book_Fair_2012b.jpg",
)
doc.tensor = doc.url.load()
doc.bytes = doc.tensor.to_bytes()
Source code in docarray/typing/tensor/image/image_tensorflow_tensor.py 
10
11
12
13
14
15
16
17
18
19
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
45
46
47
48
49
50
@_register_proto(proto_type_name='image_tensorflow_tensor')
class ImageTensorFlowTensor(
    TensorFlowTensor, AbstractImageTensor, metaclass=metaTensorFlow
):
    """
    Subclass of [`TensorFlowTensor`][docarray.typing.TensorFlowTensor],
    to represent an image tensor. Adds image-specific features to the tensor.
    For instance the ability convert the tensor back to
    [`ImageBytes`][docarray.typing.ImageBytes] which are
    optimized to send over the wire.


    ---

    ```python
    from typing import Optional

    from docarray import BaseDoc
    from docarray.typing import ImageBytes, ImageTensorFlowTensor, ImageUrl


    class MyImageDoc(BaseDoc):
        title: str
        tensor: Optional[ImageTensorFlowTensor]
        url: Optional[ImageUrl]
        bytes: Optional[ImageBytes]


    doc = MyImageDoc(
        title='my_second_image_doc',
        url="https://upload.wikimedia.org/wikipedia/commons/8/80/"
        "Dag_Sebastian_Ahlander_at_G%C3%B6teborg_Book_Fair_2012b.jpg",
    )
    doc.tensor = doc.url.load()
    doc.bytes = doc.tensor.to_bytes()
    ```

    ---
    """

    ...

docarray.typing.tensor.image.image_torch_tensor

ImageTorchTensor

Bases: AbstractImageTensor, TorchTensor

Subclass of TorchTensor, to represent an image tensor. Adds image-specific features to the tensor. For instance the ability convert the tensor back to ImageBytes which are optimized to send over the wire.

from typing import Optional

from docarray import BaseDoc
from docarray.typing import ImageBytes, ImageTorchTensor, ImageUrl


class MyImageDoc(BaseDoc):
    title: str
    tensor: Optional[ImageTorchTensor]
    url: Optional[ImageUrl]
    bytes: Optional[ImageBytes]


doc = MyImageDoc(
    title='my_second_image_doc',
    url="https://upload.wikimedia.org/wikipedia/commons/8/80/"
    "Dag_Sebastian_Ahlander_at_G%C3%B6teborg_Book_Fair_2012b.jpg",
)

doc.tensor = doc.url.load()
doc.bytes = doc.tensor.to_bytes()
Source code in docarray/typing/tensor/image/image_torch_tensor.py 
10
11
12
13
14
15
16
17
18
19
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
45
46
47
48
49
@_register_proto(proto_type_name='image_torch_tensor')
class ImageTorchTensor(AbstractImageTensor, TorchTensor, metaclass=metaTorchAndNode):
    """
    Subclass of [`TorchTensor`][docarray.typing.TorchTensor], to represent an image tensor.
    Adds image-specific features to the tensor.
    For instance the ability convert the tensor back to
    [`ImageBytes`][docarray.typing.ImageBytes] which are
    optimized to send over the wire.


    ---

    ```python
    from typing import Optional

    from docarray import BaseDoc
    from docarray.typing import ImageBytes, ImageTorchTensor, ImageUrl


    class MyImageDoc(BaseDoc):
        title: str
        tensor: Optional[ImageTorchTensor]
        url: Optional[ImageUrl]
        bytes: Optional[ImageBytes]


    doc = MyImageDoc(
        title='my_second_image_doc',
        url="https://upload.wikimedia.org/wikipedia/commons/8/80/"
        "Dag_Sebastian_Ahlander_at_G%C3%B6teborg_Book_Fair_2012b.jpg",
    )

    doc.tensor = doc.url.load()
    doc.bytes = doc.tensor.to_bytes()
    ```

    ---
    """

    ...