Picture (Algorithms 4/e)

Object
- edu.princeton.cs.algs4.Picture

All Implemented Interfaces:

ActionListener, EventListener
```
public final class Picture
extends Object
implements ActionListener
```
This class provides methods for manipulating individual pixels of an image using the RGB color format. The alpha component (for transparency) is not currently supported. 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, which is a common convention in image processing. 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 getRGB() and setRGB() methods use a 32-bit int to encode the color, thereby avoiding the need to create temporary Color objects. The red (R), green (G), and blue (B) components are encoded using the least significant 24 bits. Given a 32-bit int encoding the color, the following code extracts the RGB components:
```
  int r = (rgb >> 16) & 0xFF;
  int g = (rgb >>  8) & 0xFF;
  int b = (rgb >>  0) & 0xFF;
  
```
Given the RGB components (8-bits each) of a color, the following statement packs it into a 32-bit int:
```
  int rgb = (r << 16) + (g << 8) + (b << 0);
 
```
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.
For additional documentation, see Section 3.1 of Computer Science: An Interdisciplinary Approach by Robert Sedgewick and Kevin Wayne. See GrayscalePicture for a version that supports grayscale images.
Author:

Robert Sedgewick, Kevin Wayne

Constructor Summary

Constructors
Constructor and Description
`Picture(File file)` Creates a picture by reading the image from a PNG, GIF, or JPEG file.
`Picture(int width, int height)` Creates a `width`-by-`height` picture, with `width` columns and `height` rows, where each pixel is black.
`Picture(Picture picture)` Creates a new picture that is a deep copy of the argument picture.
`Picture(String name)` Creates a picture by reading an image from a file or URL.

Method Summary

All Methods Static Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`void`	`actionPerformed(ActionEvent e)` 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 color of pixel (`col`, `row`) as a `Color`.
`JLabel`	`getJLabel()` Returns a `JLabel` containing this picture, for embedding in a `JPanel`, `JFrame` or other GUI widget.
`int`	`getRGB(int col, int row)` Returns the color of pixel (`col`, `row`) as an `int`.
`int`	`hashCode()` This operation is not supported because pictures are mutable.
`int`	`height()` Returns the height of the picture.
`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 name)` 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 given color.
`void`	`setOriginLowerLeft()` Sets the origin to be the lower left pixel.
`void`	`setOriginUpperLeft()` Sets the origin to be the upper left pixel.
`void`	`setRGB(int col, int row, int rgb)` Sets the color of pixel (`col`, `row`) to given color.
`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 Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait

- Constructor Detail
  - Picture
```
public Picture(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 or zero
    
    IllegalArgumentException - if height is negative or zero
  - Picture
```
public Picture(Picture picture)
```
    Creates a new picture that is a deep copy of the argument picture.
    
    Parameters:
    
    picture - the picture to copy
    
    Throws:
    
    IllegalArgumentException - if picture is null
  - Picture
```
public Picture(String name)
```
    Creates a picture by reading an image from a file or URL.
    
    Parameters:
    
    name - the name of the file (.png, .gif, or .jpg) or URL.
    
    Throws:
    
    IllegalArgumentException - if cannot read image
    
    IllegalArgumentException - if name is null
  - Picture
```
public Picture(File file)
```
    Creates a picture by reading the image from a PNG, GIF, or JPEG file.
    
    Parameters:
    
    file - the file
    
    Throws:
    
    IllegalArgumentException - if cannot read image
    
    IllegalArgumentException - if file is null
- 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.
  - 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 color of pixel (col, row) as a Color.
    
    Parameters:
    
    col - the column index
    
    row - the row index
    
    Returns:
    
    the color of pixel (col, row)
    
    Throws:
    
    IllegalArgumentException - unless both 0 <= col < width and 0 <= row < height
  - getRGB
```
public int getRGB(int col,
                  int row)
```
    Returns the color of pixel (col, row) as an int. 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 integer representation of the color of pixel (col, row)
    
    Throws:
    
    IllegalArgumentException - 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 given color.
    
    Parameters:
    
    col - the column index
    
    row - the row index
    
    color - the color
    
    Throws:
    
    IllegalArgumentException - unless both 0 <= col < width and 0 <= row < height
    
    IllegalArgumentException - if color is null
  - setRGB
```
public void setRGB(int col,
                   int row,
                   int rgb)
```
    Sets the color of pixel (col, row) to given color.
    
    Parameters:
    
    col - the column index
    
    row - the row index
    
    rgb - the integer representation of the color
    
    Throws:
    
    IllegalArgumentException - 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 color of a pixel is represented using 6 hex digits to encode the red, green, and blue components.
    
    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 name)
```
    Saves the picture to a file in either PNG or JPEG format. The filetype extension must be either .png or .jpg.
    
    Parameters:
    
    name - the name of the file
    
    Throws:
    
    IllegalArgumentException - if name is null
  - 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 e)
```
    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

Class Picture

Constructor Summary

Method Summary

Methods inherited from class Object

Constructor Detail

Picture

Picture

Picture

Picture

Method Detail

getJLabel

setOriginUpperLeft

setOriginLowerLeft

show

height

width

get

getRGB

set

setRGB

equals

toString

hashCode

save

save

actionPerformed

main