Package ca.cgjennings.graphics.filters

Class TrimFilter

  • All Implemented Interfaces:
    java.awt.image.BufferedImageOp
    public final class TrimFilter
extends AbstractImageFilter
    Automatically crops an image by trimming off edges that fail to satisfy a test. The test is specified by a mask and a condition. Edges are tested one row or column at a time, starting at the image edges and working towards the image center. Each row or column is checked for any pixel whose ARGB value fails to satisfy the statement pixelARGB & mask == condition. Once any pixel in a row or column fails to satisfy the test, trimming along that edge stops.

    Some example mask and condition values
    Mask Condition Effect
    0xff000000 0x00000000 Trim transparent (alpha=0) edges
    0xffffffff 0xffffffff Trim solid white edges
    0xffffffff 0xff000000 Trim solid black edges
    0x00ffffff 0x00RRGGBB Trim edges with colour RRGGBB, ignoring transparency

    Since the purpose of this filter is to resize an image in a way that cannot be known before the filter is applied, it behaves differently from a typical filter. The destination image parameter is always ignored. If the trimmed image is smaller than the source image, a new image is created at the trimmed size and returned. If no trimming is required, the source image is returned unchanged.

    In-place filtering: This filter may or may not be applied in place; see previous paragraph.

    Since:
    3.0
    Author:
    Chris Jennings

    • Constructor Detail

      • TrimFilter

        public TrimFilter()
        Creates a new filter that trims fully transparent edges off of images. That is, with a mask of 0xff000000 and a condition of 0xff000000.

      • TrimFilter

        public TrimFilter​(int mask,
                  int condition)
        Creates a new trim filter with the specified mask and condition.
        Parameters:
        mask - the mask value for trim testing
        condition - the value that masked edges must satisfy to be trimmed

    • Method Detail

      • filter

        public java.awt.image.BufferedImage filter​(java.awt.image.BufferedImage sourceImage,
                                           java.awt.image.BufferedImage ignoredDestination)
        Filters the image, returning an image with trimmable edges cropped off. The destination image is ignored, as described in the class description. If the trim operation would result in an empty image, the filter returns null.
        Parameters:
        sourceImage - the image to trim
        ignoredDestination - this parameter is ignored
        Returns:
        a new, trimmed image; or the source image if no edges are trimmed; or null if the entire image is trimmed