Image (JavaFX 28)
Description: declaration: module: javafx.graphics, package: javafx.scene.image, class: Image

# Class Image

java.lang.Object
javafx.scene.image.Image

Direct Known Subclasses:
  `WritableImage`

public class Image extends Object
The `Image` class represents graphical images and is used for loading images from a specified URL.

JavaFX has built-in support for the following image formats:

- BMP
- GIF
- JPEG
- PNG

For all other formats, JavaFX uses the `Java Image I/O API` on supported platforms. Image I/O is extensible so that developers can "plug-in" support for additional formats.

Images can be resized as they are loaded (for example to reduce the amount of memory consumed by the image). The application can specify the quality of filtering used when scaling, and whether to preserve the original image's aspect ratio.

If a URL string is passed to a constructor, it can be any of the following:

1. the name of a resource that can be resolved by the context `ClassLoader` for this thread
2. a file path that can be resolved by `File`
3. a URL that can be resolved by `URL` and for which a protocol handler exists

The RFC 2397 "data" scheme for URLs is supported in addition to the protocol handlers that are registered for the application. If a URL uses the "data" scheme, the data must be base64-encoded and the MIME type must be a subtype of the `image` type. The MIME type must match the image format of the data contained in the URL. In case of a mismatch between MIME type and image format, the image will be loaded if the image format can be determined by JavaFX, and a warning will be logged.

Use `ImageView` for displaying images loaded with this class. The same `Image` instance can be displayed by multiple `ImageView`s.

Example code for loading images:

    import javafx.scene.image.Image;

    // load an image in background, displaying a placeholder while it's loading
    // (assuming there's an ImageView node somewhere displaying this image)
    // The image is located in default package of the classpath
    Image image1 = new Image("/flower.png", true);

    // load an image and resize it to 100x150 without preserving its original
    // aspect ratio
    // The image is located in my.res package of the classpath
    Image image2 = new Image("my/res/flower.png", 100, 150, false, false);

    // load an image and resize it to width of 100 while preserving its
    // original aspect ratio, using faster filtering method
    // The image is downloaded from the supplied URL through http protocol
    Image image3 = new Image("http://sample.com/res/flower.png", 100, 0, false, false);

    // load an image and resize it only in one dimension, to the height of 100 and
    // the original width, without preserving original aspect ratio
    // The image is located in the current working directory
    Image image4 = new Image("file:flower.png", 0, 100, false, false);

Since:
  JavaFX 2.0

- ## Property Summary

  Properties
  Type
  Property
  Description
  `final ReadOnlyBooleanProperty`
  `error`
  Indicates whether an error was detected while loading an image.
  `final ReadOnlyObjectProperty<Exception>`
  `exception`
  The exception which caused image loading to fail.
  `final ReadOnlyDoubleProperty`
  `height`
  The image height or `0` if the image loading fails.
  `final ReadOnlyDoubleProperty`
  `progress`
  The approximate percentage of image's loading that has been completed.
  `final ReadOnlyDoubleProperty`
  `width`
  The image width or `0` if the image loading fails.

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `Image(InputStream is)`
  Constructs an `Image` with content loaded from the specified input stream.
  `Image(InputStream is, boolean backgroundLoading)`
  Constructs an `Image` with content loaded from the specified input stream.
  `Image(InputStream is, double requestedWidth, double requestedHeight, boolean preserveRatio, boolean smooth)`
  Constructs a new `Image` with the specified parameters.
  `Image(InputStream is, double requestedWidth, double requestedHeight, boolean preserveRatio, boolean smooth, boolean backgroundLoading)`
  Constructs a new `Image` with the specified parameters.
  `Image(String url)`
  Constructs an `Image` with content loaded from the specified URL.
  `Image(String url, boolean backgroundLoading)`
  Constructs an `Image` with content loaded from the specified URL using the specified parameters.
  `Image(String url, double requestedWidth, double requestedHeight, boolean preserveRatio, boolean smooth)`
  Constructs an `Image` with content loaded from the specified URL using the specified parameters.
  `Image(String url, double requestedWidth, double requestedHeight, boolean preserveRatio, boolean smooth, boolean backgroundLoading)`
  Constructs an `Image` with content loaded from the specified URL using the specified parameters.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `void`
  `cancel()`
  Cancels the background loading of this image.
  `final ReadOnlyBooleanProperty`
  `errorProperty()`
  Indicates whether an error was detected while loading an image.
  `final ReadOnlyObjectProperty<Exception>`
  `exceptionProperty()`
  The exception which caused image loading to fail.
  `final Exception`
  `getException()`
  Gets the value of the `exception` property.
  `final double`
  `getHeight()`
  Gets the value of the `height` property.
  `final PixelReader`
  `getPixelReader()`
  This method returns a `PixelReader` that provides access to read the pixels of the image, if the image is readable.
  `final double`
  `getProgress()`
  Gets the value of the `progress` property.
  `final double`
  `getRequestedHeight()`
  Gets the height of the bounding box within which the source image is resized as necessary to fit.
  `final double`
  `getRequestedWidth()`
  Gets the width of the bounding box within which the source image is resized as necessary to fit.
  `final String`
  `getUrl()`
  Returns the url used to fetch the pixel data contained in the Image instance, if specified in the constructor.
  `final double`
  `getWidth()`
  Gets the value of the `width` property.
  `final ReadOnlyDoubleProperty`
  `heightProperty()`
  The image height or `0` if the image loading fails.
  `final boolean`
  `isBackgroundLoading()`
  Indicates whether the image is being loaded in the background.
  `final boolean`
  `isError()`
  Gets the value of the `error` property.
  `final boolean`
  `isPreserveRatio()`
  Indicates whether to preserve the aspect ratio of the original image when scaling to fit the image within the bounding box provided by `width` and `height`.
  `final boolean`
  `isSmooth()`
  Indicates whether to use a better quality filtering algorithm or a faster one when scaling this image to fit within the bounding box provided by `width` and `height`.
  `final ReadOnlyDoubleProperty`
  `progressProperty()`
  The approximate percentage of image's loading that has been completed.
  `final ReadOnlyDoubleProperty`
  `widthProperty()`
  The image width or `0` if the image loading fails.

  ### Methods declared in class Object

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

