Package net.sourceforge.jiu.ops

# Class ImageToImageOperation

java.lang.Object
net.sourceforge.jiu.ops.Operation
net.sourceforge.jiu.ops.ImageToImageOperation

Direct Known Subclasses:
  `ArbitraryPaletteQuantizer`, `AreaFilterOperation`, `ClusteredDotDither`, `ConvolutionKernelFilter`, `Crop`, `ErrorDiffusionDithering`, `Flip`, `HueSaturationValue`, `Invert`, `LookupTableOperation`, `MedianCutContourRemoval`, `MedianCutQuantizer`, `Mirror`, `OctreeColorQuantizer`, `OrderedDither`, `PopularityQuantizer`, `PromotionGray16`, `PromotionGray8`, `PromotionPaletted8`, `PromotionRGB24`, `PromotionRGB48`, `ReduceRGB`, `ReduceShadesOfGray`, `ReduceToBilevelThreshold`, `Resample`, `RGBToGrayConversion`, `Rotate180`, `Rotate90Left`, `Rotate90Right`, `ScaleReplication`, `Shear`, `UniformPaletteQuantizer`

public abstract class ImageToImageOperation extends Operation
An operation that acesses an input image and produces data for an output image. This abstract class only provides methods to get and set those images.

Normally, an operation creates the output image itself. However, an output image can be specified by the user with `setOutputImage(net.sourceforge.jiu.data.PixelImage)`. This could be done when existing image objects are to be reused.

An operation extending ImageToImageOperation must check if (1) a user-defined output image is available and (2) whether that image matches the required criteria. The criteria depend on the operation - example: for an operation that rotates an image by 180 degrees, an output image must have the same resolution as the input image and be of the same type.

If an output image is not available (case #1), the operation must create the matching output image itself. It should know best what is required. Very generic methods (like rotation of images by 90 degrees) must know relatively little about the image. They can make use of PixelImage.createCompatibleImage(int, int) and provide width and height. That way, the operation works for all kinds of images, like BilevelImage, Paletted8Image, Gray8Image, RGB24Image etc.

If a user-provided image does not match the required criteria, an appropriate exception (most of the time `WrongParameterException` will do) with a descriptive error message must be thrown. In the example of the 90-degree rotation, the width of the output image must be equal to the height of the input image and vice versa. The types of input and output must be equal.

However, there are limits to the checks on user-provided output images. As an example, a generic test could not check if a paletted output image has the same palette as the input counterpart because it treats all images based on IntegerImage the same.

When performing an image-to-image-operation, the input image can possibly be used as the output image. This can be done

- if input and output are of the same type and resolution and
- if the operation needs only one input pixel to compute the output pixel at any given position.

Mirroring the image horizontally is an example of an operation that can be implemented that way - the operation starts at the top left and at the bottom right pixel, swaps them and proceeds one pixel to the right of the top left pixel (and one to the left of the bottom right pixel).

Since:
  0.6.0
Author:
  Marco Schmidt

## Field Summary

Fields
Modifier and Type
Field
Description
`private boolean`
`canInAndOutBeEqual`
`private PixelImage`
`inputImage`
`private PixelImage`
`outputImage`

## Constructor Summary

Constructors
Constructor
Description
`ImageToImageOperation()`
Creates an object of this class and sets both input image and output image to `null`.
`ImageToImageOperation(PixelImage in)`
Creates an object of this class and sets the input image to the argument value, output image to `null`.
`ImageToImageOperation(PixelImage in, PixelImage out)`
Creates an object of this class and sets input image and output image to the argument values.

## Method Summary

Modifier and Type
Method
Description
`boolean`
`canInputAndOutputBeEqual()`
Returns if input and output image are allowed to be the same object.
`void`
`ensureImagesHaveSameResolution()`
If both an input and an output image have been specified (both non-null), this method compares their width and height properties and throws an exception if the two images do not have the same resolution.
`void`
`ensureInputImageIsAvailable()`
If `getInputImage()` returns `null` this method throws a `MissingParameterException` complaining that an input image is missing.
`void`
`ensureOutputImageResolution(int width, int height)`
If an output image has been specified this method will compare its resolution with the argument resolution and throw an exception if the resolutions differ.
`PixelImage`
`getInputImage()`
Returns the input image stored in this object.
`PixelImage`
`getOutputImage()`
Returns the output image stored in this object.
`void`
`setCanInputAndOutputBeEqual(boolean newValue)`
Specify if input and output image are allowed to be the same object.
`void`
`setInputImage(PixelImage in)`
Sets the input image stored in this object to the argument.
`void`
`setOutputImage(PixelImage out)`
Sets the output image stored in this object to the argument.

### Methods inherited from class net.sourceforge.jiu.ops.Operation

`addProgressListener, addProgressListeners, getAbort, process, removeProgressListener, setAbort, setProgress, setProgress`

### Methods inherited from class java.lang.Object

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

## Field Details

### inputImage

private PixelImage inputImage

### outputImage

private PixelImage outputImage

### canInAndOutBeEqual

private boolean canInAndOutBeEqual

## Constructor Details

### ImageToImageOperation

public ImageToImageOperation(PixelImage in, PixelImage out)
Creates an object of this class and sets input image and output image to the argument values.

### ImageToImageOperation

public ImageToImageOperation(PixelImage in)
Creates an object of this class and sets the input image to the argument value, output image to `null`.

### ImageToImageOperation

public ImageToImageOperation()
Creates an object of this class and sets both input image and output image to `null`.

## Method Details

### canInputAndOutputBeEqual

public boolean canInputAndOutputBeEqual()
Returns if input and output image are allowed to be the same object.

See Also:
  - `setCanInputAndOutputBeEqual(boolean)`

### ensureImagesHaveSameResolution

public void ensureImagesHaveSameResolution() throws WrongParameterException
If both an input and an output image have been specified (both non-null), this method compares their width and height properties and throws an exception if the two images do not have the same resolution.

Throws:
  `WrongParameterException` - if input and output images exist and their resolutions differ

### ensureInputImageIsAvailable

public void ensureInputImageIsAvailable() throws MissingParameterException
If `getInputImage()` returns `null` this method throws a `MissingParameterException` complaining that an input image is missing.

Throws:
  `MissingParameterException` - if no input image is available

### ensureOutputImageResolution

public void ensureOutputImageResolution(int width, int height) throws WrongParameterException
If an output image has been specified this method will compare its resolution with the argument resolution and throw an exception if the resolutions differ. If no output image has been specified nothing happens.

Parameters:
  `width` - the horizontal pixel resolution that the output image must have
  `height` - the vertical pixel resolution that the output image must have
Throws:
  `WrongParameterException` - if the resolutions differ

### getInputImage

public PixelImage getInputImage()
Returns the input image stored in this object.

Returns:
  input image, possibly `null`

### getOutputImage

public PixelImage getOutputImage()
Returns the output image stored in this object.

Returns:
  output image, possibly `null`

### setCanInputAndOutputBeEqual

public void setCanInputAndOutputBeEqual(boolean newValue)
Specify if input and output image are allowed to be the same object.

See Also:
  - `canInputAndOutputBeEqual()`

### setInputImage

public void setInputImage(PixelImage in)
Sets the input image stored in this object to the argument. Argument can be `null`.

Parameters:
  `in` - the new input image of this object

### setOutputImage

public void setOutputImage(PixelImage out)
Sets the output image stored in this object to the argument. Argument can be `null`.

Parameters:
  `out` - the new output image of this object