PixelSet (OpenIMAJ master project 1.3.1 API)

java.lang.Object
- org.openimaj.image.pixel.PixelSet

All Implemented Interfaces:

Cloneable, Iterable<Pixel>, Readable, ReadableASCII, ReadableBinary, ReadWriteable, Writeable, WriteableASCII, WriteableBinary

Direct Known Subclasses:

ConnectedComponent
```
public class PixelSet
extends Object
implements Cloneable, ReadWriteable, Iterable<Pixel>
```
A set of (not-necessarily connected) pixels within an image. This class provides a number of utility functions for working with and analysing the pixels.

Author:

Jonathon Hare (jsh2@ecs.soton.ac.uk)

Field Summary

Fields
Modifier and Type Field and Description

Set<Pixel> pixels
The set of pixels within this connected component

Fields
Modifier and Type	Field and Description
`Set<Pixel>`	`pixels` The set of pixels within this connected component

Constructor Summary

Constructors
Constructor and Description
`PixelSet()` Default constructor; makes an empty PixelSet
`PixelSet(FImage mask, float thresh)` Constructs a PixelSet from a mask image.
`PixelSet(int[][] img)` Constructs a PixelSet from a mask image.
`PixelSet(int x, int y, int w, int h)` Construct a rectangular `PixelSet`.
`PixelSet(Set<Pixel> pixels)` Construct a PixelSet from the given set of `Pixel`s.

Method Summary

Methods
Modifier and Type	Method and Description
`void`	`addPixel(int x, int y)` Add a pixel into this connected component.
`void`	`addPixel(Pixel p)` Add a pixel into this connected component.
`String`	`asciiHeader()` Header for ascii input.
`byte[]`	`binaryHeader()` Header for binary input.
`Pixel`	`bottomRightMostPixel()` Gets the bottom-right most pixel in the connected component.
`int`	`calculateArea()` Calculate the area of this connected component in pixels.
`double[]`	`calculateAverageHeightWidth()` Calculate the height and width of a box surrounding the component by averaging the distances of pixels above and below the centroid.
`double[]`	`calculateAverageHeightWidth(double[] centroid)` Calculate the height and width of a box surrounding the component by averaging the distances of pixels above and below the centroid.
`FImage`	`calculateBinaryMask(Image<?,?> input)` Returns an image where the connected component is masked in the image.
`double[]`	`calculateCentroid()` Calculate the centroid of the connected component.
`Pixel`	`calculateCentroidPixel()` Calculates the centroid pixel of the connected component.
`double`	`calculateDirection()` Calculates the principle direction of the connected component.
`double`	`calculateMoment(int p, int q)` Calculate the pq central moment, μ_pq for this region.
`double`	`calculateMoment(int p, int q, double xc, double yc)` Calculate the pq moment, μ_pq around the given centroid.
`double`	`calculateMomentNormalised(int p, int q)` Calculate the normalized, unscaled, central moments η_pq.
`Rectangle`	`calculateRegularBoundingBox()` Calculate the regular bounding box of the region by calculating the maximum and minimum x and y coordinates of the pixels contained within the region.
`double`	`calculateRegularBoundingBoxAspectRatio()` Compute the aspect ratio of the regular bounding box.
`MBFImage`	`crop(MBFImage input, boolean blackout)` Returns an image containing just the connected component cropped from the original image.
`FImage`	`extractPixels1d(FImage input)` Extract a 1 x area image with all the pixels from the region in it.
`MBFImage`	`extractPixels1d(MBFImage input)` Extract a 1xarea image with all the pixels from the region in it.
`MBFImage`	`extractPixels2d(MBFImage input, boolean blackout)` This is a convenience method that simply calls `crop(MBFImage, boolean)`
`boolean`	`find(int x, int y)` Returns whether the given coordinates are within this connected component.
`boolean`	`find(Pixel p)` Returns whether the given pixel is within this connected component.
`protected void`	`fromShape(Shape shape)`
`Set<Pixel>`	`getPixels()` Returns the set of `Pixel`s that are within this component.
`Iterator<Pixel>`	`iterator()`
`void`	`merge(ConnectedComponent c)` Shallow copies the pixels from the given `ConnectedComponent` into this object.
`Jama.Matrix`	`normMatrix()` Returns a normalisation matrix for this component.
`void`	`readASCII(Scanner in)` Read internal state from in.
`void`	`readBinary(DataInput in)` Read internal state from in.
`void`	`reposition()` Repositions the connected component so that its bounding box has its origin at (0,0).
`FImage`	`toFImage()` Returns a mask image for this connected component that will be the size of this component's bounding box.
`FImage`	`toFImage(int padding)` Returns a mask image for this connected component that will be the size of this component's bounding box plus a border of the given amount of padding.
`Pixel`	`topLeftMostPixel()` Gets the top-left most pixel within the connected component.
`String`	`toString()`
`String`	`toStringImage()` Returns an ASCII representation of the connected component as a mask; where the output is "1" for a pixel within the mask and "0" for a pixel outside of the mask.
`void`	`transform(Jama.Matrix transform)` Affine transform the shape with the given transform matrix.
`void`	`translate(int x, int y)` Translates the region's pixels by x and y.
`void`	`writeASCII(PrintWriter out)` Write the content of this as ascii to out.
`void`	`writeBinary(DataOutput out)` Write the content of this as binary to out.

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

