processing.core
Class PImage

java.lang.Object
  processing.core.PImage

All Implemented Interfaces:

java.lang.Cloneable, PConstants

Direct Known Subclasses:

PGraphics

public class PImage

extends java.lang.Object

implements PConstants, java.lang.Cloneable

Storage class for pixel data. This is the base class for most image and pixel information, such as PGraphics and the video library classes.

Code for copying, resizing, scaling, and blending contributed by toxi

Field Summary

java.lang.Object	cache for subclasses that need to store info about the image
int	format Format for this image, one of RGB, ARGB or ALPHA.
int	height
int	imageMode
boolean	modified modified portion of the image
int	mx1
int	mx2
int	my1
int	my2
PApplet	parent Path to parent object that will be used with save().
int[]	pixels
boolean	smooth
int	width

Fields inherited from interface processing.core.PConstants

ADD, ALPHA, ALPHA_MASK, ALT, AMBIENT, ARGB, ARROW, BACKSPACE, BASELINE, BEVEL, BLEND, BLUE_MASK, BLUR, BOTTOM, BURN, CENTER, CENTER_RADIUS, CHATTER, CLOSE, CODED, COMPLAINT, CONTROL, CORNER, CORNERS, CROSS, CUSTOM, DARKEST, DEG_TO_RAD, DELETE, DIFFERENCE, DILATE, DIRECTIONAL, DISABLE_AUTO_GZIP, DISABLE_DEPTH_TEST, DISABLE_ERROR_REPORT, DISABLE_TEXT_SMOOTH, DODGE, DOWN, DXF, ENABLE_ACCURATE_TEXTURES, ENABLE_DEPTH_SORT, ENABLE_NATIVE_FONTS, ENTER, EPSILON, ERODE, ESC, EXCLUSION, GIF, GRAY, GREEN_MASK, HALF_PI, HAND, HARD_LIGHT, HINT_COUNT, HSB, IMAGE, INVERT, JAVA2D, JPEG, LEFT, LIGHTEST, LINES, LINUX, MACOS9, MACOSX, MAX_FLOAT, MAX_INT, MIN_FLOAT, MIN_INT, MITER, MODEL, MOVE, MULTIPLY, NO_FLYING_POO, NORMALIZED, OPAQUE, OPEN, OPENGL, ORTHOGRAPHIC, OTHER, OVERLAY, P2D, P3D, PDF, PERSPECTIVE, PI, PIXEL_CENTER, POINT, POINTS, POLYGON, POSTERIZE, PROBLEM, PROJECT, QUAD_STRIP, QUADS, QUARTER_PI, RAD_TO_DEG, RADIUS, RED_MASK, REPLACE, RETURN, RGB, RIGHT, ROUND, SCREEN, SHAPE, SHIFT, SOFT_LIGHT, SPOT, SQUARE, SUBTRACT, TAB, TARGA, TEXT, THIRD_PI, THRESHOLD, TIFF, TOP, TRIANGLE_FAN, TRIANGLE_STRIP, TRIANGLES, TWO_PI, UP, WAIT, WHITESPACE, WINDOWS

Constructor Summary

PImage()
Create an empty image object, set its format to RGB.

PImage(java.awt.Image img)
Construct a new PImage from a java.awt.Image.

PImage(int width, int height)
Create a new RGB (alpha ignored) image of a specific size.

PImage(int width, int height, int format)

Method Summary

