org.appng.tools.image

## Class ImageProcessor

- java.lang.Object
- - org.appng.tools.image.ImageProcessor

-     public class ImageProcessor
      extends Object

  Utility class for converting images using the convert-command of ImageMagick via the API provided by http://im4java.sourceforge.net/
  Author:
    Matthias Herlitzius

- - ### Constructor Summary

    Constructors
    Constructor and Description
    `ImageProcessor(File sourceFile, File targetFile)` Creates a new `ImageProcessor`
    `ImageProcessor(File sourceFile, File targetFile, boolean checkMagicBytes)` Creates a new `ImageProcessor`
    `ImageProcessor(File imageMagickPath, File sourceFile, File targetFile)` Creates a new `ImageProcessor`
    `ImageProcessor(File imageMagickPath, File sourceFile, File targetFile, boolean checkMagicBytes)` Creates a new `ImageProcessor`

  - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `ImageProcessor` | `autoCrop(int croppingWidth, int croppingHeight, int originalWidth, int originalHeight)` Automatically crops the original image to the required size.
    `ImageProcessor` | `autoCrop(int croppingWidth, int croppingHeight, int originalWidth, int originalHeight, int croppingOffsetX, int croppingOffsetY)` Automatically crops the original image to the required size.
    `ImageProcessor` | `crop(int targetWidth, int targetHeight, int offsetWidth, int offsetHeight)` Adds a crop-option to the convert-command.
    `ImageProcessor` | `fitToHeight(Integer maxHeight)` Fits the image to the given maximum height using `resize(int, int)`.
    `ImageProcessor` | `fitToWidth(Integer maxWidth)` Fits the image to the given maximum width using `resize(int, int)`.
    `ImageProcessor` | `fitToWidthAndHeight(int maxwidth, int maxHeight)` Fits the image to the given maximum width and height using `resize(int, int)`.
    `File` | `getImage()` Executes the convert-command with all the previously applied options and returns the target-file this `ImageProcessor` was created with.
    `ImageMetaData` | `getMetaData()` Retrieves the `ImageMetaData` for the source-file.
    `org.im4java.core.IMOperation` | `getOp()`
    `static boolean` | `isImageMagickPresent(File imageMagickPath)` Checks whether the ImageMagick convert-command is available.
    `ImageProcessor` | `quality(double quality)` Adds a quality-option to the convert-command.
    `ImageProcessor` | `resize(int targetWidth, int targetHeight)` Adds a resize-option to the convert-command.
    `ImageProcessor` | `resize(int targetWidth, int targetHeight, boolean scaleUp)` Adds a resize-option to the convert-command.
    `ImageProcessor` | `rotate(int degrees)` Adds a rotate-option to the convert-command.
    `static void` | `setGlobalSearchPath(File imageMagickPath)` Sets the global search path to the convert-command
    `ImageProcessor` | `strip()` Adds a strip-option to the convert-command.

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Constructor Detail

    - #### ImageProcessor

          public ImageProcessor(File imageMagickPath,
                                File sourceFile,
                                File targetFile)

      Creates a new `ImageProcessor`
      Parameters:
        `imageMagickPath` - the path to the convert-command, if `null` the system path is being used
        `sourceFile` - the source file
        `targetFile` - the target file

    - #### ImageProcessor

          public ImageProcessor(File imageMagickPath,
                                File sourceFile,
                                File targetFile,
                                boolean checkMagicBytes)
                         throws IOException

      Creates a new `ImageProcessor`
      Parameters:
        `imageMagickPath` - the path to the convert-command, if `null` the system path is being used
        `sourceFile` - the source file
        `targetFile` - the target file
        `checkMagicBytes` - whether or not it should be checked that the source file's extension matches it's content type, using magic byte detection
      Throws:
        `IOException` - if `checkMagicBytes` is `true` and the source file's extension does not match it's content type determined by magic byte detection

    - #### ImageProcessor

          public ImageProcessor(File sourceFile,
                                File targetFile)

      Creates a new `ImageProcessor`
      Parameters:
        `sourceFile` - the source file
        `targetFile` - the target file

    - #### ImageProcessor

          public ImageProcessor(File sourceFile,
                                File targetFile,
                                boolean checkMagicBytes)
                         throws IOException

      Creates a new `ImageProcessor`
      Parameters:
        `sourceFile` - the source file
        `targetFile` - the target file
        `checkMagicBytes` - whether or not it should be checked that the source file's extension matches it's content type, using magic byte detection
      Throws:
        `IOException` - if `checkMagicBytes` is `true` and the source file's extension does not match it's content type determined by magic byte detection

  - ### Method Detail

    - #### isImageMagickPresent

          public static boolean isImageMagickPresent(File imageMagickPath)

      Checks whether the ImageMagick convert-command is available.
      Parameters:
        `imageMagickPath` - the path to the convert-command, if `null` the system path is being used
      Returns:
        `true` if the convert-command is available, `false` otherwise
      See Also:
        `setGlobalSearchPath(File)`

    - #### setGlobalSearchPath

          public static void setGlobalSearchPath(File imageMagickPath)

      Sets the global search path to the convert-command
      Parameters:
        `imageMagickPath` - the path to the convert-command, may not be null

    - #### getMetaData

          public ImageMetaData getMetaData()
                                    throws IOException

      Retrieves the `ImageMetaData` for the source-file.
      Returns:
        the `ImageMetaData`
      Throws:
        `IOException` - if the source-file could not be read

    - #### rotate

          public ImageProcessor rotate(int degrees)

      Adds a rotate-option to the convert-command.
      Parameters:
        `degrees` - the degrees
      Returns:
        this `ImageProcessor`

    - #### resize

          public ImageProcessor resize(int targetWidth,
                                       int targetHeight,
                                       boolean scaleUp)

      Adds a resize-option to the convert-command. Aspect ratio may get lost, the image may be upscaled.
      Parameters:
        `targetWidth` - the target width, must be greater 0
        `targetHeight` - the target height, must be greater 0
        `scaleUp` - set to `true` if the image should be scaled up (in case its dimensions are smaller than the desired ones).
      Returns:
        this `ImageProcessor`
      See Also:
        `resize(int, int)`

    - #### resize

          public ImageProcessor resize(int targetWidth,
                                       int targetHeight)

      Adds a resize-option to the convert-command. Aspect ratio may get lost, the image may be upscaled.
      Parameters:
        `targetWidth` - the target width, must be greater 0
        `targetHeight` - the target height, must be greater 0
      Returns:
        this `ImageProcessor`

    - #### quality

          public ImageProcessor quality(double quality)

      Adds a quality-option to the convert-command.
      Parameters:
        `quality` - the quality
      Returns:
        this `ImageProcessor`

    - #### strip

          public ImageProcessor strip()

      Adds a strip-option to the convert-command. This removes all comments and profiles from the image.
      Returns:
        this `ImageProcessor`

    - #### autoCrop

          public ImageProcessor autoCrop(int croppingWidth,
                                         int croppingHeight,
                                         int originalWidth,
                                         int originalHeight)

      Automatically crops the original image to the required size.
      Parameters:
        `croppingWidth` - The target width of the image section.
        `croppingHeight` - The target height of the image section.
        `originalWidth` - The original width of the image.
        `originalHeight` - The original height of the image.
      Returns:
        this `ImageProcessor`
      See Also:
        `autoCrop(int, int, int, int, int, int)`

    - #### autoCrop

          public ImageProcessor autoCrop(int croppingWidth,
                                         int croppingHeight,
                                         int originalWidth,
                                         int originalHeight,
                                         int croppingOffsetX,
                                         int croppingOffsetY)

      Automatically crops the original image to the required size.

      This is done in two steps. First, a section with the desired aspect ratio is being cropped from the original image. Second, this image section is resized to the desired size.

      Example: `autoCrop(50, 50, 100, 200, 0, 0)` will first crop a squared section from 0,50 to 100,150 and the resize this section to 50x50.

           0,0   _________ 100,0
                |         |
                |         |
                |         |
                |         |
           0,50 |_________|100,50
                |         |
                | cropped |
                |         |
                | section |
                |_________|
           0,150|         |100,150
                |         |
                |         |
                |         |
                |_________|
           0,200           100,200

      Note that the original aspect ratio of the original image might get lost.

      Parameters:
        `croppingWidth` - The target width of the image section.
        `croppingHeight` - The target height of the image section.
        `originalWidth` - The original width of the image.
        `originalHeight` - The original height of the image.
        `croppingOffsetX` - The X offset for the image section based on the original image.
        `croppingOffsetY` - The Y offset for the image section based on the original image.
      Returns:
        this `ImageProcessor`
      See Also:
        `crop(int, int, int, int)`, `resize(int, int)`

    - #### crop

          public ImageProcessor crop(int targetWidth,
                                     int targetHeight,
                                     int offsetWidth,
                                     int offsetHeight)

      Adds a crop-option to the convert-command.
      Parameters:
        `targetWidth` - the width of the cutting
        `targetHeight` - the height of the cutting
        `offsetWidth` - the width-offset to start cropping at.
        `offsetHeight` - the height-offset to start cropping at.
      Returns:
        this `ImageProcessor`

    - #### getImage

          public File getImage()
                        throws IOException

      Executes the convert-command with all the previously applied options and returns the target-file this `ImageProcessor` was created with.
      Returns:
        the target-file this `ImageProcessor` was created with
      Throws:
        `IOException` - if something goes wrong while executing the convert-command

    - #### fitToWidthAndHeight

          public ImageProcessor fitToWidthAndHeight(int maxwidth,
                                                    int maxHeight)
                                             throws IOException

      Fits the image to the given maximum width and height using `resize(int, int)`. No upscaling is done here, the aspect ratio is being kept.
      Parameters:
        `maxwidth` - the maximum width of the image
        `maxHeight` - the maximum height of the image
      Returns:
        this `ImageProcessor`
      Throws:
        `IOException` - if no `ImageMetaData` could be obtained from the source file
      See Also:
        `resize(int, int)`

    - #### fitToWidth

          public ImageProcessor fitToWidth(Integer maxWidth)
                                    throws IOException

      Fits the image to the given maximum width using `resize(int, int)`. No upscaling is done here, the aspect ratio is being kept.
      Parameters:
        `maxWidth` - the maximum width of the image
      Returns:
        this `ImageProcessor`
      Throws:
        `IOException` - if no `ImageMetaData` could be obtained from the source file
      See Also:
        `resize(int, int)`

    - #### fitToHeight

          public ImageProcessor fitToHeight(Integer maxHeight)
                                     throws IOException

      Fits the image to the given maximum height using `resize(int, int)`. No upscaling is done here, the aspect ratio is being kept.
      Parameters:
        `maxHeight` - the maximum height of the image
      Returns:
        this `ImageProcessor`
      Throws:
        `IOException` - if no `ImageMetaData` could be obtained from the source file
      See Also:
        `resize(int, int)`

    - #### getOp

          public org.im4java.core.IMOperation getOp()

Copyright © 2011–2023 aiticon GmbH. All rights reserved.