StdPicture (Algorithms 4/e)

Object
- edu.princeton.cs.algs4.StdPicture

```
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:
- If you ran our autoinstaller, use the commands 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.
- Download stdlib.jar (or algs4.jar) and add it to the Java classpath.
- Download StdPicture.java and Picture.java and put them in the working directory.
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:
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:
- getAlpha(int col, int row)
- setARGB(int col, int row, int r, int g, int b, int a)
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:
- save(String filename)
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.
Author:

Robert Sedgewick, Kevin Wayne

Method Summary

All Methods Static Methods Concrete Methods
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.

Methods inherited from class Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Method Detail
  - create
```
public static void create(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
  - create
```
public static void create(String filename)
```
    Creates a 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 cannot read image
    
    IllegalArgumentException - if name is null
  - show
```
public static void show()
```
    Displays the picture in a window on the screen.
  - hide
```
public static void hide()
```
    Hides the window on the screen containing the picture.
  - height
```
public static int height()
```
    Returns the height of the picture.
    
    Returns:
    
    the height of the picture (in pixels)
  - width
```
public static int width()
```
    Returns the width of the picture.
    
    Returns:
    
    the width of the picture (in pixels)
  - getAlpha
```
public static int getAlpha(int col,
                           int row)
```
    Returns the alpha component of the color of pixel (col, row).
    
    Parameters:
    
    col - the column index
    
    row - the row index
    
    Returns:
    
    the alpha component of the color of pixel (col, row)
    
    Throws:
    
    IllegalArgumentException - unless both 0 <= col < width and 0 <= row < height
  - getRed
```
public static int getRed(int col,
                         int row)
```
    Returns the red component of the color of pixel (col, row).
    
    Parameters:
    
    col - the column index
    
    row - the row index
    
    Returns:
    
    the red component of the color of pixel (col, row)
    
    Throws:
    
    IllegalArgumentException - unless both 0 <= col < width and 0 <= row < height
  - getGreen
```
public static int getGreen(int col,
                           int row)
```
    Returns the green component of the color of pixel (col, row).
    
    Parameters:
    
    col - the column index
    
    row - the row index
    
    Returns:
    
    the green component of the color of pixel (col, row)
    
    Throws:
    
    IllegalArgumentException - unless both 0 <= col < width and 0 <= row < height
  - getBlue
```
public static int getBlue(int col,
                          int row)
```
    Returns the blue component of the color of pixel (col, row).
    
    Parameters:
    
    col - the column index
    
    row - the row index
    
    Returns:
    
    the blue component of the color of pixel (col, row)
    
    Throws:
    
    IllegalArgumentException - unless both 0 <= col < width and 0 <= row < height
  - setRGB
```
public static void setRGB(int col,
                          int row,
                          int r,
                          int g,
                          int b)
```
    Sets the color of pixel (col, row) to given color.
    
    Parameters:
    
    col - the column index
    
    row - the row index
    
    r - the red component of the color
    
    g - the green component of the color
    
    b - the blue component of the color
    
    Throws:
    
    IllegalArgumentException - unless both 0 <= col < width and 0 <= row < height
    
    IllegalArgumentException - unless 0 <= r < 256, 0 <= g < 256, and 0 <= b < 256.
  - setARGB
```
public 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.
    
    Parameters:
    
    col - the column index
    
    row - the row index
    
    a - the alpha component of the color
    
    r - the red component of the color
    
    g - the green component of the color
    
    b - the blue component of the color
    
    Throws:
    
    IllegalArgumentException - unless both 0 <= col < width and 0 <= row < height
    
    IllegalArgumentException - unless 0 <= a < 256, 0 <= r < 256, 0 <= g < 256, and 0 <= b < 256.
  - save
```
public static void save(String filename)
```
    Saves the picture to a file in a supported format (typically JPEG, PNG, GIF TIFF, and BMP).
    
    Parameters:
    
    filename - the name of the file
    
    Throws:
    
    IllegalArgumentException - if filename is null
    
    IllegalArgumentException - if filename is the empty string
  - main
```
public static void main(String[] args)
```
    Unit tests this StdPicture 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 StdPicture

Method Summary

Methods inherited from class Object

Method Detail

create

create

show

hide

height

width

getAlpha

getRed

getGreen

getBlue

setRGB

setARGB

save

main