Class StdPicture


  • public final class StdPicture
    extends Object
    The StdPicture class provides static methods for manipulating the individual pixels of an image using the RGB color model. You can either initialize 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.read("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.

    anatomy of an image

    Initializing the picture. You can use the following methods to initialize the picture:

    The first method reads an image in a supported file format (typically JPEG, PNG, GIF, TIFF, and BMP) and initializes the picture to that image. The second method initializes a width-by-height picture, with each pixel black.

    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 method sets 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.read("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.setRGB(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 alpha, red, green, and bluecomponents 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, the alpha value is 255.

    Saving files. The StdPicture class supports writing images to a supported file format (typically JPEG, PNG, GIF, TIFF, and BMP). You can save the picture to a file two method:

    Alternatively, you can save the picture interactively by using the menu option File → Save from the picture window.

    File formats. The StdPicture class supports reading and writing images to any of the file formats supported by javax.imageio (typically JPEG, PNG, GIF, TIFF, and BMP). The file extensions corresponding to JPEG, PNG, GIF, TIFF, and BMP, are .jpg, .png, .gif, .tif, and .bmp, respectively. The file formats JPEG and BMP do not support transparency.

    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 Description
      static int getAlpha​(int col, int row)
      Returns the alpha component of the color of pixel (col, row).
      static int getARGB​(int col, int row)
      Returns the ARGB 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 containing the picture.
      static void init​(int width, int height)
      Initializes a width-by-height picture, with width columns and height rows, where each pixel is black.
      static boolean isVisible()
      Is the window containing the picture visible?
      static void main​(String[] args)
      Unit tests this StdPicture data type.
      static void pause​(int t)
      Pauses for t milliseconds.
      static void read​(String filename)
      Initializes the picture by reading a JPEG, PNG, GIF, BMP, or TIFF image from a file or URL.
      static void save​(String filename)
      Saves the picture to a file in a supported file format (typically JPEG, PNG, GIF, TIFF, and BMP).
      static void setARGB​(int col, int row, int argb)
      Sets the color of pixel (col, row) to the given ARGB color.
      static void setARGB​(int col, int row, int a, int r, int g, int b)
      Sets the color of pixel (col, row) to the given ARGB color using alpha, red, green, and blue components.
      static void setRGB​(int col, int row, int r, int g, int b)
      Sets the color of pixel (col, row) to the given RGB color using red, green, and blue components.
      static void setTitle​(String title)
      Sets the title of this picture.
      static void show()
      Displays the picture in a window on the screen.
      static int width()
      Returns the width of the picture.
    • Method Detail

      • init

        public static void init​(int width,
                                int height)
        Initializes 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
      • read

        public static void read​(String filename)
        Initializes the picture by reading a JPEG, PNG, GIF, BMP, or TIFF image from a file or URL. The filetype extension must be .jpg, .png, .gif, .bmp, or .tif.
        Parameters:
        filename - the name of the file or URL
        Throws:
        IllegalArgumentException - if cannot read image
        IllegalArgumentException - if name is null
      • isVisible

        public static boolean isVisible()
        Is the window containing the picture visible?
        Returns:
        true if the picture is visible, and false otherwise
      • show

        public static void show()
        Displays the picture in a window on the screen.
      • hide

        public static void hide()
        Hides the window containing the picture.
      • pause

        public static void pause​(int t)
        Pauses for t milliseconds. This method is intended to support computer animation.
        Parameters:
        t - number of milliseconds
        Throws:
        IllegalArgumentException - if t is negative
      • 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:
        IndexOutOfBoundsException - 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:
        IndexOutOfBoundsException - 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:
        IndexOutOfBoundsException - 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:
        IndexOutOfBoundsException - unless both 0 <= col < width and 0 <= row < height
      • getARGB

        public static int getARGB​(int col,
                                  int row)
        Returns the ARGB color of pixel (col, row).
        Parameters:
        col - the column index
        row - the row index
        Returns:
        the ARGB color of pixel (col, row as a 32-bit integer
        Throws:
        IndexOutOfBoundsException - 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 the given RGB color using red, green, and blue components. The alpha component is set to 255 (no transparency).
        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:
        IndexOutOfBoundsException - 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 the given ARGB color using alpha, red, green, and blue components.
        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:
        IndexOutOfBoundsException - unless both 0 <= col < width and 0 <= row < height
        IllegalArgumentException - unless 0 <= a < 256, 0 <= r < 256, 0 <= g < 256, and 0 <= b < 256.
      • setARGB

        public static void setARGB​(int col,
                                   int row,
                                   int argb)
        Sets the color of pixel (col, row) to the given ARGB color.
        Parameters:
        col - the column index
        row - the row index
        argb - the ARGB color, represented as a 32-bit integer
        Throws:
        IndexOutOfBoundsException - unless both 0 <= col < width and 0 <= row < height
      • setTitle

        public static void setTitle​(String title)
        Sets the title of this picture.
        Parameters:
        title - the title
        Throws:
        IllegalArgumentException - if title is null
      • save

        public static void save​(String filename)
        Saves the picture to a file in a supported file format (typically JPEG, PNG, GIF, TIFF, and BMP). The filetype extension must be .jpg, .png, .gif, .bmp, or .tif. If the file format does not support transparency (such as JPEG or BMP), it will be converted to be opaque (with purely transparent pixels converted to black).
        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