Package edu.princeton.cs.algs4

Class GrayscalePicture

Object

edu.princeton.cs.algs4.GrayscalePicture

All Implemented Interfaces:

ActionListener, EventListener

public final class GrayscalePicture
extends Object
implements ActionListener

The GrayscalePicture data type provides a basic capability for manipulating the individual pixels of a grayscale image. The original image can be read from a PNG, GIF, or JPEG file or the user can create a blank image of a given dimension. This class includes methods for displaying the image in a window on the screen or saving it to a file.

Pixel (col, row) is column col and row row. By default, the origin (0, 0) is the pixel in the top-left corner. These are common conventions in image processing and consistent with Java's BufferedImage data type. The method setOriginLowerLeft() change the origin to the lower left.

The get() and set() methods use Color objects to get or set the color of the specified pixel. The Color objects are converted to grayscale if they have different values for the R, G, and B channels. The getGrayscale() and setGrayscale() methods use an 8-bit int to encode the grayscale value, thereby avoiding the need to create temporary Color objects.

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 (even though, in principle, only ~ W H bytes are needed).

For additional documentation, see Section 3.1 of Computer Science: An Interdisciplinary Approach by Robert Sedgewick and Kevin Wayne. See Picture for a version that supports 32-bit RGB color images.

Author:

Robert Sedgewick, Kevin Wayne

Constructor Summary

Constructors

Constructor	Description
GrayscalePicture(int width, int height)	Creates a width-by-height picture, with width columns and height rows, where each pixel is black.
GrayscalePicture(GrayscalePicture picture)	Creates a new grayscale picture that is a deep copy of the argument picture.
GrayscalePicture(String filename)	Creates a grayscale picture by reading an image from a file or URL.

Method Summary

Modifier and Type	Method	Description
void	actionPerformed(ActionEvent event)	Opens a save dialog box when the user selects "Save As" from the menu.
boolean	equals(Object other)	Returns true if this picture is equal to the argument picture.
Color	get(int col, int row)	Returns the grayscale value of pixel (col, row) as a Color.
int	getGrayscale(int col, int row)	Returns the grayscale value of pixel (col, row) as an int between 0 and 255.
JLabel	getJLabel()	Returns a JLabel containing this picture, for embedding in a JPanel, JFrame or other GUI widget.
int	hashCode()	This operation is not supported because pictures are mutable.
int	height()	Returns the height of the picture.
void	hide()	Hides the window on the screen.
boolean	isVisible()	Is the window containing the picture visible?
static void	main(String[] args)	Unit tests this Picture data type.
void	save(File file)	Saves the picture to a file in a PNG or JPEG image format.
void	save(String filename)	Saves the picture to a file in either PNG or JPEG format.
void	set(int col, int row, Color color)	Sets the color of pixel (col, row) to the given grayscale value.
void	setGrayscale(int col, int row, int gray)	Sets the color of pixel (col, row) to the given grayscale value between 0 and 255.
void	setOriginLowerLeft()	Sets the origin to be the lower left pixel.
void	setOriginUpperLeft()	Sets the origin to be the upper left pixel.
void	show()	Displays the picture in a window on the screen.
String	toString()	Returns a string representation of this picture.
int	width()	Returns the width of the picture.

Methods inherited from class java.lang.Object

clone, getClass, notify, notifyAll, wait, wait, wait

Constructor Detail

GrayscalePicture

public GrayscalePicture(int width,
                        int height)

Creates a width-by-height picture, with width columns and height rows, where each pixel is black.

Parameters:

width - the width of the picture

height - the height of the picture

Throws:

IllegalArgumentException - if width is negative

IllegalArgumentException - if height is negative

GrayscalePicture

public GrayscalePicture(GrayscalePicture picture)

Creates a new grayscale picture that is a deep copy of the argument picture.

Parameters:

picture - the picture to copy

Throws:

IllegalArgumentException - if picture is null

GrayscalePicture

public GrayscalePicture(String filename)

Creates a grayscale picture by reading an image from a file or URL.

