Package resources

Class StrangeImage


  • public abstract class StrangeImage
    extends java.lang.Object
    A high-level representation of a drawable graphic that can be used by Strange Eons in various contexts. This class is often the starting point when working with images selected by the user. The class provides a common interface that can be used to work with both bitmap and vector images transparently.

    For drawing purposes, a StrangeImage can be treated as either a bitmap or vector image regardless of the original format. It can also be painted directly.

    A StrangeImage must have a positive width and height. Breaking this condition will lead to bugs that may be hard to detect. If you must return a representation of an image with a zero width or height, return an invisible image instead.

    Since:
    3.0.3695
    Author:
    Chris Jennings
    • Constructor Summary

      Constructors 
      Constructor Description
      StrangeImage()
      Constructs a new StrangeImage.
    • Method Summary

      All Methods Static Methods Instance Methods Abstract Methods Concrete Methods 
      Modifier and Type Method Description
      abstract java.awt.image.BufferedImage asBufferedImage()
      Returns a version of the image as a BufferedImage image.
      abstract VectorImage asVectorImage()
      Returns a version of the image as a VectorImage image.
      static StrangeImage create​(VectorImage source)
      Creates a new StrangeImage from the specified vector image source.
      static StrangeImage create​(java.awt.Image source)
      Creates a new StrangeImage from the specified bitmap image source.
      static boolean exists​(java.lang.String identifier)
      Returns whether or not an identifier refers to a valid image.
      static StrangeImage get​(java.lang.String identifier)
      Returns a StrangeImage for the given identifier.
      static java.awt.image.BufferedImage getAsBufferedImage​(java.lang.String identifier)
      Returns a BufferedImage for the given identifier.
      double getAspectRatio()
      Returns the aspect ratio of the image, that is, the width divided by the height.
      abstract int getHeight()
      Returns a typical pixel height for the image.
      abstract double getHeight2D()
      Returns the image height as a double value.
      static StrangeImage getInvisibleImage()
      Returns a StrangeImage that is completely invisible.
      static StrangeImage getMissingImage()
      Returns a standard image returned from get(java.lang.String) when an image cannot be obtained from the specified identifier.
      abstract int getWidth()
      Returns a typical pixel width for the image.
      abstract double getWidth2D()
      Returns the image width as a double value.
      static java.net.URL identifierToURL​(java.lang.String identifier)
      Returns a URL for a user image identifier, or null.
      static boolean isFileIdentifier​(java.lang.String identifier)
      Returns true if the image identifier names a local file, as opposed to a special URL.
      boolean isTransparent()
      Returns true if some parts of the image may not be opaque.
      boolean isVectorFormat()
      Returns true if the underlying image is a vector image.
      void paint​(java.awt.Graphics2D g, double x, double y, double width, double height, boolean fitToSize)
      Paints the image to a graphics context at the specified location and dimensions.
      abstract void paint​(java.awt.Graphics2D g, int x, int y, int width, int height, boolean fitToSize)
      Paints the image to a graphics context at the specified location and dimensions.
      void paint​(java.awt.Graphics2D g, java.awt.geom.Rectangle2D rect, boolean fitToSize)
      Paints the image to a graphics context within the bounds of the specified rectangle.
      java.awt.image.BufferedImage toBufferedImage​(int width, int height, boolean fitToSize)
      Returns a new buffered image representing the image content.
      • Methods inherited from class java.lang.Object

        clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
    • Constructor Detail

      • StrangeImage

        public StrangeImage()
        Constructs a new StrangeImage.
    • Method Detail

      • paint

        public abstract void paint​(java.awt.Graphics2D g,
                                   int x,
                                   int y,
                                   int width,
                                   int height,
                                   boolean fitToSize)
        Paints the image to a graphics context at the specified location and dimensions.
        Parameters:
        g - the graphics context to use for painting
        x - the x-coordinate of the upper-left corner of the image
        y - the y-coordinate of the upper-left corner of the image
        width - the width of the image
        height - the height of the image
        fitToSize - if true, the image's original aspect ratio will be maintained
      • paint

        public void paint​(java.awt.Graphics2D g,
                          double x,
                          double y,
                          double width,
                          double height,
                          boolean fitToSize)
        Paints the image to a graphics context at the specified location and dimensions. The location and size are specified using double precision floating point values; depending on the underlying implementation, these coordinates may be rounded to a less accurate form before painting.
        Parameters:
        g - the graphics context to use for painting
        x - the x-coordinate of the upper-left corner of the image
        y - the y-coordinate of the upper-left corner of the image
        width - the width of the image
        height - the height of the image
        fitToSize - if true, the image's original aspect ratio will be maintained
      • paint

        public final void paint​(java.awt.Graphics2D g,
                                java.awt.geom.Rectangle2D rect,
                                boolean fitToSize)
        Paints the image to a graphics context within the bounds of the specified rectangle.
        Parameters:
        g - the graphics context
        rect - the rectangle defining the upper-left corner and dimensions of the image
        fitToSize - if true, the image's original aspect ratio will be maintained
      • asBufferedImage

        public abstract java.awt.image.BufferedImage asBufferedImage()
        Returns a version of the image as a BufferedImage image. The returned value may be shared, so the image must not be modified. If the underlying image type is a bitmap image, then the returned image will be the same size as the original image. The returned image is guaranteed to use an RGB or ARGB pixel format.
        Returns:
        a bitmap version of the image
      • asVectorImage

        public abstract VectorImage asVectorImage()
        Returns a version of the image as a VectorImage image. Note that if the underlying image is a bitmap image, this will not convert the image into a true vector format (for example, by applying a tracing algorithm). It simply provides a VectorImage interface to the underlying bitmap data.
        Returns:
        a vector version of the image
      • toBufferedImage

        public java.awt.image.BufferedImage toBufferedImage​(int width,
                                                            int height,
                                                            boolean fitToSize)
        Returns a new buffered image representing the image content. The image will be resized, if necessary, to the specified size. If fitToSize is true, then the original aspect ratio of the image will be maintained. The returned image is guaranteed to use an RGB or ARGB pixel format.
        Parameters:
        width - the image width
        height - the image height
        fitToSize - if true, the original aspect ratio will be maintained
        Returns:
        a version of the image as a bitmap
      • getWidth

        public abstract int getWidth()
        Returns a typical pixel width for the image. If the underlying image is a bitmap image, this will return the true pixel width of that image.
        Returns:
        a width for the image, in pixels
      • getHeight

        public abstract int getHeight()
        Returns a typical pixel height for the image. If the underlying image is a bitmap image, this will return the true pixel height of that image.
        Returns:
        a height for the image, in pixels
      • getWidth2D

        public abstract double getWidth2D()
        Returns the image width as a double value. Depending on the underlying image, this may return a more accurate measure of the true image width than getWidth().
        Returns:
        a width for the image, in pixels
      • getHeight2D

        public abstract double getHeight2D()
        Returns the image height as a double value. Depending on the underlying image, this may return a more accurate measure of the true image height than getHeight().
        Returns:
        a height for the image, in pixels
      • getAspectRatio

        public double getAspectRatio()
        Returns the aspect ratio of the image, that is, the width divided by the height. When painting the image at a particular width or height, one can calculate the value for other dimension that will maintain the same image shape using the aspect ratio:
        Compute size from aspect ratio
        Known Dimension: Other Dimension Calculated Using:
        widthheight = width / aspectRatio
        heightwidth = height * aspectRatio
        Returns:
        the image aspect ratio
      • isTransparent

        public boolean isTransparent()
        Returns true if some parts of the image may not be opaque. If this returns false, then it is guaranteed that the image completely covers a rectangular area described by the specified width and height when painted. If this method returns true, then some parts of the painted area may not be completely covered.
        Returns:
        true if the image may have transparent areas; false if the image is known with certainly to be completely opaque
      • isVectorFormat

        public boolean isVectorFormat()
        Returns true if the underlying image is a vector image. If you wish to work with the original image in its underlying form, you can use code like the following:
         if( si.isVectorFormat() ) {
             VectorImage vi = si.asVectorImage();
             // ...
         } else {
             BufferedImage bi = si.asBufferedImage();
             // ...
         }
         
        Returns:
        true if the underlying image is a vector image; false if it is a bitmap image
      • create

        public static StrangeImage create​(java.awt.Image source)
        Creates a new StrangeImage from the specified bitmap image source.
        Parameters:
        source - the source image
        Returns:
        a view of the source image as a StrangeImage instance
      • create

        public static StrangeImage create​(VectorImage source)
        Creates a new StrangeImage from the specified vector image source.
        Parameters:
        source - the source image
        Returns:
        a view of the source image as a StrangeImage instance
      • get

        public static StrangeImage get​(java.lang.String identifier)
        Returns a StrangeImage for the given identifier. The identifier can be a local file path or a file:, http:, res:, or project: URL. Any string that is valid in a portrait panel will produce the same image here, except for the empty string that produce's the component-specific default portrait.
        Parameters:
        identifier - the identifier to use to locate the file
        Returns:
        the identified image, or a "missing image" stand-in
      • getAsBufferedImage

        public static java.awt.image.BufferedImage getAsBufferedImage​(java.lang.String identifier)
        Returns a BufferedImage for the given identifier. The identifier can be a local file path or a file:, http:, res:, or project: URL. Any string that is valid in a portrait panel will produce the same image here, except for the empty string that produce's the component-specific default portrait.

        This method is similar to get(java.lang.String), but ensures that the returned image is a BufferedImage bitmap. Vector images will be converted to bitmaps automatically. Where possible, prefer code that works with both bitmaps and vectors transparently by using get(java.lang.String) instead.

        Parameters:
        identifier - the identifier to use to locate the file
        Returns:
        the identified image, or a "missing image" stand-in
        Since:
        3.2
      • exists

        public static boolean exists​(java.lang.String identifier)
        Returns whether or not an identifier refers to a valid image. For example, passing a file identifier for a file that does not exist would return false. Note that this will load (and cache) the image if it is not already loaded.
        Parameters:
        identifier - the identifier to use to locate the file
        Returns:
        true if the identifier points to a valid image, false otherwise
        Since:
        3.2
      • identifierToURL

        public static java.net.URL identifierToURL​(java.lang.String identifier)
        Returns a URL for a user image identifier, or null. If the identifier is null or empty, then null is returned. (An empty string is typically used to indicate that a default image should be used.)
        Parameters:
        identifier - an identifier string containing a local file path or URL
        Returns:
        a URL that can be used to read the identified content
      • isFileIdentifier

        public static boolean isFileIdentifier​(java.lang.String identifier)
        Returns true if the image identifier names a local file, as opposed to a special URL.
        Parameters:
        identifier - the identifier to locate
        Returns:
        true if the identifier is for a local file
        See Also:
        get(java.lang.String)
      • getInvisibleImage

        public static StrangeImage getInvisibleImage()
        Returns a StrangeImage that is completely invisible. This can be used as a stand-in image for an image with a zero width or height, since StrangeImages must have a non-zero area.
        Returns:
        a completely transparent image
      • getMissingImage

        public static StrangeImage getMissingImage()
        Returns a standard image returned from get(java.lang.String) when an image cannot be obtained from the specified identifier.
        Returns:
        the shared missing image