# Class Pixers

java.lang.Object
uk.ac.starlink.ttools.plot2.layer.Pixers

public class Pixers extends Object
Utility class for use with Pixers.

Since:
  27 Nov 2013
Author:
  Mark Taylor

## Field Summary

Fields
Modifier and Type
Field
Description
`static final Pixer`
`EMPTY`
Pixer with no pixels.

## Method Summary

Modifier and Type
Method
Description
`static Pixer`
`clip(Pixer base, Rectangle clip)`
Returns a clipped version of a given pixel iterator whose extent is not known.
`static Pixer`
`clip(Pixer base, Rectangle clip, int xminBase, int xmaxBase, int yminBase, int ymaxBase)`
Returns a clipped version of a given pixel iterator whose extent is known.
`static PixelDrawing`
`convolve(PixerFactory shape, PixerFactory kernel, Rectangle clip)`
Convolves two PixerFactories together, which can be used for instance to apply a smoothing kernel to a given shape.
`static PixerFactory`
`copy(PixerFactory base)`
Returns an efficient copy of the given factory.
`static Pixer`
`createArrayPixer(int[] xs, int[] ys, int np)`
Returns a new pixer that iterates over a given list of X,Y coordinates.
`static Pixer`
`createClippedPixer(PixerFactory pfact, Rectangle clip)`
Returns a pixer that results from applying a clip rectangle to the output of a given PixerFactory.
`static PixerFactory`
`createPixerCopier(Pixer pixer)`
Takes a given pixer and copies its data, returning an object that can issue pixers that behave the same as the original.
`static Pixer`
`createPointsPixer(Point[] points)`
Returns a new pixer that iterates over an array of Points.
`static Pixer`
`translate(Pixer base, int tx, int ty)`
Returns a translated version of a pixel iterator.

### Methods inherited from class Object

`clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

## Field Details

### EMPTY

public static final Pixer EMPTY
Pixer with no pixels.

## Method Details

### createArrayPixer

public static Pixer createArrayPixer(int[] xs, int[] ys, int np)
Returns a new pixer that iterates over a given list of X,Y coordinates.

Parameters:
  `xs` - array of X values
  `ys` - array of Y values
  `np` - number of points (xs and ys must be at least this length)
Returns:
  new pixel iterator

### createPointsPixer

public static Pixer createPointsPixer(Point[] points)
Returns a new pixer that iterates over an array of Points. Iteration is done in place, so the content of these points should not be altered for the lifetime of this pixer.

Parameters:
  `points` - point array
Returns:
  pixel iterator

### copy

public static PixerFactory copy(PixerFactory base)
Returns an efficient copy of the given factory. This may be suitable if it is known that many copies will be required of a Pixer.

Parameters:
  `base` - base implementation
Returns:
  new PixerFactory functionally equivalent to base implementation

### createPixerCopier

public static PixerFactory createPixerCopier(Pixer pixer)
Takes a given pixer and copies its data, returning an object that can issue pixers that behave the same as the original. Since pixers are one-use iterators, this may be a useful caching operation for pixer generation methods that are potentially expensive to create and may be consumed multiple times.

Parameters:
  `pixer` - input pixer
Returns:
  factory to create copies of pixer

### translate

public static Pixer translate(Pixer base, int tx, int ty)
Returns a translated version of a pixel iterator.

Parameters:
  `base` - base pixel iterator
  `tx` - offset in X direction
  `ty` - offset in Y direction
Returns:
  translated pixel iterator

### clip

public static Pixer clip(Pixer base, Rectangle clip)
Returns a clipped version of a given pixel iterator whose extent is not known.

Parameters:
  `base` - base pixel iterator
  `clip` - clipping rectangle
Returns:
  clipped pixel iterator

### createClippedPixer

public static Pixer createClippedPixer(PixerFactory pfact, Rectangle clip)
Returns a pixer that results from applying a clip rectangle to the output of a given PixerFactory.

Parameters:
  `pfact` - pixer factory
  `clip` - clipping rectangle
Returns:
  pixer contiaining only points within the clip, or null if no points fall within it

### clip

public static Pixer clip(Pixer base, Rectangle clip, int xminBase, int xmaxBase, int yminBase, int ymaxBase)
Returns a clipped version of a given pixel iterator whose extent is known. May return null if the clipped pixer would dispense no pixels. {x,y}{min,max}Base are the extreme values of the base pixer; they do not account for the extent of a single pixel (so a single pixel at the origin would have all values set to zero).

Parameters:
  `base` - base pixel iterator
  `clip` - clipping rectangle
  `xminBase` - lower limit of X values dispensed by base pixer
  `xmaxBase` - upper limit of X values dispensed by base pixer
  `yminBase` - lower limit of Y values dispensed by base pixer
  `ymaxBase` - upper limit of Y values dispensed by base pixer
Returns:
  clipped pixel iterator, or null if no pixels

### convolve

public static PixelDrawing convolve(PixerFactory shape, PixerFactory kernel, Rectangle clip)
Convolves two PixerFactories together, which can be used for instance to apply a smoothing kernel to a given shape. The output will paint only within a given clipping region.

Parameters:
  `shape` - first supplier of pixels
  `kernel` - second supplier of pixels
  `clip` - clipping rectangle for output
Returns:
  convolution pixel supplier