Package org.opencms.loader

Class CmsImageScaler

  • public class CmsImageScaler
extends java.lang.Object
    Creates scaled images, acting as it's own parameter container.

    Since:
    6.2.0

    • Field Summary

      Fields 
      Modifier and Type Field Description
      static java.lang.String COLOR_TRANSPARENT
      The name of the transparent color (for the background image).
      static java.lang.String FILTER_GRAYSCALE
      The name of the grayscale image filter.
      static java.lang.String FILTER_SHADOW
      The name of the shadow image filter.
      static java.util.List<java.lang.String> FILTERS
      The supported image filter names.
      protected static org.apache.commons.logging.Log LOG
      The log object for this class.
      static java.lang.String PARAM_SCALE
      The (optional) parameter used for sending the scale information of an image in the http request.
      static int SCALE_DEFAULT_MAX_BLUR_SIZE
      The default maximum image size (width * height) to apply image blurring when down scaling (setting this to high may case "out of memory" errors).
      static int SCALE_DEFAULT_MAX_SIZE
      The default maximum image size (width or height) to allow when up or down scaling an image using request parameters.
      static java.lang.String SCALE_PARAM_COLOR
      The scaler parameter to indicate the requested image background color (if required).
      static java.lang.String SCALE_PARAM_CROP_HEIGHT
      The scaler parameter to indicate crop height.
      static java.lang.String SCALE_PARAM_CROP_WIDTH
      The scaler parameter to indicate crop width.
      static java.lang.String SCALE_PARAM_CROP_X
      The scaler parameter to indicate crop X coordinate.
      static java.lang.String SCALE_PARAM_CROP_Y
      The scaler parameter to indicate crop Y coordinate.
      static java.lang.String SCALE_PARAM_FILTER
      The scaler parameter to indicate the requested image filter.
      static java.lang.String SCALE_PARAM_HEIGHT
      The scaler parameter to indicate the requested image height.
      static java.lang.String SCALE_PARAM_POS
      The scaler parameter to indicate the requested image position (if required).
      static java.lang.String SCALE_PARAM_QUALITY
      The scaler parameter to indicate to requested image save quality in percent (if applicable, for example used with JPEG images).
      static java.lang.String SCALE_PARAM_RENDERMODE
      The scaler parameter to indicate to requested RenderingHints settings.
      static java.lang.String SCALE_PARAM_TYPE
      The scaler parameter to indicate the requested scale type.
      static java.lang.String SCALE_PARAM_WIDTH
      The scaler parameter to indicate the requested image width.

    • Constructor Summary

      Constructors 
      Constructor Description
      CmsImageScaler()
      Creates a new, empty image scaler object.
      CmsImageScaler​(byte[] content, java.lang.String rootPath)
      Creates a new image scaler initialized with the height and width of the given image contained in the byte array.
      CmsImageScaler​(int width, int height)
      Creates an image scaler with manually set width and height.
      CmsImageScaler​(java.lang.String parameters)
      Creates a new image scaler based on the given parameter String.
      CmsImageScaler​(javax.servlet.http.HttpServletRequest request, int maxScaleSize, int maxBlurSize)
      Creates a new image scaler based on the given HTTP request.
      CmsImageScaler​(CmsObject cms, CmsResource res)
      Creates a new image scaler by reading the property CmsPropertyDefinition.PROPERTY_IMAGE_SIZE from the given resource.
      CmsImageScaler​(CmsImageScaler base, int width, int height)
      Creates a new image scaler based on the given base scaler and the given width and height.

    • Method Summary

      All Methods Static Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      void addFilter​(java.lang.String filter)
      Adds a filter name to the list of filters that should be applied to the image.
      static int[] calculateDimension​(int sourceWidth, int sourceHeight, int boxWidth, int boxHeight)
      Calculate the width and height of a source image if scaled inside the given box.
      java.lang.Object clone()  
      java.awt.Color getColor()
      Returns the color.
      java.lang.String getColorString()
      Returns the color as a String.
      int getCropHeight()
      Returns the crop area height.
      CmsImageScaler getCropScaler​(CmsImageScaler target)
      Returns a new image scaler that is a cropped rescaler from this cropped scaler size to the given target scaler size.
      int getCropWidth()
      Returns the crop area width.
      int getCropX()
      Returns the crop area X start coordinate.
      int getCropY()
      Returns the crop area Y start coordinate.
      CmsImageScaler getDownScaler​(CmsImageScaler downScaler)
      Returns a new image scaler that is a down scale from the size of this scaler to the given scaler size.
      java.util.List<java.lang.String> getFilters()
      Returns the list of image filter names (Strings) to be applied to the image.
      java.lang.String getFiltersString()
      Returns the list of image filter names (Strings) to be applied to the image as a String.
      CmsPoint getFocalPoint()
      Gets the focal point, or null if it is not set.
      int getHeight()
      Returns the height.
      static java.awt.Dimension getImageDimensions​(java.lang.String path, byte[] content)
      Gets image dimensions for given file
      java.lang.String getImageType​(java.lang.String filename)
      Returns the image type from the given file name based on the file suffix (extension) and the available image writers.
      int getMaxBlurSize()
      Returns the maximum image size (width * height) to apply image blurring when down scaling images.
      int getMaxHeight()
      Returns the maximum target height (for scale type '5').
      int getMaxWidth()
      Returns the maximum target width (for scale type '5').
      int getPixelCount()
      Returns the image pixel count, that is the image with multiplied by the image height.
      int getPosition()
      Returns the position.
      int getQuality()
      Returns the image saving quality in percent (0 - 100).
      int getRenderMode()
      Returns the image rendering mode constant.
      java.lang.String getRequestParam()
      Creates a request parameter configured with the values from this image scaler, also appends a '?' char as a prefix so that this may be directly appended to an image URL.
      CmsImageScaler getReScaler​(CmsImageScaler target)
      Returns a new image scaler that is a rescaler from this scaler size to the given target scaler size.
      int getType()
      Returns the type.
      int getWidth()
      Returns the width.
      CmsImageScaler getWidthScaler​(CmsImageScaler downScaler)
      Returns a new image scaler that is a width based down scale from the size of this scaler to the given scaler size.
      int hashCode()  
      boolean isCropping()
      Returns true if all required parameters for image cropping are available.
      boolean isDownScaleRequired​(CmsImageScaler downScaler)
      Returns true if this image scaler must be down scaled when compared to the given "down scale" image scaler.
      boolean isOriginalScaler()
      Returns true if the image scaler was only used to read image properties from the VFS.
      boolean isValid()
      Returns true if all required parameters are available.
      void parseParameters​(java.lang.String parameters)
      Parses the given parameters and sets the internal scaler variables accordingly.
      byte[] scaleImage​(byte[] content, java.awt.image.BufferedImage image, java.lang.String rootPath)
      Returns a scaled version of the given image byte content according this image scalers parameters.
      byte[] scaleImage​(byte[] content, java.lang.String rootPath)
      Returns a scaled version of the given image byte content according this image scalers parameters.
      byte[] scaleImage​(CmsFile file)
      Returns a scaled version of the given image file according this image scalers parameters.
      void setColor​(java.awt.Color color)
      Sets the color.
      void setColor​(java.lang.String value)
      Sets the color as a String.
      void setCropArea​(int x, int y, int width, int height)
      Sets the image crop area.
      void setFilters​(java.lang.String value)
      Sets the list of filters as a String.
      void setFocalPoint​(CmsPoint point)
      Sets the focal point.
      void setHeight​(int height)
      Sets the height.
      void setMaxBlurSize​(int maxBlurSize)
      Sets the maximum image size (width * height) to apply image blurring when downscaling images.
      void setMaxHeight​(int maxHeight)
      Sets the maximum target height (for scale type '5').
      void setMaxWidth​(int maxWidth)
      Sets the maximum target width (for scale type '5').
      void setPosition​(int position)
      Sets the scale position.
      void setQuality​(int quality)
      Sets the image saving quality in percent.
      void setRenderMode​(int renderMode)
      Sets the image rendering mode constant.
      void setType​(int type)
      Sets the scale type.
      void setWidth​(int width)
      Sets the width.
      java.lang.String toRequestParam()
      Creates a request parameter configured with the values from this image scaler, also appends a '?' char as a prefix so that this may be directly appended to an image URL.
      java.lang.String toString()  

      • Methods inherited from class java.lang.Object

        equals, finalize, getClass, notify, notifyAll, wait, wait, wait

    • Constructor Detail

      • CmsImageScaler

        public CmsImageScaler()
        Creates a new, empty image scaler object.

      • CmsImageScaler

        public CmsImageScaler​(byte[] content,
                      java.lang.String rootPath)
        Creates a new image scaler initialized with the height and width of the given image contained in the byte array.

        Please note:The image itself is not stored in the scaler, only the width and height dimensions of the image. To actually scale an image, you need to use scaleImage(CmsFile). This constructor is commonly used only to extract the image dimensions, for example when creating a String value for the CmsPropertyDefinition.PROPERTY_IMAGE_SIZE property.

        In case the byte array can not be decoded to an image, or in case of other errors, isValid() will return false.

        Parameters:
        content - the image to calculate the dimensions for
        rootPath - the root path of the resource (for error logging)

      • CmsImageScaler

        public CmsImageScaler​(CmsImageScaler base,
                      int width,
                      int height)
        Creates a new image scaler based on the given base scaler and the given width and height.

        Parameters:
        base - the base scaler to initialize the values with
        width - the width to set for this scaler
        height - the height to set for this scaler

      • CmsImageScaler

        public CmsImageScaler​(javax.servlet.http.HttpServletRequest request,
                      int maxScaleSize,
                      int maxBlurSize)
        Creates a new image scaler based on the given HTTP request.

        The maximum scale size is checked in order to prevent DOS attacks. Without this, it would be possible to request arbitrary huge images with a simple GET request, which would result in Out-Of-Memory errors if the image is just requested large enough.

        The maximum blur size is checked since this operation is know to also cause memory issues with large images. If the original image is larger then this, no blur is applied before scaling down, which will result in a less optimal but still usable scale result.

        Parameters:
        request - the HTTP request to read the parameters from
        maxScaleSize - the maximum scale size (width or height) for the image
        maxBlurSize - the maximum size of the image (width * height) to apply blur

      • CmsImageScaler

        public CmsImageScaler​(int width,
                      int height)
        Creates an image scaler with manually set width and height.
        Parameters:
        width - the width
        height - the height

      • CmsImageScaler

        public CmsImageScaler​(java.lang.String parameters)
        Creates a new image scaler based on the given parameter String.

        Parameters:
        parameters - the scale parameters to use

    • Method Detail

      • calculateDimension

        public static int[] calculateDimension​(int sourceWidth,
                                       int sourceHeight,
                                       int boxWidth,
                                       int boxHeight)
        Calculate the width and height of a source image if scaled inside the given box.

        Parameters:
        sourceWidth - the width of the source image
        sourceHeight - the height of the source image
        boxWidth - the width of the target box
        boxHeight - the height of the target box
        Returns:
        the width [0] and height [1] of the source image if scaled inside the given box

      • getImageDimensions

        public static java.awt.Dimension getImageDimensions​(java.lang.String path,
                                                    byte[] content)
                                             throws java.io.IOException
        Gets image dimensions for given file
        Parameters:
        imgFile - image file
        Returns:
        dimensions of image
        Throws:
        java.io.IOException - if the file is not a known image

      • addFilter

        public void addFilter​(java.lang.String filter)
        Adds a filter name to the list of filters that should be applied to the image.

        Parameters:
        filter - the filter name to add

      • clone

        public java.lang.Object clone()
        Overrides:
        clone in class java.lang.Object
        See Also:
        Object.clone()

      • getColor

        public java.awt.Color getColor()
        Returns the color.

        Returns:
        the color

      • getColorString

        public java.lang.String getColorString()
        Returns the color as a String.

        Returns:
        the color as a String

      • getDownScaler

        public CmsImageScaler getDownScaler​(CmsImageScaler downScaler)
        Returns a new image scaler that is a down scale from the size of this scaler to the given scaler size.

        If no down scale from this to the given scaler is required according to isDownScaleRequired(CmsImageScaler), then null is returned.

        Parameters:
        downScaler - the image scaler that holds the down scaled target image dimensions
        Returns:
        a new image scaler that is a down scale from the size of this scaler to the given target scaler size, or null

      • getFilters

        public java.util.List<java.lang.String> getFilters()
        Returns the list of image filter names (Strings) to be applied to the image.

        Returns:
        the list of image filter names (Strings) to be applied to the image

      • getFiltersString

        public java.lang.String getFiltersString()
        Returns the list of image filter names (Strings) to be applied to the image as a String.

        Returns:
        the list of image filter names (Strings) to be applied to the image as a String

      • getFocalPoint

        public CmsPoint getFocalPoint()
        Gets the focal point, or null if it is not set.

        Returns:
        the focal point

      • getHeight

        public int getHeight()
        Returns the height.

        Returns:
        the height

      • getImageType

        public java.lang.String getImageType​(java.lang.String filename)
        Returns the image type from the given file name based on the file suffix (extension) and the available image writers.

        For example, for the file name "opencms.gif" the type is GIF, for "opencms.jpg" is is "JPEG" etc.

        In case the input filename has no suffix, or there is no known image writer for the format defined by the suffix, null is returned.

        Any non-null result can be used if an image type input value is required.

        Parameters:
        filename - the file name to get the type for
        Returns:
        the image type from the given file name based on the suffix and the available image writers, or null if no image writer is available for the format

      • getMaxBlurSize

        public int getMaxBlurSize()
        Returns the maximum image size (width * height) to apply image blurring when down scaling images.

        Image blurring is required to achieve the best results for down scale operations when the target image size is 2 times or more smaller then the original image size. This parameter controls the maximum size (width * height) of an image that is blurred before it is down scaled. If the image is larger, no blurring is done. Image blurring is an expensive operation in both CPU usage and memory consumption. Setting the blur size to large may case "out of memory" errors.

        Returns:
        the maximum image size (width * height) to apply image blurring when down scaling images

      • getMaxHeight

        public int getMaxHeight()
        Returns the maximum target height (for scale type '5').

        Returns:
        the maximum target height (for scale type '5')

      • getMaxWidth

        public int getMaxWidth()
        Returns the maximum target width (for scale type '5').

        Returns:
        the maximum target width (for scale type '5').

      • getPixelCount

        public int getPixelCount()
        Returns the image pixel count, that is the image with multiplied by the image height.

        If this scaler is not valid (see isValid()) the result is undefined.

        Returns:
        the image pixel count, that is the image with multiplied by the image height

      • getPosition

        public int getPosition()
        Returns the position.

        Returns:
        the position

      • getQuality

        public int getQuality()
        Returns the image saving quality in percent (0 - 100).

        This is used only if applicable, for example when saving JPEG images.

        Returns:
        the image saving quality in percent

      • getRenderMode

        public int getRenderMode()
        Returns the image rendering mode constant.

        Possible values are:

        Simapi.RENDER_QUALITY (default)
        Use best possible image processing - this may be slow sometimes.
        Simapi.RENDER_SPEED
        Fastest image processing but worse results - use this for thumbnails or where speed is more important then quality.
        Simapi.RENDER_MEDIUM
        Use default rendering hints from JVM - not recommended since it's almost as slow as the Simapi.RENDER_QUALITY mode.
        Returns:
        the image rendering mode constant

      • getRequestParam

        public java.lang.String getRequestParam()
        Creates a request parameter configured with the values from this image scaler, also appends a '?' char as a prefix so that this may be directly appended to an image URL.

        This can be appended to an image request in order to apply image scaling parameters.

        Returns:
        a request parameter configured with the values from this image scaler
        See Also:
        toRequestParam()

      • getReScaler

        public CmsImageScaler getReScaler​(CmsImageScaler target)
        Returns a new image scaler that is a rescaler from this scaler size to the given target scaler size.

        The height of the target image is calculated in proportion to the original image width. If the width of the the original image is not known, the target image width is calculated in proportion to the original image height.

        Parameters:
        target - the image scaler that holds the target image dimensions
        Returns:
        a new image scaler that is a rescaler from the this scaler size to the given target scaler size

      • getType

        public int getType()
        Returns the type.

        Possible values are:

        0 (default): Scale to exact target size with background padding
        • enlarge image to fit in target size (if required)
        • reduce image to fit in target size (if required)
        • keep image aspect ratio / proportions intact
        • fill up with bgcolor to reach exact target size
        • fit full image inside target size (only applies if reduced)
        1: Thumbnail generation mode (like 0 but no image enlargement)
        • dont't enlarge image
        • reduce image to fit in target size (if required)
        • keep image aspect ratio / proportions intact
        • fill up with bgcolor to reach exact target size
        • fit full image inside target size (only applies if reduced)
        2: Scale to exact target size, crop what does not fit
        • enlarge image to fit in target size (if required)
        • reduce image to fit in target size (if required)
        • keep image aspect ratio / proportions intact
        • fit full image inside target size (crop what does not fit)
        3: Scale and keep image proportions, target size variable
        • enlarge image to fit in target size (if required)
        • reduce image to fit in target size (if required)
        • keep image aspect ratio / proportions intact
        • scaled image will not be padded or cropped, so target size is likely not the exact requested size
        4: Don't keep image proportions, use exact target size
        • enlarge image to fit in target size (if required)
        • reduce image to fit in target size (if required)
        • don't keep image aspect ratio / proportions intact
        • the image will be scaled exactly to the given target size and likely will be loose proportions
        5: Scale and keep image proportions without enlargement, target size variable with optional max width and height
        • dont't enlarge image
        • reduce image to fit in target size (if required)
        • keep image aspect ratio / proportions intact
        • best fit into target width / height _OR_ width / maxHeight _OR_ maxWidth / height
        • scaled image will not be padded or cropped, so target size is likely not the exact requested size
        6: Crop around point: Use exact pixels
        • This type only applies for image crop operations (full crop parameters must be provided).
        • In this case the crop coordinates x, y are treated as a point in the middle of width, height.
        • With this type, the pixels from the source image are used 1:1 for the target image.
        7: Crop around point: Use pixels for target size, get maximum out of image
        • This type only applies for image crop operations (full crop parameters must be provided).
        • In this case the crop coordinates x, y are treated as a point in the middle of width, height.
        • With this type, as much as possible from the source image is fitted in the target image size.
        8: Focal point mode.

        If a focal point is set on this scaler, this mode will first crop a region defined by cx,cy,cw,ch from the original image, then select the largest region of the aspect ratio defined by w/h in the cropped image containing the focal point, and finally scale that region to size w x h.

        Returns:
        the type

      • getWidth

        public int getWidth()
        Returns the width.

        Returns:
        the width

      • getWidthScaler

        public CmsImageScaler getWidthScaler​(CmsImageScaler downScaler)
        Returns a new image scaler that is a width based down scale from the size of this scaler to the given scaler size.

        If no down scale from this to the given scaler is required because the width of this scaler is not larger than the target width, then the image dimensions of this scaler are unchanged in the result scaler. No up scaling is done!

        Parameters:
        downScaler - the image scaler that holds the down scaled target image dimensions
        Returns:
        a new image scaler that is a down scale from the size of this scaler to the given target scaler size

      • hashCode

        public int hashCode()
        Overrides:
        hashCode in class java.lang.Object
        See Also:
        Object.hashCode()

      • isCropping

        public boolean isCropping()
        Returns true if all required parameters for image cropping are available.

        Required parameters are "cx","cy" (x, y start coordinate), and "ch","cw" (crop height and width).

        Returns:
        true if all required cropping parameters are available

      • isDownScaleRequired

        public boolean isDownScaleRequired​(CmsImageScaler downScaler)
        Returns true if this image scaler must be down scaled when compared to the given "down scale" image scaler.

        If either this scaler or the given downScaler is invalid according to isValid(), then false is returned.

        The use case: this scaler represents an image (that is contains width and height of an image). The downScaler represents the maximum wanted image. The scalers are compared and if the image represented by this scaler is too large, true is returned. Image orientation is ignored, so for example an image with 600x800 pixel will NOT be down scaled if the target size is 800x600 but kept unchanged.

        Parameters:
        downScaler - the down scaler to compare this image scaler with
        Returns:
        true if this image scaler must be down scaled when compared to the given "down scale" image scaler

      • isOriginalScaler

        public boolean isOriginalScaler()
        Returns true if the image scaler was only used to read image properties from the VFS.
        Returns:
        true if the image scaler was only used to read image properties from the VFS

      • isValid

        public boolean isValid()
        Returns true if all required parameters are available.

        Required parameters are "h" (height), and "w" (width).

        Returns:
        true if all required parameters are available

      • parseParameters

        public void parseParameters​(java.lang.String parameters)
        Parses the given parameters and sets the internal scaler variables accordingly.

        The parameter String must have a format like "h:100,w:200,t:1", that is a comma separated list of attributes followed by a colon ":", followed by a value. As possible attributes, use the constants from this class that start with SCALE_PARAM for example SCALE_PARAM_HEIGHT or SCALE_PARAM_WIDTH.

        Parameters:
        parameters - the parameters to parse

      • scaleImage

        public byte[] scaleImage​(byte[] content,
                         java.awt.image.BufferedImage image,
                         java.lang.String rootPath)
        Returns a scaled version of the given image byte content according this image scalers parameters.

        Parameters:
        content - the image byte content to scale
        image - if this is set, this image will be used as base for the scaling rather than a new image read from the content byte array
        rootPath - the root path of the image file in the VFS
        Returns:
        a scaled version of the given image byte content according to the provided scaler parameters

      • scaleImage

        public byte[] scaleImage​(byte[] content,
                         java.lang.String rootPath)
        Returns a scaled version of the given image byte content according this image scalers parameters.

        Parameters:
        content - the image byte content to scale
        rootPath - the root path of the image file in the VFS
        Returns:
        a scaled version of the given image byte content according to the provided scaler parameters

      • scaleImage

        public byte[] scaleImage​(CmsFile file)
        Returns a scaled version of the given image file according this image scalers parameters.

        Parameters:
        file - the image file to scale
        Returns:
        a scaled version of the given image file according to the provided scaler parameters

      • setColor

        public void setColor​(java.awt.Color color)
        Sets the color.

        Parameters:
        color - the color to set

      • setColor

        public void setColor​(java.lang.String value)
        Sets the color as a String.

        Parameters:
        value - the color to set

      • setCropArea

        public void setCropArea​(int x,
                        int y,
                        int width,
                        int height)
        Sets the image crop area.

        Parameters:
        x - the x coordinate for the crop
        y - the y coordinate for the crop
        width - the crop width
        height - the crop height

      • setFilters

        public void setFilters​(java.lang.String value)
        Sets the list of filters as a String.

        Parameters:
        value - the list of filters to set

      • setFocalPoint

        public void setFocalPoint​(CmsPoint point)
        Sets the focal point.

        Parameters:
        point - the new value for the focal point

      • setHeight

        public void setHeight​(int height)
        Sets the height.

        Parameters:
        height - the height to set

      • setMaxHeight

        public void setMaxHeight​(int maxHeight)
        Sets the maximum target height (for scale type '5').

        Parameters:
        maxHeight - the maximum target height to set

      • setMaxWidth

        public void setMaxWidth​(int maxWidth)
        Sets the maximum target width (for scale type '5').

        Parameters:
        maxWidth - the maximum target width to set

      • setPosition

        public void setPosition​(int position)
        Sets the scale position.

        Parameters:
        position - the position to set

      • setQuality

        public void setQuality​(int quality)
        Sets the image saving quality in percent.

        Parameters:
        quality - the image saving quality (in percent) to set

      • setWidth

        public void setWidth​(int width)
        Sets the width.

        Parameters:
        width - the width to set

      • toRequestParam

        public java.lang.String toRequestParam()
        Creates a request parameter configured with the values from this image scaler, also appends a '?' char as a prefix so that this may be directly appended to an image URL.

        This can be appended to an image request in order to apply image scaling parameters.

        Returns:
        a request parameter configured with the values from this image scaler

      • toString

        public java.lang.String toString()
        Overrides:
        toString in class java.lang.Object
        See Also:
        Object.toString()