- Field Detail
  - pixels
```
public Set<Pixel> pixels
```
    The set of pixels within this connected component
- Constructor Detail
  - PixelSet
```
public PixelSet()
```
    Default constructor; makes an empty PixelSet
  - PixelSet
```
public PixelSet(int x,
        int y,
        int w,
        int h)
```
    Construct a rectangular PixelSet. Pixels are created for the area within the rectangle but these will not have any specific value as they are not associated to any particular image.
    
    Parameters:
    x - The top-left x-coordinate of the rectangle
    y - The top-left y-coordinate of the rectangle
    w - The width of the rectangle
    h - The height of the rectangle
  - PixelSet
```
public PixelSet(int[][] img)
```
    Constructs a PixelSet from a mask image. Pixels are created for areas within the mask image that are non-zero. Note that this may result in a connected component definition that is unconnected and some methods may not return expected results.
    
    Parameters:
    img - The mask image to construct a connected component from.
  - PixelSet
```
public PixelSet(FImage mask,
        float thresh)
```
    Constructs a PixelSet from a mask image. Pixels are created for areas within the mask image that are above the given threshold. Note that this may result in a connected component definition that is unconnected and some methods may not return expected results.
    
    Parameters:
    mask - The mask image to construct a connected component from.
    thresh - the threshold value.
  - PixelSet
```
public PixelSet(Set<Pixel> pixels)
```
    Construct a PixelSet from the given set of Pixels. The pixels are shallow copied into the connected component. If the pixels do not form a connected component then some methods in this class may not return expected results.
    
    Parameters:
    pixels - A Set of Pixels.
- Method Detail
  - fromShape
```
protected void fromShape(Shape shape)
```
  - addPixel
```
public void addPixel(int x,
            int y)
```
    Add a pixel into this connected component. If the pixel is not adjacent to another pixel within this connected component, then some methods may return unexpected results. Side-affects this object.
    
    Parameters:
    x - The x-coordinate of the pixel to add
    y - The y-coordinate of the pixel to add
  - addPixel
```
public void addPixel(Pixel p)
```
    Add a pixel into this connected component. If the pixel is not adjacent to another pixel within this connected component, then some methods may return unexpected results. Side-affects this object.
    
    Parameters:
    p - The pixel to add
  - getPixels
```
public Set<Pixel> getPixels()
```
    Returns the set of Pixels that are within this component.
    
    Returns:
    the set of Pixels that are within this component.
  - merge
```
public void merge(ConnectedComponent c)
```
    Shallow copies the pixels from the given ConnectedComponent into this object. If the pixels that are added are not adjacent to other pixels within the component some methods may return unexpected results. Side-affects this object.
    
    Parameters:
    c - The ConnectedComponent to copy pixels from.
  - find
```
public boolean find(Pixel p)
```
    Returns whether the given pixel is within this connected component. This is synonymous to getPixels().contains(p).
    
    Parameters:
    p - The pixel to find.
    
    Returns:
    TRUE if the pixel is contained within this component; FALSE otherwise
  - find
```
public boolean find(int x,
           int y)
```
    Returns whether the given coordinates are within this connected component. This is synonymous with find( new Pixel(x,y) ).
    
    Parameters:
    x - The x-coordinate of the pixel to find
    y - The y-coordinate of the pixel to find
    
    Returns:
    TRUE if the pixel is contained within this component; FALSE otherwise
  - calculateArea
```
public int calculateArea()
```
    Calculate the area of this connected component in pixels. This is synonymous with getPixels.size()
    
    Returns:
    the number of pixels covered by this connected component.
  - calculateMoment
```
public double calculateMoment(int p,
                     int q,
                     double xc,
                     double yc)
```
    Calculate the pq moment, μ_pq around the given centroid. From Equation 6.44 in Sonka, Hlavac and Boyle. If instead of giving the centroid (xc, yc), you give (0,0), then this will return the standard moments m_pq about the origin.
    
    Parameters:
    p - The P moment to calculate
    q - The Q moment to calculate
    xc - x-coordinate of centroid
    yc - y-coordinate of centroid
    
    Returns:
    The pq moment, M_pq.
  - calculateMoment
