ForkLoop Images Assignment

Motivation

We gain experience using a parallel fork loop. Image processing often presents the opportunity for a lot of parallelism. Here we will operate on a single image, making a parallel task for each row.

Background

Revisit the Image Batch Race Condition Exercise's Background section for information on pixels and images.

Utilities

Images of Rows of Colors

For this assignment we will be dealing with images. For clarity, we have structured images as a list of rows. Each row is structured as a list of colors. We use the HSV representation of color.

interface ImmutableHsvImage and class DefaultImmutableHsvImage

interface HsvImage

rows()

rowCount()

columnCount()

interface ImmutableHsvImage extends HsvImage

class DefaultImmutableHsvImage implements ImmutableHsvImage

constructor DefaultImmutableHsvImage(List<ImmutableHsvRow> rows)

interface ImmutableHsvRow and class DefaultImmutableHsvRow

interface ImmutableHsvRow

columnColors()

columnCount()

class DefaultImmutableHsvRow implements ImmutableHsvRow

constructor DefaultImmutableHsvRow(List<HsvColor> columnColors)

class HsvColor

class HsvColor

double hue()

double saturation()

double value()

PixelFiler

interface PixelFilter extends UnaryOperator<HsvColor>

HsvColor apply(HsvColor color)

Code to Investigate

SequentialImageFilter

The provided SequentialImageFilter shows off how to read from a source image and construct a new (destination) image. The specified pixelFilter is used to convert the source pixel color into its destination color.

Note: the interfaces ImmutableHsvRow and ImmutableHsvImage are used when appropriate. When we need to construct instances of those interfaces, we use classes which implement them: DefaultImmutableHsvRow and DefaultImmutableHsvImage.

Note: the rowCount() and columnCount() methods are only used to provide the (not required) initialCapacity when constructing the ArrayLists.

SequentialImageFilter

public class SequentialImageFilter implements ImageFilter { @Override public ImmutableHsvImage apply(ImmutableHsvImage src, PixelFilter pixelFilter) { List<ImmutableHsvRow> dstRows = new ArrayList<>(src.rowCount()); for (ImmutableHsvRow srcRow : src.rows()) { List<HsvColor> dstRowPixels = new ArrayList<>(srcRow.columnCount()); for (HsvColor srcPixel : srcRow.columnColors()) { HsvColor dstPixel = pixelFilter.apply(srcPixel); dstRowPixels.add(dstPixel); } dstRows.add(new DefaultImmutableHsvRow(dstRowPixels)); } return new DefaultImmutableHsvImage(dstRows); } }

DesaturateAllPixelFilter

class DesaturateAllPixelFilter
public class DesaturateAllPixelFilter implements PixelFilter { @Override public HsvColor apply(HsvColor src) { return new HsvColor(src.hue(), 0.0, src.value()); } }

PixelFilters

Our Image Filter will apply a PixelFilter to every pixel in a specified image.

Some example pixel filters have been provided which show off reading the hue(), saturation(), and value from a source HsvColor, as well as constructing new HsvColors.

Further, we take the opportunity to construct PixelFilters using named classes, anonymous classes, and lambdas.

class PixelFilters

public class PixelFilters { private static class HueSettingPixelFilter implements PixelFilter { private final double hue; public HueSettingPixelFilter(double hue) { this.hue = hue; } @Override public HsvColor apply(HsvColor src) { double saturation = src.saturation(); double value = src.value(); return new HsvColor(hue, saturation, value); } } public static PixelFilter hueSettingPixelFilterOf(double hue) { // return new instance of named class HueSettingPixelFilter return new HueSettingPixelFilter(hue); } public static PixelFilter hueAdjustingPixelFilterOf(double deltaHue) { // return new instance of anonymous class return new PixelFilter() { @Override public HsvColor apply(HsvColor src) { double hue = src.hue(); double saturation = src.saturation(); double value = src.value(); return new HsvColor(hue + deltaHue, saturation, value); } }; } public static PixelFilter saturationAdjustingPixelFilterOf(double deltaSaturation) { // return anonymous function (also known as a lambda) with parameter type return (HsvColor src) -> { double hue = src.hue(); double saturation = src.saturation(); double value = src.value(); return new HsvColor(hue, saturation + deltaSaturation, value); }; } public static PixelFilter valueAdjustingPixelFilterOf(double deltaValue) { // return anonymous function (also known as a lambda) without parameter type return src -> { double hue = src.hue(); double saturation = src.saturation(); double value = src.value(); return new HsvColor(hue, saturation, value + deltaValue); }; } }

Code To Implement

ParallelTaskPerRowImageFilter

class:	ParallelTaskPerRowImageFilter.java
methods:	apply
package:	imagefilter.exercise
source folder:	student/src/main/java

apply

method: public ImmutableHsvImage apply(ImmutableHsvImage src, PixelFilter pixelFilter) (parallel implementation required)

Apply the provided pixelFilter to each pixel in the src HsvImage.

Each pixel is represented by an HsvColor.

PixelFilter has one interesting method apply which takes a source HsvColor and returns a new filtered HsvColor. It will NOT modify the passed source HsvColor. It would be impossible anyway, as HsvColor is immutable.

Example use of PixelFilter apply:

HsvColor dstPixel = pixelFilter.apply(srcPixel);

To complete this method we must return a new instance of the HsvImage class.

Nicely, HsvImage provides both:

• a constructor which takes an List<HsvColor[]> and,
• another constructor which takes an HsvColor[][].

These two constructors match up well with the two different return types of the many incantations of join_fork_loop:

• List<R>, and
• R[]

where R is the return type of the TaskFunction<T, R> passed to the join_fork_loop.

What should the return type from the this TaskFunction be?

Requirements:

Create a task per row.

Do NOT create a task per pixel.

Use a parallel fork loop.

Visualization

class:	ImageFilterApp.java	VIZ
package:	imagefilter.viz
source folder:	student/src/main/java

Testing Your Solution

class:	__ParallelTaskPerRowImageFilterTestSuite.java
package:	imagefilter.exercise
source folder:	testing/src/test/java

Pledge, Acknowledgments, Citations

file:

exercise-fork-loop-images-pledge-acknowledgments-citations.txt

More info about the Honor Pledge