void	blend(int sx1, int sy1, int sx2, int sy2, int dx1, int dy1, int dx2, int dy2, int mode) Blends one area of this image to another area.
void	blend(PImage src, int sx1, int sy1, int sx2, int sy2, int dx1, int dy1, int dx2, int dy2, int mode) Copies area of one image into another PImage object.
static int	blendColor(int c1, int c2, int mode) Blend two colors based on a particular mode.
java.lang.Object	clone() Duplicate an image, returns new PImage object.
void	copy(int sx1, int sy1, int sx2, int sy2, int dx1, int dy1, int dx2, int dy2) Copy things from one area of this image to another area in the same image.
void	copy(PImage src, int sx1, int sy1, int sx2, int sy2, int dx1, int dy1, int dx2, int dy2) Copies area of one image into another PImage object.
void	filter(int kind) Method to apply a variety of basic filters to this image.
void	filter(int kind, float param) Method to apply a variety of basic filters to this image.
PImage	get() Returns a copy of this PImage.
int	get(int x, int y) Returns an ARGB "color" type (a packed 32 bit int with the color.
PImage	get(int x, int y, int w, int h) Grab a subsection of a PImage, and copy it into a fresh PImage.
void	imageMode(int mode) The mode can only be set to CORNERS or CORNER, because the others are just too weird for the other functions.
void	init(int width, int height, int format) Function to be used by subclasses to setup their own bidness.
void	loadPixels() Call this when you want to mess with the pixels[] array.
void	mask(int[] alpha) Set alpha channel for an image.
void	mask(PImage alpha) Set alpha channel for an image using another image as the source.
void	noSmooth() Disable smoothing.
void	save(java.lang.String path) Save this image to disk.
void	set(int x, int y, int c) Silently ignores if the coordinate is outside the image.
void	set(int dx, int dy, PImage src)
void	smooth() If true in PImage, use bilinear interpolation for copy() operations.
void	updatePixels() Call this when finished messing with the pixels[] array.
void	updatePixels(int x1, int y1, int x2, int y2) Mark the pixels in this region as needing an update.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

format

public int format

Format for this image, one of RGB, ARGB or ALPHA. note that RGB images still require 0xff in the high byte because of how they'll be manipulated by other functions

pixels

public int[] pixels

width

public int width

height

public int height

parent

public PApplet parent

Path to parent object that will be used with save(). This prevents users from needing savePath() to use PImage.save().

imageMode

public int imageMode

smooth

public boolean smooth

cache

public java.lang.Object cache

for subclasses that need to store info about the image

modified

public boolean modified

modified portion of the image

mx1

public int mx1

my1

public int my1

mx2

public int mx2

my2

public int my2

Constructor Detail

PImage

public PImage()

Create an empty image object, set its format to RGB. The pixel array is not allocated.

PImage

public PImage(int width,
              int height)

Create a new RGB (alpha ignored) image of a specific size. All pixels are set to zero, meaning black, but since the alpha is zero, it will be transparent.

PImage

public PImage(int width,
              int height,
              int format)

PImage

public PImage(java.awt.Image img)

Construct a new PImage from a java.awt.Image. This constructor assumes that you've done the work of making sure a MediaTracker has been used to fully download the data and that the img is valid.

Method Detail

init

public void init(int width,
                 int height,
                 int format)

Function to be used by subclasses to setup their own bidness. Used by Capture and Movie classes (and perhaps others), because the width/height will not be known when super() is called.

imageMode

public void imageMode(int mode)

The mode can only be set to CORNERS or CORNER, because the others are just too weird for the other functions. Do you really want to use get() or copy() with imageMode(CENTER)?

smooth

public void smooth()

If true in PImage, use bilinear interpolation for copy() operations. When inherited by PGraphics, also controls shapes.

noSmooth

public void noSmooth()

Disable smoothing. See smooth().

loadPixels

public void loadPixels()

Call this when you want to mess with the pixels[] array.

For subclasses where the pixels[] buffer isn't set by default, this should copy all data into the pixels[] array

updatePixels

public void updatePixels()

Call this when finished messing with the pixels[] array.

Mark all pixels as needing update.

updatePixels

public void updatePixels(int x1,
                         int y1,
                         int x2,
                         int y2)

Mark the pixels in this region as needing an update.

This is not currently used by any of the renderers, however the api is structured this way in the hope of being able to use this to speed things up in the future.

Note that when using imageMode(CORNERS), the x2 and y2 positions are non-inclusive.

get

public int get(int x,
               int y)

Returns an ARGB "color" type (a packed 32 bit int with the color. If the coordinate is outside the image, zero is returned (black, but completely transparent).

If the image is in RGB format (i.e. on a PVideo object), the value will get its high bits set, just to avoid cases where they haven't been set already.

If the image is in ALPHA format, this returns a white with its alpha value set.

This function is included primarily for beginners. It is quite slow because it has to check to see if the x, y that was provided is inside the bounds, and then has to check to see what image type it is. If you want things to be more efficient, access the pixels[] array directly.

get

public PImage get(int x,
                  int y,
                  int w,
                  int h)

Grab a subsection of a PImage, and copy it into a fresh PImage. This honors imageMode() for the coordinates.

get

public PImage get()

Returns a copy of this PImage. Equivalent to get(0, 0, width, height).

set

public void set(int x,
                int y,
                int c)

Silently ignores if the coordinate is outside the image.

set

public void set(int dx,
                int dy,
                PImage src)

mask

public void mask(int[] alpha)

Set alpha channel for an image. Black colors in the source image will make the destination image completely transparent, and white will make things fully opaque. Gray values will be in-between steps.

Strictly speaking the "blue" value from the source image is used as the alpha color. For a fully grayscale image, this is correct, but for a color image it's not 100% accurate. For a more accurate conversion, first use filter(GRAY) which will make the image into a "correct" grayscake by performing a proper luminance-based conversion.

mask

public void mask(PImage alpha)

Set alpha channel for an image using another image as the source.

filter

public void filter(int kind)

Method to apply a variety of basic filters to this image.

• filter(BLUR) provides a basic blur.
• filter(GRAY) converts the image to grayscale based on luminance.
• filter(INVERT) will invert the color components in the image.
• filter(OPAQUE) set all the high bits in the image to opaque
• filter(THRESHOLD) converts the image to black and white.
• filter(DILATE) grow white/light areas
• filter(ERODE) shrink white/light areas

Luminance conversion code contributed by toxi

Gaussian blur code contributed by Mario Klingemann

filter

public void filter(int kind,
                   float param)

Method to apply a variety of basic filters to this image. These filters all take a parameter.

• filter(BLUR, int radius) performs a gaussian blur of the specified radius.
• filter(POSTERIZE, int levels) will posterize the image to between 2 and 255 levels.
• filter(THRESHOLD, float center) allows you to set the center point for the threshold. It takes a value from 0 to 1.0.

Gaussian blur code contributed by Mario Klingemann and later updated by toxi for better speed.

copy

public void copy(int sx1,
                 int sy1,
                 int sx2,
                 int sy2,
                 int dx1,
                 int dy1,
                 int dx2,
                 int dy2)

Copy things from one area of this image to another area in the same image.

copy

public void copy(PImage src,
                 int sx1,
                 int sy1,
                 int sx2,
                 int sy2,
                 int dx1,
                 int dy1,
                 int dx2,
                 int dy2)

Copies area of one image into another PImage object.

blendColor

public static int blendColor(int c1,
                             int c2,
                             int mode)

Blend two colors based on a particular mode.

• REPLACE - destination colour equals colour of source pixel: C = A. Sometimes called "Normal" or "Copy" in other software.
• BLEND - linear interpolation of colours: C = A*factor + B
• ADD - additive blending with white clip: C = min(A*factor + B, 255). Clipped to 0..255, Photoshop calls this "Linear Burn", and Director calls it "Add Pin".
• SUBTRACT - substractive blend with black clip: C = max(B - A*factor, 0). Clipped to 0..255, Photoshop calls this "Linear Dodge", and Director calls it "Subtract Pin".
• DARKEST - only the darkest colour succeeds: C = min(A*factor, B). Illustrator calls this "Darken".
• LIGHTEST - only the lightest colour succeeds: C = max(A*factor, B). Illustrator calls this "Lighten".
• DIFFERENCE - subtract colors from underlying image.
• EXCLUSION - similar to DIFFERENCE, but less extreme.
• MULTIPLY - Multiply the colors, result will always be darker.
• SCREEN - Opposite multiply, uses inverse values of the colors.
• OVERLAY - A mix of MULTIPLY and SCREEN. Multiplies dark values, and screens light values.
• HARD_LIGHT - SCREEN when greater than 50% gray, MULTIPLY when lower.
• SOFT_LIGHT - Mix of DARKEST and LIGHTEST. Works like OVERLAY, but not as harsh.
• DODGE - Lightens light tones and increases contrast, ignores darks. Called "Color Dodge" in Illustrator and Photoshop.
• BURN - Darker areas are applied, increasing contrast, ignores lights. Called "Color Burn" in Illustrator and Photoshop.

A useful reference for blending modes and their algorithms can be found in the SVG specification.

It is important to note that Processing uses "fast" code, not necessarily "correct" code. No biggie, most software does. A nitpicker can find numerous "off by 1 division" problems in the blend code where >>8 or >>7 is used when strictly speaking /255.0 or /127.0 should have been used.

For instance, exclusion (not intended for real-time use) reads r1 + r2 - ((2 * r1 * r2) / 255) because 255 == 1.0 not 256 == 1.0. In other words, (255*255)>>8 is not the same as (255*255)/255. But for real-time use the shifts are preferrable, and the difference is insignificant for applications built with Processing.

blend

public void blend(int sx1,
                  int sy1,
                  int sx2,
                  int sy2,
                  int dx1,
                  int dy1,
                  int dx2,
                  int dy2,
                  int mode)

Blends one area of this image to another area.

See Also:

blendColor(int,int,int)

blend

public void blend(PImage src,
                  int sx1,
                  int sy1,
                  int sx2,
                  int sy2,
                  int dx1,
                  int dy1,
                  int dx2,
                  int dy2,
                  int mode)

Copies area of one image into another PImage object.

See Also:

blendColor(int,int,int)

clone

public java.lang.Object clone()
                       throws java.lang.CloneNotSupportedException

Duplicate an image, returns new PImage object. The pixels[] array for the new object will be unique and recopied from the source image. This is implemented as an override of Object.clone(). We recommend using get() instead, because it prevents you from needing to catch the CloneNotSupportedException, and from doing a cast from the result.

Throws:

java.lang.CloneNotSupportedException

save

public void save(java.lang.String path)

Save this image to disk.

As of revision 0100, this function requires an absolute path, in order to avoid confusion. To save inside the sketch folder, use the function savePath() from PApplet, or use saveFrame() instead.

As of revision 0115, when using Java 1.4 and later, you can write to several formats besides tga and tiff. If Java 1.4 is installed and the extension used is supported (usually png, jpg, jpeg, bmp, and tiff), then those methods will be used to write the image. To get a list of the supported formats for writing, use:
println(javax.imageio.ImageIO.getReaderFormatNames())

To use the original built-in image writers, use .tga as the extension, or don't include an extension, in which case .tif will be added.

The ImageIO API claims to support wbmp files, however they probably require a black and white image. Basic testing produced a zero-length file with no error.

As of revision 0116, savePath() is not needed if this object has been created (as recommended) via createImage() or createGraphics() or one of its neighbors.