```
public double calculateMoment(int p,
                     int q)
```
    Calculate the pq central moment, μ_pq for this region. From Equation 6.44 in Sonka, Hlavac and Boyle.
    
    Parameters:
    p - The P moment to calculate
    q - The Q moment to calculate
    
    Returns:
    The pq moment, M_pq.
  - calculateMomentNormalised
```
public double calculateMomentNormalised(int p,
                               int q)
```
    Calculate the normalized, unscaled, central moments η_pq. From Equation 6.47 in Sonka, Hlavac and Boyle [1st Ed.]. Normalised central moments are invariant to scale and translation.
    
    Parameters:
    p - The P moment to calculate
    q - The Q moment to calculate
    
    Returns:
    The normalised, unscaled central moment, M_pq.
  - calculateDirection
```
public double calculateDirection()
```
    Calculates the principle direction of the connected component. This is given by 0.5 * atan( (M₂₀-M₀₂) / 2 * M₁₁ ) so results in an angle between -PI and +PI.
    
    Returns:
    The principle direction (-PI/2 to +PI/2 radians) of the connected component.
  - calculateCentroid
```
public double[] calculateCentroid()
```
    Calculate the centroid of the connected component. This is the average of all the pixel coordinates in the component. The result is returned in a double array where the the first index is the x-coordinate and second is the y-coordinate.
    
    Returns:
    The centroid point as a double array (x then y).
  - calculateCentroidPixel
```
public Pixel calculateCentroidPixel()
```
    Calculates the centroid pixel of the connected component. That is, the centroid value is rounded to the nearest pixel.
    
    Returns:
    A Pixel at the centroid.
  - calculateAverageHeightWidth
```
public double[] calculateAverageHeightWidth(double[] centroid)
```
    Calculate the height and width of a box surrounding the component by averaging the distances of pixels above and below the centroid. The result is a double array where the first index is the height and the second is the width.
    
    Parameters:
    centroid - The centroid of the component.
    
    Returns:
    average height and width as a double array.
  - calculateAverageHeightWidth
```
public double[] calculateAverageHeightWidth()
```
    Calculate the height and width of a box surrounding the component by averaging the distances of pixels above and below the centroid. The result is a double array where the first index is the height and the second is the width.
    
    Returns:
    average height and width as a double array.
  - calculateRegularBoundingBoxAspectRatio
```
public double calculateRegularBoundingBoxAspectRatio()
```
    Compute the aspect ratio of the regular bounding box.
    
    Returns:
    the aspect ratio of the regular bounding box.
  - calculateRegularBoundingBox
```
public Rectangle calculateRegularBoundingBox()
```
    Calculate the regular bounding box of the region by calculating the maximum and minimum x and y coordinates of the pixels contained within the region. The result is an integer array containing the (x,y) coordinate of the top-left of the bounding box, and the width and height of the bounding box.
    
    Returns:
    an Rectangle describing the bounds
  - translate
```
public void translate(int x,
             int y)
```
    Translates the region's pixels by x and y. This method side-affects the pixels in this object.
    
    Parameters:
    x - The offset in the horizontal direction
    y - The offset in the vertical direction.
  - topLeftMostPixel
```
public Pixel topLeftMostPixel()
```
    Gets the top-left most pixel within the connected component.
    
    Returns:
    the top-left most pixel within the connected component.
  - bottomRightMostPixel
```
public Pixel bottomRightMostPixel()
```
    Gets the bottom-right most pixel in the connected component.
    
    Returns:
    the bottom-right most pixel in the connected component.
  - toString
```
public String toString()
```
    Overrides:
    
    toString in class Object
    
    See Also:
    Object.toString()
  - extractPixels1d
```
public MBFImage extractPixels1d(MBFImage input)
```
    Extract a 1xarea image with all the pixels from the region in it. Useful for analysing the colour for example
    
    Parameters:
    input - input image to extract samples from
    
    Returns:
    new image with pixels set from samples
  - extractPixels1d
```
public FImage extractPixels1d(FImage input)
```
    Extract a 1 x area image with all the pixels from the region in it. Useful for analysing the colour for example
    
    Parameters:
    input - image to extract pixel values from
    
    Returns:
    new image filled with pixel values
  - crop
```
public MBFImage crop(MBFImage input,
            boolean blackout)
```
    Returns an image containing just the connected component cropped from the original image. Although that the result image is necessarily rectangular, the pixels which are not part of the connected component will be transparent.
    
    Parameters:
    input - The input image from which to take the pixels
    blackout - Whether to blackout pixels that are not part of the region or whether to mark them as transparent
    
    Returns:
    An image with the component's pixels cropped
  - extractPixels2d
```
public MBFImage extractPixels2d(MBFImage input,
                       boolean blackout)
```
    This is a convenience method that simply calls crop(MBFImage, boolean)
    
    Parameters:
    input - The input image from which to take the pixels
    blackout - Whether to blackout pixels that are not part of the region or whether to mark them as transparent
    
    Returns:
    An image with the component's pixels cropped
  - calculateBinaryMask