Parameters:

filename - the name of the file (.png, .gif, or .jpg) or URL.

Throws:

IllegalArgumentException - if filename is null

IllegalArgumentException - if cannot read image from file or URL

Method Detail

getJLabel

public JLabel getJLabel()

Returns a JLabel containing this picture, for embedding in a JPanel, JFrame or other GUI widget.

Returns:

the JLabel

setOriginUpperLeft

public void setOriginUpperLeft()

Sets the origin to be the upper left pixel. This is the default.

setOriginLowerLeft

public void setOriginLowerLeft()

Sets the origin to be the lower left pixel.

show

public void show()

Displays the picture in a window on the screen.

hide

public void hide()

Hides the window on the screen.

isVisible

public boolean isVisible()

Is the window containing the picture visible?

Returns:

true if the picture is visible, and false otherwise

height

public int height()

Returns the height of the picture.

Returns:

the height of the picture (in pixels)

width

public int width()

Returns the width of the picture.

Returns:

the width of the picture (in pixels)

get

public Color get(int col,
                 int row)

Returns the grayscale value of pixel (col, row) as a Color.

Parameters:

col - the column index

row - the row index

Returns:

the grayscale value of pixel (col, row)

Throws:

IndexOutOfBoundsException - unless both 0 <= col < width and 0 <= row < height

getGrayscale

public int getGrayscale(int col,
                        int row)

Returns the grayscale value of pixel (col, row) as an int between 0 and 255. Using this method can be more efficient than get(int, int) because it does not create a Color object.

Parameters:

col - the column index

row - the row index

Returns:

the 8-bit integer representation of the grayscale value of pixel (col, row)

Throws:

IndexOutOfBoundsException - unless both 0 <= col < width and 0 <= row < height

set

public void set(int col,
                int row,
                Color color)

Sets the color of pixel (col, row) to the given grayscale value.

Parameters:

col - the column index

row - the row index

color - the color (converts to grayscale if color is not a shade of gray)

Throws:

IndexOutOfBoundsException - unless both 0 <= col < width and 0 <= row < height

IllegalArgumentException - if color is null

setGrayscale

public void setGrayscale(int col,
                         int row,
                         int gray)

Sets the color of pixel (col, row) to the given grayscale value between 0 and 255.

Parameters:

col - the column index

row - the row index

gray - the 8-bit integer representation of the grayscale value

Throws:

IndexOutOfBoundsException - unless both 0 <= col < width and 0 <= row < height

equals

public boolean equals(Object other)

Returns true if this picture is equal to the argument picture.

Overrides:

equals in class Object

Parameters:

other - the other picture

Returns:

true if this picture is the same dimension as other and if all pixels have the same color; false otherwise

toString

public String toString()

Returns a string representation of this picture. The result is a width-by-height matrix of pixels, where the grayscale value of a pixel is an integer between 0 and 255.

Overrides:

toString in class Object

Returns:

a string representation of this picture

hashCode

public int hashCode()

This operation is not supported because pictures are mutable.

Overrides:

hashCode in class Object

Returns:

does not return a value

Throws:

UnsupportedOperationException - if called

save

public void save(String filename)

Saves the picture to a file in either PNG or JPEG format. The filetype extension must be either .png or .jpg.

Parameters:

filename - the name of the file

Throws:

IllegalArgumentException - if filename is null

IllegalArgumentException - if filename is the empty string

IllegalArgumentException - if filename has invalid filetype extension

IllegalArgumentException - if cannot write the file filename

save

public void save(File file)

Saves the picture to a file in a PNG or JPEG image format.

Parameters:

file - the file

Throws:

IllegalArgumentException - if file is null

actionPerformed

public void actionPerformed(ActionEvent event)

Opens a save dialog box when the user selects "Save As" from the menu.

Specified by:

actionPerformed in interface ActionListener

main

public static void main(String[] args)

Unit tests this Picture data type. Reads a picture specified by the command-line argument, and shows it in a window on the screen.

Parameters:

args - the command-line arguments