From af247ee252cbf6368a8077de9c89d7c642e9c502 Mon Sep 17 00:00:00 2001
From: Leonard Kupper <leonard.kupper@mailbox.tu-dresden.de>
Date: Mon, 22 Jul 2019 14:45:07 +0200
Subject: [PATCH] Complete JavaDoc (for public and protected visibility scope).
---
.../brailleplot/rendering/AbstractCanvas.java | 11 +-
.../inf/mci/brailleplot/rendering/Axis.java | 7 +-
.../brailleplot/rendering/BrailleText.java | 56 ++++++++
.../rendering/BrailleTextRasterizer.java | 8 +-
.../rendering/FunctionalRasterizer.java | 2 +-
.../rendering/FunctionalRenderingBase.java | 49 +++++--
.../inf/mci/brailleplot/rendering/Image.java | 15 +++
.../rendering/ImageRasterizer.java | 26 +++-
.../LinearMappingAxisRasterizer.java | 15 ++-
.../brailleplot/rendering/RasterCanvas.java | 4 +-
.../mci/brailleplot/rendering/Rasterizer.java | 38 +++++-
.../mci/brailleplot/rendering/Rectangle.java | 127 +++++++++++++++++-
.../mci/brailleplot/rendering/Renderable.java | 1 +
.../rendering/SixDotBrailleRasterCanvas.java | 2 +-
.../inf/mci/brailleplot/rendering/Text.java | 31 -----
.../rendering/ThrowingBiConsumer.java | 9 ++
.../UniformTextureBarChartRasterizer.java | 15 ++-
.../rendering/FunctionalRasterizerTest.java | 6 +-
.../rendering/MasterRendererTest.java | 4 +-
19 files changed, 341 insertions(+), 85 deletions(-)
create mode 100644 src/main/java/de/tudresden/inf/mci/brailleplot/rendering/BrailleText.java
delete mode 100644 src/main/java/de/tudresden/inf/mci/brailleplot/rendering/Text.java
diff --git a/src/main/java/de/tudresden/inf/mci/brailleplot/rendering/AbstractCanvas.java b/src/main/java/de/tudresden/inf/mci/brailleplot/rendering/AbstractCanvas.java
index e101a5f9..b8529387 100644
--- a/src/main/java/de/tudresden/inf/mci/brailleplot/rendering/AbstractCanvas.java
+++ b/src/main/java/de/tudresden/inf/mci/brailleplot/rendering/AbstractCanvas.java
@@ -11,7 +11,7 @@ import java.util.ListIterator;
/**
* Representation of a target onto which can be drawn. It wraps a {@link PrintableData} instance and specifies the size of the drawing area (in mm).
* @author Leonard Kupper
- * @version 2019.07.20
+ * @version 2019.07.22
*/
public abstract class AbstractCanvas {
@@ -19,15 +19,6 @@ public abstract class AbstractCanvas {
Format mFormat;
Rectangle mPrintableArea;
- /*
- double mMillimeterWidth;
- double mMillimeterHeight;
-
- double mMarginTop;
- double mMarginBottom;
- double mMarginLeft;
- double mMarginRight;
- */
List<PrintableData> mPageContainer;
diff --git a/src/main/java/de/tudresden/inf/mci/brailleplot/rendering/Axis.java b/src/main/java/de/tudresden/inf/mci/brailleplot/rendering/Axis.java
index 21a430a9..2fe6ce12 100644
--- a/src/main/java/de/tudresden/inf/mci/brailleplot/rendering/Axis.java
+++ b/src/main/java/de/tudresden/inf/mci/brailleplot/rendering/Axis.java
@@ -5,8 +5,8 @@ import java.util.Objects;
/**
* The representation of a visible axis with a line, tickmarks and labels.
- * @version 2019.07.09
- * @author Leonard Kupper
+ * @author Leonard Kupper
+ * @version 2019.07.09
*/
public class Axis implements Renderable {
@@ -178,6 +178,9 @@ public class Axis implements Renderable {
return !Objects.isNull(mBoundary);
}
+ /**
+ * Representation of the axis type / orientation.
+ */
enum Type {
X_AXIS, Y_AXIS;
}
diff --git a/src/main/java/de/tudresden/inf/mci/brailleplot/rendering/BrailleText.java b/src/main/java/de/tudresden/inf/mci/brailleplot/rendering/BrailleText.java
new file mode 100644
index 00000000..afa027de
--- /dev/null
+++ b/src/main/java/de/tudresden/inf/mci/brailleplot/rendering/BrailleText.java
@@ -0,0 +1,56 @@
+package de.tudresden.inf.mci.brailleplot.rendering;
+
+import java.util.Objects;
+
+/**
+ * Simple representation of a braille text field.
+ * @author Leonard Kupper
+ * @version 2019.07.22
+ */
+public class BrailleText implements Renderable {
+
+ private String mContent;
+ private Rectangle mArea;
+
+ /**
+ * Constructor. Creates a braille text field.
+ * @param content The actual text of the text field.
+ * @param area The desired area for the text to be rendered on.
+ */
+ public BrailleText(final String content, final Rectangle area) {
+ setText(content);
+ setArea(area);
+ }
+
+ /**
+ * Sets a new text content.
+ * @param content The new content for the text field.
+ */
+ public void setText(final String content) {
+ mContent = Objects.requireNonNull(content);
+ }
+
+ /**
+ * Gets the current text content of the text field.
+ * @return A {@link String} containing the text.
+ */
+ public String getText() {
+ return mContent;
+ }
+
+ /**
+ * Sets a new area for the text field.
+ * @param area The new area for the text field.
+ */
+ public void setArea(final Rectangle area) {
+ mArea = Objects.requireNonNull(area);
+ }
+
+ /**
+ * Gets the current area of the text field.
+ * @return The area of the text field.
+ */
+ public Rectangle getArea() {
+ return mArea;
+ }
+}
diff --git a/src/main/java/de/tudresden/inf/mci/brailleplot/rendering/BrailleTextRasterizer.java b/src/main/java/de/tudresden/inf/mci/brailleplot/rendering/BrailleTextRasterizer.java
index 5f049629..3c42cce9 100644
--- a/src/main/java/de/tudresden/inf/mci/brailleplot/rendering/BrailleTextRasterizer.java
+++ b/src/main/java/de/tudresden/inf/mci/brailleplot/rendering/BrailleTextRasterizer.java
@@ -1,13 +1,13 @@
package de.tudresden.inf.mci.brailleplot.rendering;
/**
- * A rasterizer for text on braille grids.
- * @version 2019.07.20
+ * A rasterizer for text on braille grids. This class is still a stub and must be implemented!
+ * @version 2019.07.21
* @author Leonard Kupper
*/
-public class BrailleTextRasterizer implements Rasterizer<Text> {
+public final class BrailleTextRasterizer implements Rasterizer<BrailleText> {
@Override
- public void rasterize(final Text data, final RasterCanvas canvas) throws InsufficientRenderingAreaException {
+ public void rasterize(final BrailleText data, final RasterCanvas canvas) throws InsufficientRenderingAreaException {
// TODO: rasterize the text (Take different grids into consideration! 6-dot / 8-dot)
// Until then, we just display dummy characters
int x = data.getArea().intWrapper().getX();
diff --git a/src/main/java/de/tudresden/inf/mci/brailleplot/rendering/FunctionalRasterizer.java b/src/main/java/de/tudresden/inf/mci/brailleplot/rendering/FunctionalRasterizer.java
index 3c2eb847..892b6e43 100644
--- a/src/main/java/de/tudresden/inf/mci/brailleplot/rendering/FunctionalRasterizer.java
+++ b/src/main/java/de/tudresden/inf/mci/brailleplot/rendering/FunctionalRasterizer.java
@@ -42,7 +42,7 @@ public class FunctionalRasterizer<T extends Renderable> implements Rasterizer {
mRasterizingAlgorithm.accept(diagram, canvas);
}
- public final Class<? extends T> getSupportedDiagramClass() {
+ final Class<? extends T> getSupportedDiagramClass() {
return mSupportedDiagramClass;
}
diff --git a/src/main/java/de/tudresden/inf/mci/brailleplot/rendering/FunctionalRenderingBase.java b/src/main/java/de/tudresden/inf/mci/brailleplot/rendering/FunctionalRenderingBase.java
index d0f328bf..336fab1e 100644
--- a/src/main/java/de/tudresden/inf/mci/brailleplot/rendering/FunctionalRenderingBase.java
+++ b/src/main/java/de/tudresden/inf/mci/brailleplot/rendering/FunctionalRenderingBase.java
@@ -7,7 +7,7 @@ import java.util.Objects;
* FunctionalRenderingBase. This class acts as a wrapper for multiple {@link FunctionalRasterizer} instances.
* The rasterizer instances can be registered at runtime. The main purpose of the class is to take diagram representations of any type and select the correct concrete rasterizer.
* @author Leonard Kupper
- * @version 2019.07.20
+ * @version 2019.07.22
*/
public class FunctionalRenderingBase {
@@ -18,35 +18,56 @@ public class FunctionalRenderingBase {
mRasterizingAlgorithms = new HashMap<>();
}
- // Rasterizing
-
- public final void rasterize(final Renderable diagram) throws InsufficientRenderingAreaException {
- // first, check if a raster is set. No rasterizing without raster.
+ /**
+ * Rasterizes any given {@link Renderable} by passing it to the appropriate registered {@link FunctionalRasterizer}.
+ * @param renderData Any instance of a class implementing {@link Renderable}.
+ * @throws InsufficientRenderingAreaException If too few space is available on the currently set {@link RasterCanvas}
+ * to display the amount of data contained in the given renderable representation.
+ * @exception IllegalStateException If no {@link RasterCanvas} is set. Call {@link #setRasterCanvas(RasterCanvas)} beforehand.
+ */
+ public void rasterize(final Renderable renderData) throws InsufficientRenderingAreaException {
+ // First, check if a raster is set. No rasterizing without raster.
if (Objects.isNull(mRaster)) {
throw new IllegalStateException("No raster was set. The method 'setRasterCanvas' must be called before invoking the 'rasterize' method.");
}
- // then, look at the type of the diagram
- Class<? extends Renderable> diagramClass = diagram.getClass();
- // is a rasterizer for the given diagram type available?
+ // Then, look at the type of the renderData
+ Class<? extends Renderable> diagramClass = renderData.getClass();
+ // Is a rasterizer for the given renderData type available?
if (mRasterizingAlgorithms.containsKey(diagramClass)) {
// dispatch to concrete rasterizer implementation
FunctionalRasterizer selectedRasterizer = mRasterizingAlgorithms.get(diagramClass);
- selectedRasterizer.rasterize(diagram, mRaster);
+ selectedRasterizer.rasterize(renderData, mRaster);
} else {
- throw new IllegalArgumentException("No rasterizer registered for diagram class: '"
+ throw new IllegalArgumentException("No rasterizer registered for renderData class: '"
+ diagramClass.getCanonicalName() + "'");
}
}
-
- public final void registerRasterizer(final FunctionalRasterizer<? extends Renderable> rasterizer) {
+ /**
+ * Registers a {@link FunctionalRasterizer} instance to the rendering base. The rendering base can ony hold one rasterizer
+ * per {@link Renderable} type at the same time. This means that any rasterizer that has been registered for the same
+ * type before will be replaced by the new instance.
+ * @param rasterizer The instance of {@link FunctionalRasterizer} to be registered.
+ */
+ public void registerRasterizer(final FunctionalRasterizer<? extends Renderable> rasterizer) {
mRasterizingAlgorithms.put(rasterizer.getSupportedDiagramClass(), rasterizer);
}
- public final void setRasterCanvas(final RasterCanvas raster) {
+ /**
+ * Sets a new canvas for any rasterizing operations performed by this rendering base. The rasterizing results are
+ * 'drawn' on the currently selected canvas instance. There are no restrictions on the raster canvas. It is also
+ * possible to pass a canvas which already contains data to 'overlay' the new data.
+ * @param raster The {@link AbstractCanvas} instance which will be used for all subsequent rasterizing operations.
+ */
+ public void setRasterCanvas(final RasterCanvas raster) {
mRaster = Objects.requireNonNull(raster);
}
- public final RasterCanvas getRaster() {
+
+ /**
+ * Gets the currently set {@link AbstractCanvas} of the rendering base.
+ * @return An instance of {@link AbstractCanvas}.
+ */
+ public RasterCanvas getRaster() {
return mRaster;
}
}
diff --git a/src/main/java/de/tudresden/inf/mci/brailleplot/rendering/Image.java b/src/main/java/de/tudresden/inf/mci/brailleplot/rendering/Image.java
index 8b036858..1bbc3ca7 100644
--- a/src/main/java/de/tudresden/inf/mci/brailleplot/rendering/Image.java
+++ b/src/main/java/de/tudresden/inf/mci/brailleplot/rendering/Image.java
@@ -5,14 +5,29 @@ import java.awt.image.BufferedImage;
import java.io.File;
import java.util.Objects;
+/**
+ * A representation of an (raster graphic) image. Basically just a wrapper for {@link javax.imageio.ImageIO} and
+ * {@link java.awt.image.BufferedImage}.
+ * @author Leonard Kupper
+ * @version 2019.07.22
+ */
public class Image implements Renderable {
private BufferedImage imageData;
+ /**
+ * Constructor. Creates a new renderable representation from an image file.
+ * @param imageFile A file containing an raster graphic image. (Different types supported. BMP, PNG, JPEG, ...)
+ * @throws java.io.IOException If an I/O exception of some sort has occurred while reading the image file.
+ */
public Image(final File imageFile) throws java.io.IOException {
imageData = ImageIO.read(Objects.requireNonNull(imageFile));
}
+ /**
+ * Get the loaded image as {@link BufferedImage}.
+ * @return An instance of {@link BufferedImage}.
+ */
BufferedImage getBufferedImage() {
return imageData;
}
diff --git a/src/main/java/de/tudresden/inf/mci/brailleplot/rendering/ImageRasterizer.java b/src/main/java/de/tudresden/inf/mci/brailleplot/rendering/ImageRasterizer.java
index ddee318e..a7c2893d 100644
--- a/src/main/java/de/tudresden/inf/mci/brailleplot/rendering/ImageRasterizer.java
+++ b/src/main/java/de/tudresden/inf/mci/brailleplot/rendering/ImageRasterizer.java
@@ -9,7 +9,7 @@ import static java.lang.Math.*;
/**
* A rasterizer that is able to re-raster a raster graphics onto a canvas.
* @author Leonard Kupper
- * @version 2019.07.20
+ * @version 2019.07.22
*/
public class ImageRasterizer implements Rasterizer<Image> {
@@ -24,9 +24,12 @@ public class ImageRasterizer implements Rasterizer<Image> {
private boolean mPreserveAspectRatio;
private boolean mQuantifiedPositions;
- // Output threshold: A dot will be set for gray scale values below (darker than) the threshold.
+ // Output threshold: A dot will be set for gray scale values below (darker than/equal) this threshold.
private int mLowThreshold;
+ /**
+ * Constructor. Creates a new {@link Rasterizer} for instances of {@link Image} with default settings.
+ */
public ImageRasterizer() {
mPreventOverStretch = true;
mPreserveAspectRatio = true;
@@ -34,6 +37,18 @@ public class ImageRasterizer implements Rasterizer<Image> {
mLowThreshold = 80;
}
+ /**
+ * Constructor. Creates a new {@link Rasterizer} for instances of {@link Image}.
+ * @param preventOverStretch In case that the given images resolution is smaller than the grid on at least one
+ * dimension this flag prevents it to be 'stretched' on the output, leading to 'cuts' in
+ * former solid lines.
+ * @param preserveAspectRatio This flag will cause the rasterizer to select the smaller of both scaling ratios for
+ * both dimensions to keep aspect ratio the same in the output.
+ * @param useQuantifiedPositions Algorithm selection flag:
+ * If set to true, output dot positions will be quantified.
+ * If set to false, simple linear mapping will be applied instead.
+ * @param threshold Gray scale threshold which determines whether a pixel in the original image sets a dot in the output.
+ */
public ImageRasterizer(
final boolean preventOverStretch,
final boolean preserveAspectRatio,
@@ -45,8 +60,13 @@ public class ImageRasterizer implements Rasterizer<Image> {
mLowThreshold = threshold;
}
+ /**
+ * Rasterizes a {@link Image} instance onto a {@link RasterCanvas}.
+ * @param imgData A instance of {@link Image} representing the renderable image.
+ * @param canvas A instance of {@link RasterCanvas} representing the target for the rasterizer output.
+ */
@Override
- public void rasterize(final Image imgData, final RasterCanvas canvas) throws InsufficientRenderingAreaException {
+ public void rasterize(final Image imgData, final RasterCanvas canvas) {
// Each rasterizer essentially works by taking an instance of a Renderable (in this case Image) and then
// creating a graphical representation of the object on the raster canvas.
diff --git a/src/main/java/de/tudresden/inf/mci/brailleplot/rendering/LinearMappingAxisRasterizer.java b/src/main/java/de/tudresden/inf/mci/brailleplot/rendering/LinearMappingAxisRasterizer.java
index 68c0a9db..208fb2b0 100644
--- a/src/main/java/de/tudresden/inf/mci/brailleplot/rendering/LinearMappingAxisRasterizer.java
+++ b/src/main/java/de/tudresden/inf/mci/brailleplot/rendering/LinearMappingAxisRasterizer.java
@@ -17,6 +17,13 @@ public class LinearMappingAxisRasterizer implements Rasterizer<Axis> {
private BrailleTextRasterizer mTextRasterizer = new BrailleTextRasterizer();
private RasterCanvas mCanvas;
+ /**
+ * Rasterizes a {@link Axis} instance onto a {@link RasterCanvas}.
+ * @param axis A instance of {@link Axis} representing the visual diagram axis.
+ * @param canvas A instance of {@link RasterCanvas} representing the target for the rasterizer output.
+ * @throws InsufficientRenderingAreaException If too few space is available on the {@link RasterCanvas}
+ * to display the given axis.
+ */
@Override
public void rasterize(final Axis axis, final RasterCanvas canvas) throws InsufficientRenderingAreaException {
@@ -52,7 +59,7 @@ public class LinearMappingAxisRasterizer implements Rasterizer<Axis> {
if (hasLabels && axis.getLabels().containsKey(i)) {
String label = axis.getLabels().get(i);
Rectangle labelArea = new Rectangle(dotX - 1, endY + 1, stepWidth, mCanvas.getCellHeight());
- mTextRasterizer.rasterize(new Text(label, labelArea), mCanvas);
+ mTextRasterizer.rasterize(new BrailleText(label, labelArea), mCanvas);
}
i++;
}
@@ -62,7 +69,7 @@ public class LinearMappingAxisRasterizer implements Rasterizer<Axis> {
if (hasLabels && axis.getLabels().containsKey(i)) {
String label = axis.getLabels().get(i);
Rectangle labelArea = new Rectangle(dotX - 1, endY + 1, stepWidth, mCanvas.getCellHeight());
- mTextRasterizer.rasterize(new Text(label, labelArea), mCanvas);
+ mTextRasterizer.rasterize(new BrailleText(label, labelArea), mCanvas);
}
i--;
}
@@ -92,7 +99,7 @@ public class LinearMappingAxisRasterizer implements Rasterizer<Axis> {
if (hasLabels && axis.getLabels().containsKey(i)) {
String label = axis.getLabels().get(i);
Rectangle labelArea = new Rectangle(endX + Integer.signum(tickSize), dotY, stepWidth, mCanvas.getCellHeight());
- mTextRasterizer.rasterize(new Text(label, labelArea), mCanvas);
+ mTextRasterizer.rasterize(new BrailleText(label, labelArea), mCanvas);
}
*/
i++;
@@ -104,7 +111,7 @@ public class LinearMappingAxisRasterizer implements Rasterizer<Axis> {
if (hasLabels && axis.getLabels().containsKey(i)) {
String label = axis.getLabels().get(i);
Rectangle labelArea = new Rectangle(endX + Integer.signum(tickSize), dotY, stepWidth, mCanvas.getCellHeight());
- mTextRasterizer.rasterize(new Text(label, labelArea), mCanvas);
+ mTextRasterizer.rasterize(new BrailleText(label, labelArea), mCanvas);
}
*/
i--;
diff --git a/src/main/java/de/tudresden/inf/mci/brailleplot/rendering/RasterCanvas.java b/src/main/java/de/tudresden/inf/mci/brailleplot/rendering/RasterCanvas.java
index f3ce9d57..41918a8a 100644
--- a/src/main/java/de/tudresden/inf/mci/brailleplot/rendering/RasterCanvas.java
+++ b/src/main/java/de/tudresden/inf/mci/brailleplot/rendering/RasterCanvas.java
@@ -4,10 +4,8 @@ import de.tudresden.inf.mci.brailleplot.configparser.Format;
import de.tudresden.inf.mci.brailleplot.configparser.Printer;
import de.tudresden.inf.mci.brailleplot.printabledata.MatrixData;
import de.tudresden.inf.mci.brailleplot.printabledata.SimpleMatrixDataImpl;
-import org.w3c.dom.css.Rect;
import java.util.ArrayList;
-import java.util.ListIterator;
import static java.lang.Math.*;
@@ -15,7 +13,7 @@ import static java.lang.Math.*;
* Representation of a target onto which an image can be rasterized.
* It wraps a {@link de.tudresden.inf.mci.brailleplot.printabledata.MatrixData} instance and describes the raster size and its (not necessarily equidistant) layout.
* @author Leonard Kupper
- * @version 2019.07.20
+ * @version 2019.07.22
*/
public class RasterCanvas extends AbstractCanvas {
diff --git a/src/main/java/de/tudresden/inf/mci/brailleplot/rendering/Rasterizer.java b/src/main/java/de/tudresden/inf/mci/brailleplot/rendering/Rasterizer.java
index d43e40d5..70681ef6 100644
--- a/src/main/java/de/tudresden/inf/mci/brailleplot/rendering/Rasterizer.java
+++ b/src/main/java/de/tudresden/inf/mci/brailleplot/rendering/Rasterizer.java
@@ -7,18 +7,35 @@ import static java.lang.Math.max;
import static java.lang.Math.min;
/**
- * Rasterizer. A functional interface for anything that is able to rasterize a diagram to a raster.
- * @param <T> The concrete diagram class which can be rasterized with the rasterizer.
+ * Rasterizer. A functional interface for anything that is able to rasterize renderable data onto a raster.
+ * This interface also defines a static set of tool methods for basic operations on a rasters data container ({@link MatrixData}).
+ * @param <T> The concrete class implementing {@link Renderable} which can be rasterized with the rasterizer.
* @author Leonard Kupper
- * @version 2019.07.20
+ * @version 2019.07.22
*/
@FunctionalInterface
public interface Rasterizer<T extends Renderable> {
+ /**
+ * Rasterizes a {@link Renderable} instance onto a {@link RasterCanvas}.
+ * @param data The renderable representation.
+ * @param canvas A instance of {@link RasterCanvas} representing the target for the rasterizer output.
+ * @throws InsufficientRenderingAreaException If too few space is available on the {@link RasterCanvas}
+ * to display the given data.
+ */
void rasterize(T data, RasterCanvas canvas) throws InsufficientRenderingAreaException;
// Basic geometric rasterizing toolset:
+ /**
+ * Fills the space on the raster between two arbitrary opposite points with a given value.
+ * @param x1 X coordinate of first point.
+ * @param y1 Y coordinate of first point.
+ * @param x2 X coordinate of second point.
+ * @param y2 Y coordinate of second point.
+ * @param data The target raster data container.
+ * @param value The value to fill the area with.
+ */
static void fill(int x1, int y1, int x2, int y2, MatrixData<Boolean> data, boolean value) {
int xMin = min(x1, x2);
int xMax = max(x1, x2);
@@ -31,6 +48,15 @@ public interface Rasterizer<T extends Renderable> {
}
}
+ /**
+ * Draws a rectangle border with a given value onto the raster. The rectangle is defined by two arbitrary opposite points.
+ * @param x1 X coordinate of first point.
+ * @param y1 Y coordinate of first point.
+ * @param x2 X coordinate of second point.
+ * @param y2 Y coordinate of second point.
+ * @param data The target raster data container.
+ * @param value The value to fill the area with.
+ */
static void rectangle(int x1, int y1, int x2, int y2, MatrixData<Boolean> data, boolean value) {
int xMin = min(x1, x2);
int xMax = max(x1, x2);
@@ -39,6 +65,12 @@ public interface Rasterizer<T extends Renderable> {
rectangle(new Rectangle(xMin, yMin, xMax - xMin + 1, yMax - yMin + 1), data, value);
}
+ /**
+ * Draws a rectangle border with a given value onto the raster.
+ * @param rect The {@link Rectangle} instance to draw.
+ * @param data The target raster data container.
+ * @param value The value to fill the area with.
+ */
static void rectangle(Rectangle rect, MatrixData<Boolean> data, boolean value) {
Rectangle.IntWrapper intRect = rect.intWrapper();
int x2 = max(intRect.getX() + intRect.getWidth() - 1, 0);
diff --git a/src/main/java/de/tudresden/inf/mci/brailleplot/rendering/Rectangle.java b/src/main/java/de/tudresden/inf/mci/brailleplot/rendering/Rectangle.java
index 46371354..9da2927f 100644
--- a/src/main/java/de/tudresden/inf/mci/brailleplot/rendering/Rectangle.java
+++ b/src/main/java/de/tudresden/inf/mci/brailleplot/rendering/Rectangle.java
@@ -16,6 +16,13 @@ public class Rectangle {
private double mX, mY, mW, mH;
+ /**
+ * Constructor. Creates a rectangle with given position and size.
+ * @param x The x coordinate of the upper left corner.
+ * @param y The y coordinate of the upper left corner.
+ * @param w The width of the rectangle, meaning its rightward expanse.
+ * @param h The height of the rectangle, meaning its downward expanse.
+ */
public Rectangle(final double x, final double y, final double w, final double h) {
setX(x);
setY(y);
@@ -23,6 +30,10 @@ public class Rectangle {
setHeight(h);
}
+ /**
+ * Copy constructor. Creates a copy of a rectangle.
+ * @param rect The rectangle to be copied.
+ */
public Rectangle(final Rectangle rect) {
setX(rect.getX());
setY(rect.getY());
@@ -30,6 +41,12 @@ public class Rectangle {
setHeight(rect.getHeight());
}
+ /**
+ * Removes a partition from the rectangles top and returns it.
+ * @param height The height of the partition that will be removed.
+ * @return A rectangle representing the cropped partition.
+ * @throws OutOfSpaceException If the requested partition is greater than the underlying rectangle itself.
+ */
public Rectangle removeFromTop(final double height) throws OutOfSpaceException {
Rectangle removedPartition = fromTop(height);
double newY = (getY() + height);
@@ -39,6 +56,12 @@ public class Rectangle {
return removedPartition;
}
+ /**
+ * Removes a partition from the rectangles bottom and returns it.
+ * @param height The height of the partition that will be removed.
+ * @return A rectangle representing the cropped partition.
+ * @throws OutOfSpaceException If the requested partition is greater than the underlying rectangle itself.
+ */
public Rectangle removeFromBottom(final double height) throws OutOfSpaceException {
Rectangle removedPartition = fromBottom(height);
double newHeight = (getHeight() - height);
@@ -46,6 +69,12 @@ public class Rectangle {
return removedPartition;
}
+ /**
+ * Removes a partition from the rectangles left side and returns it.
+ * @param width The width of the partition that will be removed.
+ * @return A rectangle representing the cropped partition.
+ * @throws OutOfSpaceException If the requested partition is greater than the underlying rectangle itself.
+ */
public Rectangle removeFromLeft(final double width) throws OutOfSpaceException {
Rectangle removedPartition = fromLeft(width);
double newX = (getX() + width);
@@ -55,6 +84,12 @@ public class Rectangle {
return removedPartition;
}
+ /**
+ * Removes a partition from the rectangles right side and returns it.
+ * @param width The width of the partition that will be removed.
+ * @return A rectangle representing the cropped partition.
+ * @throws OutOfSpaceException If the requested partition is greater than the underlying rectangle itself.
+ */
public Rectangle removeFromRight(final double width) throws OutOfSpaceException {
Rectangle removedPartition = fromRight(width);
double newWidth = (getWidth() - width);
@@ -62,21 +97,48 @@ public class Rectangle {
return removedPartition;
}
- // Methods to getText a mRectangle partition
+ // Methods to get a rectangle partition
+ /**
+ * Gets a partition from the rectangles top without removing it from the original instance.
+ * @param height The height of the selected partition.
+ * @return A rectangle representing the selected partition.
+ * @throws OutOfSpaceException If the requested partition is greater than the underlying rectangle itself.
+ */
public Rectangle fromTop(final double height) throws OutOfSpaceException {
checkHeight(height);
return new Rectangle(getX(), getY(), getWidth(), height);
}
+
+ /**
+ * Gets a partition from the rectangles left side without removing it from the original instance.
+ * @param width The width of the selected partition.
+ * @return A rectangle representing the selected partition.
+ * @throws OutOfSpaceException If the requested partition is greater than the underlying rectangle itself.
+ */
public Rectangle fromLeft(final double width) throws OutOfSpaceException {
checkWidth(width);
return new Rectangle(getX(), getY(), width, getHeight());
}
+
+ /**
+ * Gets a partition from the rectangles bottom without removing it from the original instance.
+ * @param height The height of the selected partition.
+ * @return A rectangle representing the selected partition.
+ * @throws OutOfSpaceException If the requested partition is greater than the underlying rectangle itself.
+ */
public Rectangle fromBottom(final double height) throws OutOfSpaceException {
checkHeight(height);
double newY = (getY() + (getHeight() - height));
return new Rectangle(getX(), newY, getWidth(), height);
}
+
+ /**
+ * Gets a partition from the rectangles right side without removing it from the original instance.
+ * @param width The width of the selected partition.
+ * @return A rectangle representing the selected partition.
+ * @throws OutOfSpaceException If the requested partition is greater than the underlying rectangle itself.
+ */
public Rectangle fromRight(final double width) throws OutOfSpaceException {
checkWidth(width);
double newX = (getX() + (getWidth() - width));
@@ -98,37 +160,76 @@ public class Rectangle {
}
}
+ // Getters for edge positions and size
+
+ /**
+ * Gets the rectangles x position.
+ * @return The x coordinate of the upper left corner.
+ */
public double getX() {
return mX;
}
+ /**
+ * Gets the rectangles y position.
+ * @return The y coordinate of the upper left corner.
+ */
public double getY() {
return mY;
}
+ /**
+ * Gets the rectangles width.
+ * @return The distance between the rectangles left and right edge.
+ */
public double getWidth() {
return mW;
}
+ /**
+ * Gets the rectangles height.
+ * @return The distance between the rectangles top and bottom edge.
+ */
public double getHeight() {
return mH;
}
+ /**
+ * Gets the rectangles right edges position.
+ * @return The x coordinate of the lower right corner.
+ */
public double getRight() {
return mX + mW;
}
+
+ /**
+ * Gets the rectangles bottom edges position.
+ * @return The y coordinate of the lower right corner.
+ */
public double getBottom() {
return mY + mH;
}
+ /**
+ * Sets a new x position for the rectangle.
+ * @param x The new x coordinate of the upper left corner.
+ */
public void setX(final double x) {
mX = x;
}
+ /**
+ * Sets a new y position for the rectangle.
+ * @param y The new y coordinate of the upper left corner.
+ */
public void setY(final double y) {
mY = y;
}
+ /**
+ * Sets a new width for the rectangle.
+ * @param width The new width value.
+ */
public void setWidth(final double width) {
if (width < 0) {
throw new IllegalArgumentException("The width can't be negative.");
@@ -136,6 +237,10 @@ public class Rectangle {
mW = width;
}
+ /**
+ * Sets a new height for the rectangle.
+ * @param height The new height value.
+ */
public void setHeight(final double height) {
if (height < 0) {
throw new IllegalArgumentException("The height can't be negative.");
@@ -166,6 +271,16 @@ public class Rectangle {
return new Rectangle(itsctX, itsctY, max(0, itsctR - itsctX), max(0, itsctB - itsctY));
}
+ /**
+ * Returns a translated copy of this rectangle.
+ * @param alongX The distance to move the copy along x axis.
+ * @param alongY The distance to move the copy along y axis.
+ * @return A new rectangle representing a translated copy of this rectangle.
+ */
+ public Rectangle translatedBy(final double alongX, final double alongY) {
+ return new Rectangle(getX() + alongX, getY() + alongY, getWidth(), getHeight());
+ }
+
@Override
public String toString() {
return "x:" + getX() + ", y:" + getY() + ", w:" + getWidth() + ", h:" + getHeight();
@@ -173,10 +288,20 @@ public class Rectangle {
// Wrapper to make it easy to read integer values from rectangle.
+ /**
+ * Retrieves a proxy object as integer coordinate representation of the rectangle. This is meant as a shortcut
+ * for otherwise frequent int-casting when using rectangles on a integer based coordinate system.
+ * @return An instance of {@link IntWrapper} proxying this rectangle.
+ */
public IntWrapper intWrapper() {
return new IntWrapper(this);
}
+ /**
+ * Wrapper of rectangle for integer coordinates.
+ * @author Leonard Kupper
+ * @version 2019.07.22
+ */
public final class IntWrapper {
private Rectangle mRectangle;
diff --git a/src/main/java/de/tudresden/inf/mci/brailleplot/rendering/Renderable.java b/src/main/java/de/tudresden/inf/mci/brailleplot/rendering/Renderable.java
index 2ca719b0..992d9826 100644
--- a/src/main/java/de/tudresden/inf/mci/brailleplot/rendering/Renderable.java
+++ b/src/main/java/de/tudresden/inf/mci/brailleplot/rendering/Renderable.java
@@ -6,4 +6,5 @@ package de.tudresden.inf.mci.brailleplot.rendering;
* @version 2019.07.04
*/
public interface Renderable {
+ // Not much going on here...
}
diff --git a/src/main/java/de/tudresden/inf/mci/brailleplot/rendering/SixDotBrailleRasterCanvas.java b/src/main/java/de/tudresden/inf/mci/brailleplot/rendering/SixDotBrailleRasterCanvas.java
index 10529b15..dd284e48 100644
--- a/src/main/java/de/tudresden/inf/mci/brailleplot/rendering/SixDotBrailleRasterCanvas.java
+++ b/src/main/java/de/tudresden/inf/mci/brailleplot/rendering/SixDotBrailleRasterCanvas.java
@@ -4,7 +4,7 @@ import de.tudresden.inf.mci.brailleplot.configparser.Format;
import de.tudresden.inf.mci.brailleplot.configparser.Printer;
/**
- * Represents a raster consisting of 6-dot braille cells.
+ * Represents a raster consisting of 6-dot braille cells. (May be removed completely in favor of dynamic {@link RasterCanvas})
* @author Leonard Kupper
* @version 2019.07.20
*/
diff --git a/src/main/java/de/tudresden/inf/mci/brailleplot/rendering/Text.java b/src/main/java/de/tudresden/inf/mci/brailleplot/rendering/Text.java
deleted file mode 100644
index 77abc5ab..00000000
--- a/src/main/java/de/tudresden/inf/mci/brailleplot/rendering/Text.java
+++ /dev/null
@@ -1,31 +0,0 @@
-package de.tudresden.inf.mci.brailleplot.rendering;
-
-import java.util.Objects;
-
-/**
- * Representation of a text field.
- */
-public class Text implements Renderable {
-
- private String mContent;
- private Rectangle mArea;
-
- public Text(final String content, final Rectangle area) {
- setText(content);
- setArea(area);
- }
-
- public void setText(final String content) {
- mContent = Objects.requireNonNull(content);
- }
- public String getText() {
- return mContent;
- }
-
- public void setArea(final Rectangle area) {
- mArea = Objects.requireNonNull(area);
- }
- public Rectangle getArea() {
- return mArea;
- }
-}
diff --git a/src/main/java/de/tudresden/inf/mci/brailleplot/rendering/ThrowingBiConsumer.java b/src/main/java/de/tudresden/inf/mci/brailleplot/rendering/ThrowingBiConsumer.java
index 7e3997c9..8118436d 100644
--- a/src/main/java/de/tudresden/inf/mci/brailleplot/rendering/ThrowingBiConsumer.java
+++ b/src/main/java/de/tudresden/inf/mci/brailleplot/rendering/ThrowingBiConsumer.java
@@ -1,5 +1,14 @@
package de.tudresden.inf.mci.brailleplot.rendering;
+/**
+ * A functional interface representing a void function taking two parameters of types T and U which can throw an
+ * exception E on failure.
+ * @param <T> First parameter type.
+ * @param <U> Second parameter type.
+ * @param <E> Exception type.
+ * @author Leonard Kupper
+ * @version 2019.07.09
+ */
@FunctionalInterface
interface ThrowingBiConsumer<T, U, E extends Exception> {
void accept(T t, U u) throws E;
diff --git a/src/main/java/de/tudresden/inf/mci/brailleplot/rendering/UniformTextureBarChartRasterizer.java b/src/main/java/de/tudresden/inf/mci/brailleplot/rendering/UniformTextureBarChartRasterizer.java
index 9471d452..f2761e74 100644
--- a/src/main/java/de/tudresden/inf/mci/brailleplot/rendering/UniformTextureBarChartRasterizer.java
+++ b/src/main/java/de/tudresden/inf/mci/brailleplot/rendering/UniformTextureBarChartRasterizer.java
@@ -38,13 +38,22 @@ final class UniformTextureBarChartRasterizer implements Rasterizer<BarChart> {
private LinearMappingAxisRasterizer mAxisRasterizer;
//private Rasterizer<Legend> mLegendRasterizer;
+ /**
+ * Constructor. Create a new rasterizer for instances of {@link BarChart}.
+ */
UniformTextureBarChartRasterizer() {
mTextRasterizer = new BrailleTextRasterizer();
mAxisRasterizer = new LinearMappingAxisRasterizer();
//mLegendRasterizer = new LegendRasterizer();
}
-
+ /**
+ * Rasterizes a {@link BarChart} instance onto a {@link RasterCanvas}.
+ * @param diagram A instance of {@link BarChart} representing the bar chart diagram.
+ * @param canvas A instance of {@link RasterCanvas} representing the target for the rasterizer output.
+ * @throws InsufficientRenderingAreaException If too few space is available on the {@link RasterCanvas}
+ * to display the given diagram.
+ */
@Override
public void rasterize(final BarChart diagram, final RasterCanvas canvas)
throws InsufficientRenderingAreaException {
@@ -129,7 +138,7 @@ final class UniformTextureBarChartRasterizer implements Rasterizer<BarChart> {
// Now everything is ready to be rasterized onto the canvas.
// 1. Rasterize the diagram title
- Text diagramTitle = new Text(strDiagramTitle, titleArea.scaledBy(mCanvas.getCellWidth(), mCanvas.getCellHeight()));
+ BrailleText diagramTitle = new BrailleText(strDiagramTitle, titleArea.scaledBy(mCanvas.getCellWidth(), mCanvas.getCellHeight()));
mTextRasterizer.rasterize(diagramTitle, mCanvas);
// 2. Draw the individual bars for each category.
@@ -279,7 +288,7 @@ final class UniformTextureBarChartRasterizer implements Rasterizer<BarChart> {
captionCellX = mCanvas.getCellXFromDotX(max(lowerX, upperX) + 1);
}
Rectangle captionArea = new Rectangle(captionCellX, captionCellY, mCaptionLength, 1);
- mTextRasterizer.rasterize(new Text(categoryName,
+ mTextRasterizer.rasterize(new BrailleText(categoryName,
captionArea.scaledBy(mCanvas.getCellWidth(), mCanvas.getCellHeight())), mCanvas);
return mCanvas.getCellYFromDotY(upperY - (mBarDotPadding + 1)) - mExtraBarCellPadding;
diff --git a/src/test/java/de/tudresden/inf/mci/brailleplot/rendering/FunctionalRasterizerTest.java b/src/test/java/de/tudresden/inf/mci/brailleplot/rendering/FunctionalRasterizerTest.java
index b7ab3ebb..fb1567a6 100644
--- a/src/test/java/de/tudresden/inf/mci/brailleplot/rendering/FunctionalRasterizerTest.java
+++ b/src/test/java/de/tudresden/inf/mci/brailleplot/rendering/FunctionalRasterizerTest.java
@@ -39,8 +39,8 @@ public class FunctionalRasterizerTest {
@Test
public void testInvalidDirectCall() {
- // Create FunctionalRasterizer for Text
- FunctionalRasterizer<Text> textRasterizer = new FunctionalRasterizer<>(Text.class, (data, canvas) -> {
+ // Create FunctionalRasterizer for BrailleText
+ FunctionalRasterizer<BrailleText> textRasterizer = new FunctionalRasterizer<>(BrailleText.class, (data, canvas) -> {
// dummy
});
@@ -49,7 +49,7 @@ public class FunctionalRasterizerTest {
// Directly passing the wrong Renderable type must cause exception:
Assertions.assertThrows(IllegalArgumentException.class, () -> {
RasterCanvas testCanvas = new SixDotBrailleRasterCanvas(mPrinter, mFormat);
- // Pass Image to Text rasterizer.
+ // Pass Image to BrailleText rasterizer.
textRasterizer.rasterize(new Image(getResource("dummy.bmp")), testCanvas);
});
}
diff --git a/src/test/java/de/tudresden/inf/mci/brailleplot/rendering/MasterRendererTest.java b/src/test/java/de/tudresden/inf/mci/brailleplot/rendering/MasterRendererTest.java
index 3d4a6224..e1e7e12c 100644
--- a/src/test/java/de/tudresden/inf/mci/brailleplot/rendering/MasterRendererTest.java
+++ b/src/test/java/de/tudresden/inf/mci/brailleplot/rendering/MasterRendererTest.java
@@ -46,7 +46,7 @@ public class MasterRendererTest {
// Register two different rasterizers for two different types.
// The rasterizers are later distinguished by the number of pages they generate.
- FunctionalRasterizer<Text> rasterizerRef1 = new FunctionalRasterizer<>(Text.class, (data, canvas) -> {
+ FunctionalRasterizer<BrailleText> rasterizerRef1 = new FunctionalRasterizer<>(BrailleText.class, (data, canvas) -> {
for (int i = 0; i < 1; i++) {
canvas.getNewPage();
}
@@ -65,7 +65,7 @@ public class MasterRendererTest {
// Test rasterizer selection
RasterCanvas result;
- result= renderer.rasterize(new Text("dummy text", new Rectangle(0,0,1,1)));
+ result= renderer.rasterize(new BrailleText("dummy text", new Rectangle(0,0,1,1)));
Assertions.assertEquals(1, result.getPageCount());
result = renderer.rasterize(new Image(getResource("dummy.bmp")));
--
GitLab