```
public FImage calculateBinaryMask(Image<?,?> input)
```
    Returns an image where the connected component is masked in the image. The image is the same size as the image that is passed in.
    
    Parameters:
    input - The input image from which to take the size.
    
    Returns:
    An FImage containing a binary mask; pixels within the connected component will have value 1, outside with have value 0
  - toStringImage
```
public String toStringImage()
```
    Returns an ASCII representation of the connected component as a mask; where the output is "1" for a pixel within the mask and "0" for a pixel outside of the mask.
    
    Returns:
    An image string.
  - reposition
```
public void reposition()
```
    Repositions the connected component so that its bounding box has its origin at (0,0). Side-affects this connected component.
  - toFImage
```
public FImage toFImage()
```
    Returns a mask image for this connected component that will be the size of this component's bounding box. Pixels within the component will be set to value 1.0, while pixels outside of the component will retain their initial value.
    
    Returns:
    An FImage mask image
  - toFImage
```
public FImage toFImage(int padding)
```
    Returns a mask image for this connected component that will be the size of this component's bounding box plus a border of the given amount of padding. Pixels within the component will be set to value 1.0, while pixels outside of the component will retain their initial value.
    
    Parameters:
    padding - The number of pixels padding to add around the outside of the mask.
    
    Returns:
    An FImage mask image
  - transform
```
public void transform(Jama.Matrix transform)
```
    Affine transform the shape with the given transform matrix. Side-affects this component.
    
    Parameters:
    transform - The matrix containing the transform.
  - normMatrix
```
public Jama.Matrix normMatrix()
```
    Returns a normalisation matrix for this component.
    
    Returns:
    A normalisation matrix.
  - readASCII
```
public void readASCII(Scanner in)
               throws IOException
```
    Description copied from interface: ReadableASCII
    
    Read internal state from in.
    
    Specified by:
    
    readASCII in interface ReadableASCII
    
    Parameters:
    in - source to read from.
    
    Throws:
    
    IOException - an error reading input
  - readBinary
```
public void readBinary(DataInput in)
                throws IOException
```
    Description copied from interface: ReadableBinary
    
    Read internal state from in.
    
    Specified by:
    
    readBinary in interface ReadableBinary
    
    Parameters:
    in - source to read from.
    
    Throws:
    
    IOException - an error reading input
  - asciiHeader
```
public String asciiHeader()
```
    Description copied from interface: ReadableASCII
    
    Header for ascii input. Will be automatically read by IOUtils when using readASCII().
    
    Specified by:
    
    asciiHeader in interface ReadableASCII
    
    Specified by:
    
    asciiHeader in interface WriteableASCII
    
    Returns:
    header
  - binaryHeader
```
public byte[] binaryHeader()
```
    Description copied from interface: ReadableBinary
    
    Header for binary input. Will be automatically read by IOUtils when using readBinary().
    
    Specified by:
    
    binaryHeader in interface ReadableBinary
    
    Specified by:
    
    binaryHeader in interface WriteableBinary
    
    Returns:
    header
  - writeASCII
```
public void writeASCII(PrintWriter out)
                throws IOException
```
    Description copied from interface: WriteableASCII
    
    Write the content of this as ascii to out.
    
    Specified by:
    
    writeASCII in interface WriteableASCII
    
    Parameters:
    out - sink to write to
    
    Throws:
    
    IOException - an error writing to out
  - writeBinary
```
public void writeBinary(DataOutput out)
                 throws IOException
```
    Description copied from interface: WriteableBinary
    
    Write the content of this as binary to out.
    
    Specified by:
    
    writeBinary in interface WriteableBinary
    
    Parameters:
    out - sink to write to
    
    Throws:
    
    IOException - an error writing to out
  - iterator
```
public Iterator<Pixel> iterator()
```
    Specified by:
    
    iterator in interface Iterable<Pixel>

Class PixelSet

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

pixels

Constructor Detail

PixelSet

PixelSet

PixelSet

PixelSet

PixelSet

Method Detail

fromShape

addPixel

addPixel

getPixels

merge

find

find

calculateArea

calculateMoment

calculateMoment

calculateMomentNormalised

calculateDirection

calculateCentroid

calculateCentroidPixel

calculateAverageHeightWidth

calculateAverageHeightWidth

calculateRegularBoundingBoxAspectRatio

calculateRegularBoundingBox

translate

topLeftMostPixel

bottomRightMostPixel

toString

extractPixels1d

extractPixels1d

crop

extractPixels2d

calculateBinaryMask

toStringImage

reposition

toFImage

toFImage

transform

normMatrix

readASCII

readBinary

asciiHeader

binaryHeader

writeASCII

writeBinary

iterator