Package com.sksamuel.scrimage

Class ImmutableImage

  • public class ImmutableImage
extends MutableImage
    An immutable Image backed by an AWT BufferedImage.

    An Image represents an abstraction that allow operations such as resize, scale, rotate, flip, trim, pad, cover, fit.

    All operations on an ImmutableImage are read only or return a cloned instance of this image. For operations that can be performed without a copying step, see MutableImage.

    • Method Detail

      • fromAwt

        public static ImmutableImage fromAwt​(java.awt.image.BufferedImage awt)
        Create a new [ImmutableImage] from a source AWT Image. This method will copy the source image so that modifications to the original do not write forward to this image.
        Parameters:
        awt - the source AWT Image
        Returns:
        a new ImmutableImage

      • fromAwt

        public static ImmutableImage fromAwt​(java.awt.image.BufferedImage awt,
                                     int type)
        Create a new [ImmutableImage] from a source AWT Image. This method will copy the source image so that modifications to the original do not write forward to this image.

        If the given type is greater than 0, then a copy will be made using that type for the image. If the param type is -1, then the source image type will be used, unless the source image has type 0, in which case BufferedImage.TYPE_INT_ARGB will be used.

        Parameters:
        awt - the source AWT Image
        Returns:
        a new ImmutableImage

      • wrapAwt

        public static ImmutableImage wrapAwt​(java.awt.image.BufferedImage awt,
                                     ImageMetadata metadata)
        Creates a new [ImmutableImage] from an AWT image by wrapping that source image. Note: Modifications to the source will write forward to this image. In other words, this method should not be used if the source is going to be shared. This method is intended for when an AWT image is created as an intermediate step and never exposed.
        Parameters:
        awt - the source AWT Image
        metadata - the image metadata
        Returns:
        a new ImmutableImage

      • wrapAwt

        public static ImmutableImage wrapAwt​(java.awt.image.BufferedImage awt)
        Creates a new [ImmutableImage] from an AWT image by wrapping that source image. Note: Modifications to the source will write forward to this image. In other words, this method should not be used if the source is going to be shared. This method is intended for when an AWT image is created as an intermediate step and never exposed.
        Parameters:
        awt - the source AWT Image
        Returns:
        a new ImmutableImage

      • wrapAwt

        public static ImmutableImage wrapAwt​(java.awt.image.BufferedImage awt,
                                     int type)
        Creates a new [ImmutableImage] from an AWT image by wrapping that source image. Since the source buffer is wrapped, any changes to the original will write through. If you require a completely independent and truely immutable image, then consider [fromAwt].

        If the given awt image does not have the same type as requested, then this will force the image to be copied using [fromAwt].

        Parameters:
        awt - the source AWT Image
        type - the AWT image type to use. If the image is not in this format already it will be coped. specify UNDERLYING_DATA_TYPE if you want to use the original
        Returns:
        a new Scrimage Image

      • fromFile

        @Deprecated
public static ImmutableImage fromFile​(java.io.File file)
                               throws java.io.IOException
        Deprecated.
        use ImmutableImage.loader().fromFile(file);
        Creates a new [ImmutableImage] from a file. This method will also attach metadata.
        Throws:
        java.io.IOException

      • fromPath

        @Deprecated
