# Source code for enaml.image

    #------------------------------------------------------------------------------
    # Copyright (c) 2013-2025, Nucleic Development Team.
    #
    # Distributed under the terms of the Modified BSD License.
    #
    # The full license is in the file LICENSE, distributed with this software.
    #------------------------------------------------------------------------------
    from atom.api import Atom, Enum, Bytes, Value, Coerced

    from enaml.layout.geometry import Size

    class Image(Atom):
        """ An object representing an image.

        Once an image is created it should be treated as read only. User
        code should create a new image object if the parameters need to
        be changed.

        """
        #: The format of the image. By default, the consumer of the image
        #: will probe the header to automatically infer a type.
        #: Base64 images need to be decoded using the base64.b64decode function
        #: from the standard library.
        format = Enum(
            'auto',     # Automatically determine the image format
            'png',      # Portable Network Graphics
            'jpg',      # Joint Photographic Experts Group
            'gif',      # Graphics Interchange Format
            'bmp',      # Windows Bitmap
            'xpm',      # X11 Pixmap
            'xbm',      # X11 Bitmap
            'pbm',      # Portable Bitmap
            'pgm',      # Portable Graymap
            'ppm',      # Portable Pixmap
            'tiff',     # Tagged Image File Format
            'argb32',   # Raw data in the 0xAARRGGBB format.
                        # The `raw_size` of the image must be provided.
        )

        #: The (width, height) raw size of the image. This must be provided
        #: for images where the size is not encoded in the data stream.
        raw_size = Coerced(Size, (0, 0))

        #: The (width, height) size of the image. An invalid size indicates
        #: that the size of the image should be automatically inferred. A
        #: valid size indicates that the toolkit image should be scaled to
        #: the specified size.
        size = Coerced(Size, (-1, -1))

        #: The aspect ratio mode to use when the toolkit scales the image.
        aspect_ratio_mode = Enum('ignore', 'keep', 'keep_by_expanding')

        #: The transform mode to use when the toolkit scales the image.
        transform_mode = Enum('smooth', 'fast')

        # XXX this needs to be augmented to support arrays.
        #: The bytestring holding the data for the image.
        data = Bytes()

        #: Storage space for use by a toolkit backend to use as needed.
        #: This should not typically be manipulated by user code.
        _tkdata = Value()