- ## Property Details

  - ### progress

    public final ReadOnlyDoubleProperty progressProperty
    The approximate percentage of image's loading that has been completed. A positive value between 0 and 1 where 0 is 0% and 1 is 100%.
    Default value:
      0
    See Also:
      - `getProgress()`
      - `progressProperty()`

  - ### width

    public final ReadOnlyDoubleProperty widthProperty
    The image width or `0` if the image loading fails. While the image is being loaded it is set to `0`.
    See Also:
      - `getWidth()`
      - `widthProperty()`

  - ### height

    public final ReadOnlyDoubleProperty heightProperty
    The image height or `0` if the image loading fails. While the image is being loaded it is set to `0`.
    See Also:
      - `getHeight()`
      - `heightProperty()`

  - ### error

    public final ReadOnlyBooleanProperty errorProperty
    Indicates whether an error was detected while loading an image.
    Default value:
      false
    See Also:
      - `isError()`
      - `errorProperty()`

  - ### exception

    public final ReadOnlyObjectProperty<Exception> exceptionProperty
    The exception which caused image loading to fail. Contains a non-null value only if the `error` property is set to `true`.
    Since:
      JavaFX 8.0
    See Also:
      - `getException()`
      - `exceptionProperty()`

- ## Constructor Details

  - ### Image

    public Image(String url)
    Constructs an `Image` with content loaded from the specified URL.

    The image loading is performed immediately and is completed when this constructor returns.

    Parameters:
      `url` - a resource path, file path, or URL
    Throws:
      `NullPointerException` - if `url` is null
      `IllegalArgumentException` - if `url` is invalid or unsupported

  - ### Image

    public Image(String url, boolean backgroundLoading)
    Constructs an `Image` with content loaded from the specified URL using the specified parameters.

    If loading in the background is requested, then the `progress` property can be monitored for loading progress. Otherwise, the image loading is performed immediately and is completed when this constructor returns.

    Parameters:
      `url` - a resource path, file path, or URL
      `backgroundLoading` - indicates whether the image should be loaded in the background
    Throws:
      `NullPointerException` - if `url` is null
      `IllegalArgumentException` - if `url` is invalid or unsupported

  - ### Image

    public Image(String url, double requestedWidth, double requestedHeight, boolean preserveRatio, boolean smooth)
    Constructs an `Image` with content loaded from the specified URL using the specified parameters.

    The image loading is performed immediately and is completed when this constructor returns.

    Parameters:
      `url` - a resource path, file path, or URL
      `requestedWidth` - the image's bounding box width
      `requestedHeight` - the image's bounding box height
      `preserveRatio` - indicates whether to preserve the aspect ratio of the original image when scaling to fit the image within the specified bounding box
      `smooth` - indicates whether to use a better quality filtering algorithm or a faster one when scaling this image to fit within the specified bounding box
    Throws:
      `NullPointerException` - if `url` is null
      `IllegalArgumentException` - if `url` is invalid or unsupported

  - ### Image

    public Image(String url, double requestedWidth, double requestedHeight, boolean preserveRatio, boolean smooth, boolean backgroundLoading)
    Constructs an `Image` with content loaded from the specified URL using the specified parameters.

    If loading in the background is requested, then the `progress` property can be monitored for loading progress. Otherwise, the image loading is performed immediately and is completed when this constructor returns.

    Parameters:
      `url` - a resource path, file path, or URL
      `requestedWidth` - the image's bounding box width
      `requestedHeight` - the image's bounding box height
      `preserveRatio` - indicates whether to preserve the aspect ratio of the original image when scaling to fit the image within the specified bounding box
      `smooth` - indicates whether to use a better quality filtering algorithm or a faster one when scaling this image to fit within the specified bounding box
      `backgroundLoading` - indicates whether the image should be loaded in the background
    Throws:
      `NullPointerException` - if `url` is null
      `IllegalArgumentException` - if `url` is invalid or unsupported

  - ### Image

    public Image(InputStream is)
    Constructs an `Image` with content loaded from the specified input stream.

    The image loading is performed immediately and is completed when this constructor returns. The stream is consumed but not closed.

    Parameters:
      `is` - the stream from which to load the image
    Throws:
      `NullPointerException` - if input stream is null

  - ### Image

    public Image(InputStream is, boolean backgroundLoading)
    Constructs an `Image` with content loaded from the specified input stream.

    If `backgroundLoading` is `true`, the `progress` property can be monitored for loading progress. The stream will be consumed asynchronously; the caller must not read from or close it. It will be closed automatically when loading completes.

    If `backgroundLoading` is `false`, the image is loaded immediately and completed when this constructor returns. The stream is consumed but not closed.

    Parameters:
      `is` - the stream from which to load the image
      `backgroundLoading` - indicates whether the image should be loaded in the background
    Throws:
      `NullPointerException` - if input stream is null
    Since:
      26

  - ### Image

    public Image(InputStream is, double requestedWidth, double requestedHeight, boolean preserveRatio, boolean smooth)
    Constructs a new `Image` with the specified parameters.

    The image loading is performed immediately and is completed when this constructor returns. The stream is consumed but not closed.

    Parameters:
      `is` - the stream from which to load the image
      `requestedWidth` - the image's bounding box width
      `requestedHeight` - the image's bounding box height
      `preserveRatio` - indicates whether to preserve the aspect ratio of the original image when scaling to fit the image within the specified bounding box
      `smooth` - indicates whether to use a better quality filtering algorithm or a faster one when scaling this image to fit within the specified bounding box
    Throws:
      `NullPointerException` - if input stream is null

  - ### Image

    public Image(InputStream is, double requestedWidth, double requestedHeight, boolean preserveRatio, boolean smooth, boolean backgroundLoading)
    Constructs a new `Image` with the specified parameters.

    If `backgroundLoading` is `true`, the `progress` property can be monitored for loading progress. The stream will be consumed asynchronously; the caller must not read from or close it. It will be closed automatically when loading completes.

    If `backgroundLoading` is `false`, the image is loaded immediately and completed when this constructor returns. The stream is consumed but not closed.

    Parameters:
      `is` - the stream from which to load the image
      `requestedWidth` - the image's bounding box width
      `requestedHeight` - the image's bounding box height
      `preserveRatio` - indicates whether to preserve the aspect ratio of the original image when scaling to fit the image within the specified bounding box
      `smooth` - indicates whether to use a better quality filtering algorithm or a faster one when scaling this image to fit within the specified bounding box
      `backgroundLoading` - indicates whether the image should be loaded in the background
    Throws:
      `NullPointerException` - if input stream is null
    Since:
      26