public static ImmutableImage fromPath​(java.nio.file.Path path)
                               throws java.io.IOException
        Deprecated.
        use ImmutableImage.loader().fromPath(path);
        Creates a new [ImmutableImage] from a path. This method will also attach metadata.
        Throws:
        java.io.IOException

      • create

        public static ImmutableImage create​(int width,
                                    int height)
        Create a new ImmutableImage that is the given width and height with no initialization. This will usually result in a default black background (all pixel data defaulting to zeroes) but that is not guaranteed. The type of the image will be [ImmutableImage.DEFAULT_DATA_TYPE].
        Parameters:
        width - the width of the new image
        height - the height of the new image
        Returns:
        the new Image with the given width and height

      • create

        public static ImmutableImage create​(int width,
                                    int height,
                                    int type)
        Create a new ImmutableImage that is the given width and height and type with no initialization. This will usually result in a default black background (all pixel data defaulting to zeroes) but that is not guaranteed. The underlying image will have the type specified.
        Parameters:
        width - the width of the new image
        height - the height of the new image
        Returns:
        the new Image with the given width and height

      • filled

        public static ImmutableImage filled​(int width,
                                    int height,
                                    java.awt.Color color)
        Return a new ImmutableImage with the given width and height, with all pixels set to the supplied colour. The type of the image will be [ImmutableImage.CANONICAL_DATA_TYPE].
        Parameters:
        width - the width of the new Image
        height - the height of the new Image
        color - the color to set all pixels to
        Returns:
        the new Image

      • filled

        public static ImmutableImage filled​(int width,
                                    int height,
                                    java.awt.Color color,
                                    int type)
        Return a new ImmutableImage with the given width and height and type, with all pixels set to the supplied colour.
        Parameters:
        width - the width of the new Image
        height - the height of the new Image
        color - the color to set all pixels to
        Returns:
        the new Image

      • fromStream

        @Deprecated
public static ImmutableImage fromStream​(java.io.InputStream in)
                                 throws java.io.IOException
        Deprecated.
        use ImmutableImage.loader().fromFile(file);
        Create a new Image from an input stream. This is intended to create an image from an image format eg PNG, not from a stream of pixels. This method will also attach metadata if available.
        Parameters:
        in - the stream to read the bytes from
        Returns:
        a new Image
        Throws:
        java.io.IOException

      • fromStream

        @Deprecated
public static ImmutableImage fromStream​(java.io.InputStream in,
                                        int type)
                                 throws java.io.IOException
        Deprecated.
        use ImmutableImage.loader().fromFile(file);
        Create a new Image from an input stream. This is intended to create an image from an image format eg PNG, not from a stream of pixels. This method will also attach metadata if available. The image will have the given type. If the given type is not the same as stored in the stream, this will force the image to be copied. Consider using fromStream(in).
        Parameters:
        in - the stream to read the bytes from
        Returns:
        a new Image
        Throws:
        java.io.IOException

      • fromResource

        @Deprecated
public static ImmutableImage fromResource​(java.lang.String path)
                                   throws java.io.IOException
        Deprecated.
        use ImmutableImage.loader().fromResource(file);
        Creates a new Image from the resource on the classpath.
        Throws:
        java.io.IOException

      • fromResource

        @Deprecated
public static ImmutableImage fromResource​(java.lang.String path,
                                          int type)
                                   throws java.io.IOException
        Deprecated.
        use ImmutableImage.loader().fromResource(file);
        Throws:
        java.io.IOException

      • create

        public static ImmutableImage create​(int w,
                                    int h,
                                    Pixel[] pixels)
        Create a new Image from an array of pixels. The specified width and height must match the number of pixels. The image's type will be CANONICAL_DATA_TYPE.
        Returns:
        a new Image

      • create

        public static ImmutableImage create​(int w,
                                    int h,
                                    Pixel[] pixels,
                                    int type)
        Create a new Image from an array of pixels with the given type. The specified width and height must match the number of pixels.
        Returns:
        a new Image

      • parse

        @Deprecated
public static ImmutableImage parse​(byte[] bytes)
                            throws java.io.IOException
        Deprecated.
        use ImmutableImage.loader().fromBytes(file);
        Create a new Image from an array of bytes. This is intended to create an image from an image format eg PNG, not from a stream of pixels.
        Parameters:
        bytes - the bytes from the format stream
        Returns:
        a new Image
        Throws:
        java.io.IOException

      • parse

        @Deprecated
