public final class StdPicture extends Object
Overview.
The StdPicture
class provides a basic capability for manipulating
the individual pixels of an image using the RGB color model.
You can either create a blank image (of a given dimension) or read an
image in a supported file format
(typically JPEG, PNG, GIF TIFF, and BMP).
This class also includes methods for displaying the image in a window
and saving it to a file.
Use in the curriculum.
The StdPicture
class is intended for early usage in the
curriculum, before objects.
The Picture
class is an object-oriented version that supports
manipulating multiple pictures at the same time.
Getting started.
To use this class, you must have StdPicture
in your Java classpath.
Here are three possible ways to do this:
javac-introcs
and java-introcs
(or javac-algs4
and java-algs4
) when compiling and executing. These commands
add stdlib.jar
(or algs4.jar
) to the Java classpath, which
provides access to StdPicture
.
As a test, cut-and-paste the following short program into your editor:
public class TestStdPicture { public static void main(String[] args) { StdPicture.create("https://introcs.cs.princeton.edu/java/stdlib/mandrill.jpg"); StdPicture.show(); } }
If you compile and execute the program, you should see a picture of a mandrill (a colorful monkey native to west-central Africa) in a window.
Anatomy of an image. An image is a width-by-height grid of pixels, with pixel (0, 0) in the upper-left corner. Each pixel has a color that is represented using the RGB color model, which specifies the levels of red (R), green (G), and blue (B) on an integer scale from 0 to 255.
Getting and setting the colors of the individual pixels. You can use the following methods to retrieve the RGB components of a specified pixel:
getRed(int col, int row)
getGreen(int col, int row)
getBlue(int col, int row)
setRGB(int col, int row, int r, int g, int b)
The first three methods return the red, green, and blue components of pixel (col, row). Each component is an integer between 0 and 255, with 0 corresponding to the absence of that component and 255 corresponding to full intensity of that component. The last methods set the red, green, and blue components of pixel (col, row) to the specified values.
Iterating over the pixels. A common operation in image processing is to iterate over and process all of the pixels in an image. Here is a prototypical example that converts a color image to grayscale, using the NTSC formula Y = 0.299r + 0.587g + 0.114b. Note that if the red, green, and blue components are all equal, then the color is a shade of gray.
StdPicture.create("https://introcs.cs.princeton.edu/java/stdlib/mandrill.jpg"); for (int col = 0; col < StdPicture.width(); col++) { for (int row = 0; row < StdPicture.height(); row++) { int r = StdPicture.getRed(col, row); int g = StdPicture.getGreen(col, row); int b = StdPicture.getBlue(col, row); int y = (int) (Math.round(0.299*r + 0.587*g + 0.114*b)); StdPicture.set(col, row, y, y, y); } } StdPicture.show();
Transparency.
The StdPicture
class supports transparent images, using the
ARGB color model. The following methods are useful for this:
The first method gets the alpha component of pixel (col, row). The second methods sets the red, green, blue, and alpha components of pixel (col, row). The alpha value defines the transparency of a color, with 0 corresponding to completely transparent and 255 to completely opaque. If transparency is not explicitly used, all alpha values are 255.
File formats.
The Picture
class supports reading and writing images in
a supported format (typically JPEG, PNG, GIF TIFF, and BMP).
Note that some file format (such as JPEG and BMP) do not support transparency.
You can save the picture to a file using this method:
Alternatively, you can save the picture interactively by using the menu option File → Save from the picture window.
Memory usage.
A W-by-H picture uses ~ 4 W H bytes of memory,
since the color of each pixel is encoded as a 32-bit int
.
Additional documentation. For additional documentation, see Section 3.1 of Computer Science: An Interdisciplinary Approach by Robert Sedgewick and Kevin Wayne.
Modifier and Type | Method and Description |
---|---|
static void |
create(int width,
int height)
Creates a
width -by-height picture, with width columns
and height rows, where each pixel is black. |
static void |
create(String filename)
Creates a picture by reading an image from a file or URL.
|
static int |
getAlpha(int col,
int row)
Returns the alpha component of the color of pixel (
col , row ). |
static int |
getBlue(int col,
int row)
Returns the blue component of the color of pixel (
col , row ). |
static int |
getGreen(int col,
int row)
Returns the green component of the color of pixel (
col , row ). |
static int |
getRed(int col,
int row)
Returns the red component of the color of pixel (
col , row ). |
static int |
height()
Returns the height of the picture.
|
static void |
hide()
Hides the window on the screen containing the picture.
|
static void |
main(String[] args)
Unit tests this
StdPicture data type. |
static void |
save(String filename)
Saves the picture to a file in a supported format
(typically JPEG, PNG, GIF TIFF, and BMP).
|
static void |
setARGB(int col,
int row,
int a,
int r,
int g,
int b)
Sets the color of pixel (
col , row ) to given color. |
static void |
setRGB(int col,
int row,
int r,
int g,
int b)
Sets the color of pixel (
col , row ) to given color. |
static void |
show()
Displays the picture in a window on the screen.
|
static int |
width()
Returns the width of the picture.
|
public static void create(int width, int height)
width
-by-height
picture, with width
columns
and height
rows, where each pixel is black.width
- the width of the pictureheight
- the height of the pictureIllegalArgumentException
- if width
is negative or zeroIllegalArgumentException
- if height
is negative or zeropublic static void create(String filename)
filename
- the name of the file (.png, .gif, or .jpg) or URL.IllegalArgumentException
- if cannot read imageIllegalArgumentException
- if name
is null
public static void show()
public static void hide()
public static int height()
public static int width()
public static int getAlpha(int col, int row)
col
, row
).col
- the column indexrow
- the row indexcol
, row
)IllegalArgumentException
- unless both 0 <= col < width
and 0 <= row < height
public static int getRed(int col, int row)
col
, row
).col
- the column indexrow
- the row indexcol
, row
)IllegalArgumentException
- unless both 0 <= col < width
and 0 <= row < height
public static int getGreen(int col, int row)
col
, row
).col
- the column indexrow
- the row indexcol
, row
)IllegalArgumentException
- unless both 0 <= col < width
and 0 <= row < height
public static int getBlue(int col, int row)
col
, row
).col
- the column indexrow
- the row indexcol
, row
)IllegalArgumentException
- unless both 0 <= col < width
and 0 <= row < height
public static void setRGB(int col, int row, int r, int g, int b)
col
, row
) to given color.col
- the column indexrow
- the row indexr
- the red component of the colorg
- the green component of the colorb
- the blue component of the colorIllegalArgumentException
- unless both 0 <= col < width
and 0 <= row < height
IllegalArgumentException
- unless 0 <= r < 256
, 0 <= g < 256
,
and 0 <= b < 256
.public static void setARGB(int col, int row, int a, int r, int g, int b)
col
, row
) to given color.col
- the column indexrow
- the row indexa
- the alpha component of the colorr
- the red component of the colorg
- the green component of the colorb
- the blue component of the colorIllegalArgumentException
- unless both 0 <= col < width
and 0 <= row < height
IllegalArgumentException
- unless 0 <= a < 256
, 0 <= r < 256
,
0 <= g < 256
, and 0 <= b < 256
.public static void save(String filename)
filename
- the name of the fileIllegalArgumentException
- if filename
is null
IllegalArgumentException
- if filename
is the empty stringpublic static void main(String[] args)
StdPicture
data type.
Reads a picture specified by the command-line argument,
and shows it in a window on the screen.args
- the command-line arguments