- ## Method Details

  - ### getUrl

    public final String getUrl()
    Returns the url used to fetch the pixel data contained in the Image instance, if specified in the constructor. If no url is provided in the constructor (for instance, if the Image is constructed from an `InputStream`), this method will return null.
    Returns:
      a String containing the URL used to fetch the pixel data for this Image instance.
    Since:
      9

  - ### getProgress

    public final double getProgress()
    Gets the value of the `progress` property.
    Property description:
      The approximate percentage of image's loading that has been completed. A positive value between 0 and 1 where 0 is 0% and 1 is 100%.
    Default value:
      0
    Returns:
      the value of the `progress` property
    See Also:
      - `progressProperty()`

  - ### progressProperty

    public final ReadOnlyDoubleProperty progressProperty()
    The approximate percentage of image's loading that has been completed. A positive value between 0 and 1 where 0 is 0% and 1 is 100%.
    Default value:
      0
    Returns:
      the `progress` property
    See Also:
      - `getProgress()`

  - ### getRequestedWidth

    public final double getRequestedWidth()
    Gets the width of the bounding box within which the source image is resized as necessary to fit. If set to a value `<= 0`, then the intrinsic width of the image will be used.

    See `preserveRatio` for information on interaction between image's `requestedWidth`, `requestedHeight` and `preserveRatio` attributes.

    Returns:
      The requested width

  - ### getRequestedHeight

    public final double getRequestedHeight()
    Gets the height of the bounding box within which the source image is resized as necessary to fit. If set to a value `<= 0`, then the intrinsic height of the image will be used.

    See `preserveRatio` for information on interaction between image's `requestedWidth`, `requestedHeight` and `preserveRatio` attributes.

    Returns:
      The requested height

  - ### getWidth

    public final double getWidth()
    Gets the value of the `width` property.
    Property description:
      The image width or `0` if the image loading fails. While the image is being loaded it is set to `0`.
    Returns:
      the value of the `width` property
    See Also:
      - `widthProperty()`

  - ### widthProperty

    public final ReadOnlyDoubleProperty widthProperty()
    The image width or `0` if the image loading fails. While the image is being loaded it is set to `0`.
    Returns:
      the `width` property
    See Also:
      - `getWidth()`

  - ### getHeight

    public final double getHeight()
    Gets the value of the `height` property.
    Property description:
      The image height or `0` if the image loading fails. While the image is being loaded it is set to `0`.
    Returns:
      the value of the `height` property
    See Also:
      - `heightProperty()`

  - ### heightProperty

    public final ReadOnlyDoubleProperty heightProperty()
    The image height or `0` if the image loading fails. While the image is being loaded it is set to `0`.
    Returns:
      the `height` property
    See Also:
      - `getHeight()`

  - ### isPreserveRatio

    public final boolean isPreserveRatio()
    Indicates whether to preserve the aspect ratio of the original image when scaling to fit the image within the bounding box provided by `width` and `height`.

    If set to `true`, it affects the dimensions of this `Image` in the following way:

    - If only `width` is set, height is scaled to preserve ratio
    - If only `height` is set, width is scaled to preserve ratio
    - If both are set, they both may be scaled to get the best fit in a width by height rectangle while preserving the original aspect ratio
    The reported `width` and `height` may be different from the initially set values if they needed to be adjusted to preserve aspect ratio. If unset or set to `false`, it affects the dimensions of this `ImageView` in the following way:
    - If only `width` is set, the image's width is scaled to match and height is unchanged;
    - If only `height` is set, the image's height is scaled to match and height is unchanged;
    - If both are set, the image is scaled to match both.
    Returns:
      true if the aspect ratio of the original image is to be preserved when scaling to fit the image within the bounding box provided by `width` and `height`.

  - ### isSmooth

    public final boolean isSmooth()
    Indicates whether to use a better quality filtering algorithm or a faster one when scaling this image to fit within the bounding box provided by `width` and `height`.

    If not initialized or set to `true` a better quality filtering will be used, otherwise a faster but lesser quality filtering will be used.

    Returns:
      true if a better quality (but slower) filtering algorithm is used for scaling to fit within the bounding box provided by `width` and `height`.

  - ### isBackgroundLoading

    public final boolean isBackgroundLoading()
    Indicates whether the image is being loaded in the background.
    Returns:
      true if the image is loaded in the background

  - ### isError

    public final boolean isError()
    Gets the value of the `error` property.
    Property description:
      Indicates whether an error was detected while loading an image.
    Default value:
      false
    Returns:
      the value of the `error` property
    See Also:
      - `errorProperty()`

  - ### errorProperty

    public final ReadOnlyBooleanProperty errorProperty()
    Indicates whether an error was detected while loading an image.
    Default value:
      false
    Returns:
      the `error` property
    See Also:
      - `isError()`

  - ### getException

    public final Exception getException()
    Gets the value of the `exception` property.
    Property description:
      The exception which caused image loading to fail. Contains a non-null value only if the `error` property is set to `true`.
    Returns:
      the value of the `exception` property
    Since:
      JavaFX 8.0
    See Also:
      - `exceptionProperty()`

  - ### exceptionProperty

    public final ReadOnlyObjectProperty<Exception> exceptionProperty()
    The exception which caused image loading to fail. Contains a non-null value only if the `error` property is set to `true`.
    Returns:
      the `exception` property
    Since:
      JavaFX 8.0
    See Also:
      - `getException()`

  - ### cancel

    public void cancel()
    Cancels the background loading of this image.

    Has no effect if this image isn't loaded in background or if loading has already completed.

  - ### getPixelReader

    public final PixelReader getPixelReader()
    This method returns a `PixelReader` that provides access to read the pixels of the image, if the image is readable. If this method returns null then this image does not support reading at this time. This method will return null if the image is being loaded from a source and is still incomplete {the progress is still <1.0) or if there was an error. This method may also return null for some images in a format that is not supported for reading and writing pixels to.
    Returns:
      the `PixelReader` for reading the pixel data of the image
    Since:
      JavaFX 2.2