public static ImmutableImage parse​(byte[] bytes,
                                   int type)
                            throws java.io.IOException
        Deprecated.
        use ImmutableImage.loader().fromBytes(file);
        Create a new Image from an array of bytes. This is intended to create an image from an image format eg PNG, not from a stream of pixels.

        The final image will have the given type. Note, if the image is not stored in the given type, then it will need to be copied. Unless you have a reason to specify the format, use parse(byte[]) and allow the image readers to choose the most appropriate type.

        Parameters:
        bytes - the bytes from the format stream
        Returns:
        a new Image
        Throws:
        java.io.IOException

      • autocrop

        public ImmutableImage autocrop​(java.awt.Color color,
                               int colorTolerance)
        Crops an image by removing cols and rows that are composed only of a single given color.

        Eg, if an image had a 20 pixel row of white at the top, and this method was invoked with Color.WHITE then the image returned would have that 20 pixel row removed.

        This method is useful when images have an abudance of a single colour around them.

        Parameters:
        color - the color to match
        colorTolerance - the amount of tolerance to use when determining whether the color matches the reference color [0..255]

      • blank

        public ImmutableImage blank()
        Creates an empty ImmutableImage of the same concrete type as this image and with the same dimensions. The underlying pixels will not be initialized.
        Returns:
        a new Image that is a clone of this image but with uninitialized data

      • bound

        public ImmutableImage bound​(int w,
                            int h)
        Convenience method for bound(w, h, ScaleMethod.Bicubic)

      • bound

        public ImmutableImage bound​(int w,
                            int h,
                            ScaleMethod scaleMethod)
        Returns an image that is no larger than the given width and height keeping the same aspect ratio.

        If the current image is already within the given dimensions then the same image will be returned. If not, then a scaled image, with the same aspect ratio as the original, and with dimensions inside the constraints will be returned.

        This operation differs from max, in that max will scale an image up to be as large as it can be inside the constraints. Bound will keep the image the same if its already within the constraints.

        Parameters:
        w - the maximum width
        h - the maximum height
        Returns:
        the constrained image.

      • brightness

        public ImmutableImage brightness​(double factor)
        Returns a new Image with the brightness adjusted.

      • copy

        public ImmutableImage copy()
        Creates a new image with the same data as this image. Any operations to the copied image will not write back to the original.
        Returns:
        A copy of this image.

      • copy

        public ImmutableImage copy​(int type)
        Returns a copy of this image with the underlying image type set to the given value. The type value is one of the AWT standard image types, taken from BufferedImage.

      • composite

        public ImmutableImage composite​(Composite composite,
                                ImmutableImage applicative)
        Apply the given image with this image using the given composite. The original image is unchanged.
        Parameters:
        composite - the composite to use. See com.sksamuel.scrimage.Composite.
        applicative - the image to apply with the composite.
        Returns:
        A new image with the given image applied using the given composite.

      • contrast

        public ImmutableImage contrast​(double factor)
        Returns a new Image with the contrast adjusted.

      • cover

        public ImmutableImage cover​(int targetWidth,
                            int targetHeight)
        Convenience method for cover(targetWidth, targetHeight, ScaleMethod.Bicubic, Position.Center)

      • cover

        public ImmutableImage cover​(int targetWidth,
                            int targetHeight,
                            Position position)
        Convenience method for cover(targetWidth, targetHeight, ScaleMethod.Bicubic, position)

      • cover

        public ImmutableImage cover​(int targetWidth,
                            int targetHeight,
                            ScaleMethod scaleMethod,
                            Position position)
        Returns an image with the given dimensions where this image has been scaled to completely cover the new dimensions whilst retaining the original aspect ratio.

        If the given dimensions have a different aspect ratio than this image then the image will be cropped so that it still covers the new area without leaving any background.

        In other words, the image "covers" the target dimensions with the potential loss of some of the image if the aspect ratio change. Similar to taking a 16:9 movie and resizing it for a 4:3 screen. You can either lose part of the image (this operation) or resize it so there is empty space on two sides (the fit operation).

        Parameters:
        targetWidth - the target width
        targetHeight - the target height
        scaleMethod - the type of scaling method to use. Defaults to Bicubic
        position - where to position the image inside the new canvas
        Returns:
        a new Image with the original image scaled to cover the new dimensions

      • fill

        public ImmutableImage fill​(java.awt.Color color)
        Creates a new Image with the same dimensions of this image and with all the pixels initialized to the given color.
        Returns:
        a new Image with the same dimensions as this

      • fill

        public ImmutableImage fill​(Painter painter)
        Creates a new Image with the same dimensions of this image and with all the pixels initialized using the given painter.
        Returns:
        a new Image with the same dimensions as this

      • filter

        public ImmutableImage filter​(Filter... filters)
                      throws java.io.IOException
        Apply a sequence of filters in sequence. This is sugar for image.filter(filter1).filter(filter2)....
        Parameters:
        filters - the sequence filters to apply
        Returns:
        the result of applying each filter in turn
        Throws:
        java.io.IOException

      • filter

        public ImmutableImage filter​(Filter filter)
                      throws java.io.IOException
        Creates a copy of this image with the given filter applied. The original (this) image is unchanged.
        Parameters:
        filter - the filter to apply. See com.sksamuel.scrimage.Filter.
        Returns:
        A new image with the given filter applied.
        Throws:
        java.io.IOException

      • fit

        public ImmutableImage fit​(int canvasWidth,
                          int canvasHeight)
        Convenience method for: fit(canvasWidth, canvasHeight, Colors.Transparent.toAWT(), ScaleMethod.Bicubic, Position.Center)

      • fit

        public ImmutableImage fit​(int canvasWidth,
                          int canvasHeight,
                          java.awt.Color color)

      • fit

        public ImmutableImage fit​(int canvasWidth,
                          int canvasHeight,
                          java.awt.Color color,
                          Position position)

      • fit

        public ImmutableImage fit​(int canvasWidth,
                          int canvasHeight,
                          java.awt.Color color,
                          ScaleMethod scaleMethod,
                          Position position)
        Returns a copy of this image with the given dimensions where the original image has been scaled to fit completely inside the new dimensions whilst retaining the original aspect ratio.

        In other words, the image "fits" the target dimensions without losing any of the image if the aspect ratio change. Similar to taking a 16:9 movie and resizing it for a 4:3 screen. You can either lose part of the image (cover operation) or resize it so there is empty space on two sides (this operation).

        Parameters:
        canvasWidth - the target width
        canvasHeight - the target height
        scaleMethod - the algorithm to use for the scaling operation. See ScaleMethod.
        color - the color to use as the "padding" colour should the scaled original not fit exactly inside the new dimensions
        position - where to position the image inside the new canvas
        Returns:
        a new Image with the original image scaled to fit inside

      • quantize

        public RGBColor[] quantize​(int colours)
        Returns the most n used colours in this image.
        Parameters:
        colours - how many colours to quantize for.

      • flipX

        public ImmutableImage flipX()
        Flips this image horizontally.
        Returns:
        The result of flipping this image horizontally.

      • flipY

        public ImmutableImage flipY()
        Flips this image vertically.
        Returns:
        The result of flipping this image vertically.

      • max

        public ImmutableImage max​(int maxW,
                          int maxH)
        Convenience method for max(maxW, maxH, ScaleMethod.Bicubic)

      • max

        public ImmutableImage max​(int maxW,
                          int maxH,
                          ScaleMethod scaleMethod)
        Returns a new image that is scaled to fit the specified bounds while retaining the same aspect ratio as the original image. The dimensions of the returned image will be the same as the result of the scaling operation. That is, no extra padding will be added to match the bounded width and height.

        For an operation that will scale an image as well as add padding to fit the dimensions perfectly, then use fit. For an operation that will only resize smaller, and not larger, see bound.

        Requesting a bound of 200,200 on an image of 300,600 will result in a scale to 100,200. Eg, the original image will be scaled down to fit the bounds.

        Requesting a bound of 150,200 on an image of 150,150 will result in the same image being returned. Eg, the original image cannot be scaled up any further without exceeding the bounds.

        Requesting a bound of 300,300 on an image of 100,150 will result in a scale to 200,300.

        Requesting a bound of 100,1000 on an image of 50,50 will result in a scale to 100,100.

        Parameters:
        maxW - the maximum width
        maxH - the maximum height
        Returns:
        A new image that is the result of the binding.

      • op

        public ImmutableImage op​(java.awt.image.BufferedImageOp op)

      • overlay

        public ImmutableImage overlay​(AwtImage overlayImage)
        Returns a new image that is the result of overlaying the given image over this image. That is, the existing image ends up being "under" the image parameter. The x / y parameters determine where the (0,0) coordinate of the overlay should be placed.

        If the image to render exceeds the boundaries of the source image, then the excess pixels will be ignored.

        Returns:
        a new Image with the given image overlaid.

      • resize

        public ImmutableImage resize​(double scaleFactor,
                             java.awt.Color background)

      • resize

        public ImmutableImage resize​(double scaleFactor,
                             Position position,
                             java.awt.Color background)
        Resize will resize the canvas, it will not scale the image. This is like a "canvas resize" in Photoshop.
        Parameters:
        scaleFactor - the scaleFactor. 1 retains original size. 0.5 is half. 2 double. etc
        position - where to position the original image after the canvas size change. Defaults to centre.
        background - the color to use for expande background areas.
        Returns:
        a new Image that is the result of resizing the canvas.

      • resizeTo

        public ImmutableImage resizeTo​(int targetWidth,
                               int targetHeight)

      • resizeTo

        public ImmutableImage resizeTo​(int targetWidth,
                               int targetHeight,
                               java.awt.Color color)

      • resizeTo

        public ImmutableImage resizeTo​(int targetWidth,
                               int targetHeight,
                               Position position,
                               java.awt.Color background)
        Resize will resize the canvas, it will not scale the image. This is like a "canvas resize" in Photoshop.

        If the dimensions are smaller than the current canvas size then the image will be cropped.

        The position parameter determines how the original image will be positioned on the new canvas.

        Parameters:
        targetWidth - the target width
        targetHeight - the target height
        position - where to position the original image after the canvas size change
        background - the background color if the canvas was enlarged
        Returns:
        a new Image that is the result of resizing the canvas.

      • resizeToRatio

        public ImmutableImage resizeToRatio​(double targetRatio)

      • resizeToRatio

        public ImmutableImage resizeToRatio​(double targetRatio,
                                    Position position,
                                    java.awt.Color background)
        Resize will resize the canvas, it will not scale the image. This is like a "canvas resize" in Photoshop.

        Depending on ratio will increase either width or height.

        The position parameter determines how the original image will be positioned on the new canvas.

        Parameters:
        targetRatio - width divided by height
        position - where to position the original image after the canvas size change
        background - the background color if the canvas was enlarged
        Returns:
        a new Image that is the result of resizing the canvas.

      • resizeToHeight

        public ImmutableImage resizeToHeight​(int targetHeight)
        Resize will resize the canvas, it will not scale the image. This is like a "canvas resize" in Photoshop.
        Returns:
        a new Image that is the result of resizing the canvas.

      • resizeToHeight

        public ImmutableImage resizeToHeight​(int targetHeight,
                                     Position position,
                                     java.awt.Color background)
        Resize will resize the canvas, it will not scale the image. This is like a "canvas resize" in Photoshop.
        Parameters:
        position - where to position the original image after the canvas size change
        Returns:
        a new Image that is the result of resizing the canvas.

      • resizeToWidth

        public ImmutableImage resizeToWidth​(int targetWidth)
        Resize will resize the canvas, it will not scale the image. This is like a "canvas resize" in Photoshop.
        Returns:
        a new Image that is the result of resizing the canvas.

      • resizeToWidth

        public ImmutableImage resizeToWidth​(int targetWidth,
                                    Position position,
                                    java.awt.Color background)
        Resize will resize the canvas, it will not scale the image. This is like a "canvas resize" in Photoshop.
        Parameters:
        position - where to position the original image after the canvas size change
        Returns:
        a new Image that is the result of resizing the canvas.

      • rotateLeft

        public ImmutableImage rotateLeft()
        Returns a copy of this image rotated 90 degrees anti-clockwise (counter clockwise to US English speakers).

      • rotateRight

        public ImmutableImage rotateRight()
        Returns a copy of this image rotated 90 degrees clockwise.

      • pad

        public ImmutableImage pad​(int size,
                          java.awt.Color color)
        Creates a new image which is the result of this image padded with the given number of pixels on each edge.

        Eg, requesting a pad of 30 on an image of 250,300 will result in a new image with a canvas size of 310,360

        Parameters:
        size - the number of pixels to add on each edge
        color - the background of the padded area.
        Returns:
        A new image that is the result of the padding

      • padTo

        public ImmutableImage padTo​(int targetWidth,
                            int targetHeight)

      • padTo

        public ImmutableImage padTo​(int targetWidth,
                            int targetHeight,
                            java.awt.Color color)
        Creates a new ImmutableImage which is the result of this image padded to the canvas size specified. If this image is already larger than the specified dimensions then the sizes of the existing image will be used instead.

        Eg, requesting a pad of 200,200 on an image of 250,300 will result in keeping the 250,300.

        Eg2, requesting a pad of 300,300 on an image of 400,250 will result in the width staying at 400 and the height padded to 300.

        Parameters:
        targetWidth - the size of the output canvas width
        targetHeight - the size of the output canvas height
        color - the background of the padded area.
        Returns:
        A new image that is the result of the padding

      • padWith

        public ImmutableImage padWith​(int left,
                              int top,
                              int right,
                              int bottom)

      • padWith

        public ImmutableImage padWith​(int left,
                              int top,
                              int right,
                              int bottom,
                              java.awt.Color color)
        Creates a new ImmutableImage by adding the given number of columns/rows on left, top, right and bottom.
        Parameters:
        left - the number of columns/pixels to add on the left
        top - the number of rows/pixels to add to the top
        right - the number of columns/pixels to add on the right
        bottom - the number of rows/pixels to add to the bottom
        color - the background of the padded area.
        Returns:
        A new image that is the result of the padding operation.

      • padTop

        public ImmutableImage padTop​(int k,
                             java.awt.Color color)
        Creates a new Image by adding k amount of rows of pixels to the top. This is a convenience method for calling padWith(0,k,0,0,color).
        Parameters:
        k - the number of rows to pad by
        color - the color that should be used for the new rows
        Returns:
        the new Image

      • padBottom

        public ImmutableImage padBottom​(int k,
                                java.awt.Color color)
        Creates a new Image by adding k amount of rows of pixels to the bottom. This is a convenience method for calling padWith(0,0,0,k,color).
        Parameters:
        k - the number of rows to pad by
        color - the color that should be used for the new rows
        Returns:
        the new Image

      • padLeft

        public ImmutableImage padLeft​(int k)
        Creates a new Image by adding k columns of pixels to the left. This is a convenience method for calling padWith(k,0,0,0,Transparent).
        Parameters:
        k - the number of columns to pad by
        Returns:
        the new Image

      • padLeft

        public ImmutableImage padLeft​(int k,
                              java.awt.Color color)
        Creates a new Image by adding k columns of pixels to the left. This is a convenience method for calling padWith(k,0,0,0,color).
        Parameters:
        k - the number of columns to pad by
        color - the color that should be used for the new pixels
        Returns:
        the new Image

      • padRight

        public ImmutableImage padRight​(int k)
        Creates a new Image by adding k columns of pixels to the right. This is a convenience method for calling padWith(0,0,k,0,color).
        Parameters:
        k - the number of columns to pad by
        Returns:
        the new Image

      • padRight

        public ImmutableImage padRight​(int k,
                               java.awt.Color color)
        Creates a new Image by adding k columns of pixels to the right. This is a convenience method for calling padWith(0,0,k,0,color).
        Parameters:
        k - the number of columns to pad by
        color - the color that should be used for the new pixels
        Returns:
        the new Image

      • removeTransparency

        public ImmutableImage removeTransparency​(java.awt.Color color)
        Returns a new ImmutableImage with transparency replaced with the given color.

      • scaleToWidth

        public ImmutableImage scaleToWidth​(int targetWidth)
        Convenience method for scaleToWidth(targetWith, scaleMethod)

      • scaleToWidth

        public ImmutableImage scaleToWidth​(int targetWidth,
                                   ScaleMethod scaleMethod)
        Scale will resize the canvas and scale the image to match. This is like a "image resize" in Photoshop.

        scaleToWidth will scale the image so that the new image has a width that matches the given targetWidth and the height is determined by the original aspect ratio.

        Eg, an image of 200,300 with a scaleToWidth of 400 will result in a scaled image of 400,600

        Parameters:
        targetWidth - the target width
        scaleMethod - the type of scaling method to use.
        Returns:
        a new Image that is the result of scaling this image

      • scaleToHeight

        public ImmutableImage scaleToHeight​(int targetHeight)
        Convenience method for scaleToHeight(targetHeight, ScaleMethod.Bicubic)

      • scaleToHeight

        public ImmutableImage scaleToHeight​(int targetHeight,
                                    ScaleMethod scaleMethod)
        Convenience method for scaleToHeight(targetHeight, scaleMethod, true)

      • scaleToHeight

        public ImmutableImage scaleToHeight​(int targetHeight,
                                    ScaleMethod scaleMethod,
                                    boolean keepAspectRatio)
        Scale will resize the canvas and scale the image to match. This is like a "image resize" in Photoshop.

        scaleToHeight will scale the image so that the new image has a height that matches the given targetHeight.

        If keepAspectRatio is true, then the width will also be scaled so that the aspect ratio of the image does not change. If keepAspectRatio is false, then the width will stay the same.

        Eg, an image of 200,300 with a scaleToHeight of 450 and keepAspectRatio of true will result in a scaled image of 300,450 (because 300 to 450 is 1.5 and so 200 x 1.5 is 300).

        Parameters:
        targetHeight - the target height
        scaleMethod - the type of scaling method to use.
        keepAspectRatio - whether the width should also be scaled to keep the aspect ratio the same.
        Returns:
        a new Image that is the result of scaling this image

      • scaleHeightToRatio

        public ImmutableImage scaleHeightToRatio​(double ratio)

      • scale

        public ImmutableImage scale​(double scaleFactor,
                            ScaleMethod scaleMethod)
        Scale will resize the canvas and the image. This is like a "image resize" in Photoshop.
        Parameters:
        scaleFactor - the target increase or decrease. 1 is the same as original.
        scaleMethod - the type of scaling method to use.
        Returns:
        a new Image that is the result of scaling this image

      • scaleTo

        public ImmutableImage scaleTo​(int targetWidth,
                              int targetHeight)
        Convenience method for scaleTo(targetWidth, targetHeight, ScaleMethod.Bicubic);

      • scaleTo

        public ImmutableImage scaleTo​(int targetWidth,
                              int targetHeight,
                              ScaleMethod scaleMethod)
        Scale will resize both the canvas and the image. This is like a "image resize" in Photoshop.

        The size of the scaled instance are taken from the given width and height parameters.

        Parameters:
        targetWidth - the target width
        targetHeight - the target height
        scaleMethod - the type of scaling method to use. Defaults to SmoothScale
        Returns:
        a new Image that is the result of scaling this image

      • subpixelSubimage

        public ImmutableImage subpixelSubimage​(double x,
                                       double y,
                                       int subWidth,
                                       int subHeight)
        Extracts a subimage, but using subpixel interpolation.

      • subpixelSubimageCenteredAtPoint

        public ImmutableImage subpixelSubimageCenteredAtPoint​(double x,
                                                      double y,
                                                      double xRadius,
                                                      double yRadius)
        Extract a patch, centered at a subpixel point.

      • subimage

        public ImmutableImage subimage​(int x,
                               int y,
                               int w,
                               int h)
        Returns a new Image that is a subimage or region of the original image.
        Parameters:
        x - the start x coordinate
        y - the start y coordinate
        w - the width of the subimage
        h - the height of the subimage
        Returns:
        a new Image that is the subimage

      • subimage

        public ImmutableImage subimage​(java.awt.Rectangle rectangle)

      • takeLeft

        public ImmutableImage takeLeft​(int k)
        Returns a new Image which is the source image, but only keeping a max of k columns from the left.

      • takeRight

        public ImmutableImage takeRight​(int k)
        Returns a new Image which is the source image, but only keeping a max of k columns from the right.

      • takeTop

        public ImmutableImage takeTop​(int k)
        Returns a new Image which is the source image, but only keeping a max of k rows from the top.

      • takeBottom

        public ImmutableImage takeBottom​(int k)
        Returns a new Image which is the source image, but only keeping a max of k rows from the bottom.

      • translate

        public ImmutableImage translate​(int x,
                                int y)
        Returns an image that is the result of translating the image while keeping the same view window. Eg, if translating by 10,5 then all pixels will move 10 to the right, and 5 down. This would mean 10 columns and 5 rows of background added to the left and top.

        This method will use transparency for the color of the displaced pixels.

        Returns:
        a new Image with this image translated.

      • translate

        public ImmutableImage translate​(int x,
                                int y,
                                java.awt.Color bg)
        Returns an image that is the result of translating the image while keeping the same view window. Eg, if translating by 10,5 then all pixels will move 10 to the right, and 5 down. This would mean 10 columns and 5 rows of background added to the left and top.
        Returns:
        a new Image with this image translated.

      • trim

        public ImmutableImage trim​(int amount)
        Removes the given amount of pixels from each edge; like a crop operation.
        Parameters:
        amount - the number of pixels to trim from each edge
        Returns:
        a new Image with the dimensions width-trim*2, height-trim*2

      • trim

        public ImmutableImage trim​(int left,
                           int top,
                           int right,
                           int bottom)
        Removes the given amount of pixels from each edge; like a crop operation.
        Parameters:
        left - the number of pixels to trim from the left
        top - the number of pixels to trim from the top
        right - the number of pixels to trim from the right
        bottom - the number of pixels to trim from the bottom
        Returns:
        a new Image with the dimensions width-trim*2, height-trim*2

      • trimLeft

        public ImmutableImage trimLeft​(int k)
        Removes the specified amount of columns of pixels from the left side of the image. This is a convenience method for trim(k,0,0,0).
        Parameters:
        k - how many columns of pixels to remove
        Returns:
        a new image with k columns from the left removed

      • trimRight

        public ImmutableImage trimRight​(int k)
        Removes the specified amount of columns of pixels from the right side of the image. This is a convenience method for trim(0,0,k,0).
        Parameters:
        k - how many columns of pixels to remove
        Returns:
        a new image with k columns from the right removed

      • trimBottom

        public ImmutableImage trimBottom​(int k)
        Removes the specified amount of rows of pixels from the bottom of the image. This is a convenience method for trim(0,0,0,k).
        Parameters:
        k - how many rows of pixels to remove
        Returns:
        a new image with k rows from the bottom removed

      • trimTop

        public ImmutableImage trimTop​(int k)
        Removes the specified amount of rows of pixels from the top of the image. This is a convenience method for trim(0,k,0,0).
        Parameters:
        k - how many rows of pixels to remove
        Returns:
        a new image with k rows from the top removed

      • underlay

        public ImmutableImage underlay​(ImmutableImage underlayImage,
                               int x,
                               int y)
        Returns a new Image that is the result of overlaying this image over the supplied image. That is, the existing image ends up being "on top" of the image parameter. The x / y parameters determine where the (0,0) coordinate of the overlay should be placed.

        If the image to render exceeds the boundaries of the source image, then the excess pixels will be ignored.

        Returns:
        a new Image with the given image overlaid.

      • associateMetadata

        public ImmutableImage associateMetadata​(ImageMetadata metadata)
        Returns this image, with metadata attached.

        Both the original and the new image will share a buffer

      • zoom

        public ImmutableImage zoom​(double factor,
                           ScaleMethod method)
        Returns a new image that is the result of scaling this image but without changing the canvas size.

        This can be thought of as zooming in on a camera - the viewpane does not change but the image increases in size with the outer columns/rows being dropped as required.

        Parameters:
        factor - how much to zoom by
        method - how to apply the scaling method
        Returns:
        the zoomed image

      • map

        public ImmutableImage map​(java.util.function.Function<Pixel,​java.awt.Color> mapper)
        Maps the pixels of this image into another image by applying the given function to each pixel.

        The function accepts a pixel being transformed and returns a new (or same) color.

        Parameters:
        mapper - the function to transform pixel x,y with existing value p into new pixel value p' (p prime)

      • toCanvas

        public Canvas toCanvas()
        Returns a Canvas that wraps this image.

      • transform

        public ImmutableImage transform​(Transform transform)
                         throws java.io.IOException
        Throws:
        java.io.IOException