JavaFX’s Image Class

By Doug Lowe

An image is a file that contains a picture. Java supports pictures in several formats, including .jpg, .png, .gif, and .bmp. To incorporate images into your applications, you need to use two classes: Image and ImageView. The Image class represents an image in memory, whereas the ImageView class is a Node that you can add to a scene graph to display an Image on the screen.

Both of these classes are in the package javafx.scene.image, so you need to add the following statement to your programs:

import javafx.scene.image.*;

To load an image from an external source, such as a disk file or a web location, you use the Image class. This class has six constructors, detailed in this table.

The Image Class
Constructor Description
Image(InputStream in) Creates an image by reading from the specified input
stream.
Image(InputStream in, double width, double
height, boolean preserveRatio, boolean smooth)
Creates an image by reading from the specified input stream and
resizes it according to the width and height you specify. preserveRatio indicates whether the aspect
ratio of the original image should be preserved, and smooth indicates whether image smoothing should
be applied.
Image(String url) Creates an image by reading from the specified URL.
Image(String url, boolean
backgroundLoading)
Creates an image by reading from the specified URL. If backgroundLoading is true, the image is loaded in the background
(that is, on a separate thread).
Image(String url, double width, double
height, boolean preserveRatio, boolean smooth)
Creates an image by reading from the specified URL. This
constructor specifies the width and height of the resulting image
and indicates whether the aspect ratio of the original image should
be preserved and whether image smoothing should be applied.
Image(String url, double width, double
height, boolean preserveRatio, boolean smooth, boolean
backgroundLoading)
Creates an image by reading from the specified web path and
resizes it according to the width and height you specify. preserveRatio indicates whether the aspect
ratio of the original image should be preserved, and smooth indicates whether image smoothing should
be applied. If backgroundLoading is true, the image is loaded in the background
(that is, on a separate thread).

The easiest way to load an image is to do so directly from a file on your local computer by specifying a file path in the Image constructor. The file path string should be prefaced by the protocol string file:. For example, the following constructor creates an Image object from a file named pic001.jpg in the folder C:Pictures:

Image img = new Image("file:C:\Pictures\pic001.jpg");

You can also specify a web location using the http: protocol, as in this example:

Image img = new Image("http://www.domain.com/pic001.jpg"); 

Notice in the web example that you don’t have to double the slashes because HTTP addresses use forward slashes, not backward slashes.

In many cases, you want to load an image from a File object. To do that, use the File object’s toURI method to get the correct path from the file. Note:toURI returns an object of type URI; you must then call getString to convert the URI to a string:

File f = new File("C:\Pictures\pic001.jpg");
Image img = new Image(f.toURI().toString());

Here, a file is created from the path C:Picturespic001.jpg. Then, an image is created from the file.

When you create an Image object, you can specify that the image should be resized by providing the width and height parameters. You’ll also need to provide two boolean arguments.

The first specifies whether you want JavaFX to preserve the image’s aspect ratio (that is, the ratio of width to height). If you specify true, the image may contain blank areas above and below or left and right as needed to preserve the image’s aspect ratio. If you specify false, the image may be distorted.

The second boolean argument specifies whether you want JavaFX to apply a smoothing algorithm to improve the clarity of the image. The smoothing process makes the image look better, but takes time.

Finally, you can specify an optional third boolean argument that indicates that you want the image to load in the background. This causes the image loading process to be spun off to a separate thread so that your main application thread can continue without waiting for the image to load.