This is an automated email from the ASF dual-hosted git repository.
desruisseaux pushed a commit to branch geoapi-4.0
in repository https://gitbox.apache.org/repos/asf/sis.git
commit 226c9c57062299c2f587e36130e81f5d168170fb
Author: Martin Desruisseaux <martin.desruisse...@geomatys.com>
AuthorDate: Mon Dec 23 13:51:12 2024 +0100
Deprecate `ImageProcessor.Resizing`, replaced by `ImageLayout`.
---
.../main/org/apache/sis/image/ImageLayout.java | 50 ++++++++++++++++
.../main/org/apache/sis/image/ImageProcessor.java | 67 ++++++++++++++--------
.../org/apache/sis/map/coverage/RenderingData.java | 9 ++-
3 files changed, 102 insertions(+), 24 deletions(-)
diff --git
a/endorsed/src/org.apache.sis.feature/main/org/apache/sis/image/ImageLayout.java
b/endorsed/src/org.apache.sis.feature/main/org/apache/sis/image/ImageLayout.java
index 4b9e2096d2..179f3e426b 100644
---
a/endorsed/src/org.apache.sis.feature/main/org/apache/sis/image/ImageLayout.java
+++
b/endorsed/src/org.apache.sis.feature/main/org/apache/sis/image/ImageLayout.java
@@ -41,6 +41,8 @@ import org.apache.sis.coverage.privy.RasterFactory;
* for deriving an actual tile size for a given image size.
* The rules for deriving a tile size are configurable by flags.
*
+ * <p>Instances of this class are immutable and thread-safe.</p>
+ *
* @author Martin Desruisseaux (Geomatys)
* @version 1.5
* @since 1.5
@@ -103,6 +105,7 @@ public class ImageLayout {
*
* <p>The {@linkplain #DEFAULT default} value is {@code false}.</p>
*
+ * @see #allowImageBoundsAdjustments(boolean)
* @see #suggestTileSize(RenderedImage, Rectangle)
*/
public final boolean isImageBoundsAdjustmentAllowed;
@@ -112,6 +115,8 @@ public class ImageLayout {
* This flag may be ignored (handled as {@code false}) when the image for
which to compute a tile size is opaque.
*
* <p>The {@linkplain #DEFAULT default} value is {@code true}.</p>
+ *
+ * @see #allowPartialTiles(boolean)
*/
public final boolean isPartialTilesAllowed;
@@ -206,11 +211,56 @@ public class ImageLayout {
}
}
+ /**
+ * Returns a new layout with the same properties than this layout except
whether it allows changes of tile size.
+ * If the given argument value results in no change, returns {@code this}.
+ *
+ * @param allowed whether to allow changes of tile size when needed.
+ * @return the layout for the given flag.
+ *
+ * @see #isTileSizeAdjustmentAllowed
+ */
+ public ImageLayout allowTileSizeAdjustments(boolean allowed) {
+ if (isTileSizeAdjustmentAllowed == allowed) return this;
+ return new ImageLayout(getPreferredTileSize(), allowed,
isImageBoundsAdjustmentAllowed, isPartialTilesAllowed);
+ }
+
+ /**
+ * Returns a new layout with the same properties than this layout except
whether it allows changes of image size.
+ * If the given argument value results in no change, returns {@code this}.
+ *
+ * @param allowed whether to allow changes of image size when needed.
+ * @return the layout for the given flag.
+ *
+ * @see #isImageBoundsAdjustmentAllowed
+ */
+ public ImageLayout allowImageBoundsAdjustments(boolean allowed) {
+ if (isImageBoundsAdjustmentAllowed == allowed) return this;
+ return new ImageLayout(getPreferredTileSize(),
isTileSizeAdjustmentAllowed, allowed, isPartialTilesAllowed);
+ }
+
+ /**
+ * Returns a new layout with the same properties than this layout except
whether it allows partially filled tiles.
+ * If the given argument value results in no change, returns {@code this}.
+ *
+ * @param allowed whether to allow tiles that are only partially filled
in the last row and last column of the tile matrix.
+ * @return the layout for the given flag.
+ *
+ * @see #isPartialTilesAllowed
+ */
+ public ImageLayout allowPartialTiles(boolean allowed) {
+ if (isPartialTilesAllowed == allowed) return this;
+ return new ImageLayout(getPreferredTileSize(),
isTileSizeAdjustmentAllowed, isImageBoundsAdjustmentAllowed, allowed);
+ }
+
/**
* Returns a new layout with the same flags but a different preferred tile
size.
+ * If the given argument values result in no change, returns {@code this}.
*
* @param size the new tile size.
* @return the layout for the given size.
+ *
+ * @see #getPreferredTileSize()
*/
public ImageLayout withPreferredTileSize(final Dimension size) {
if (size.width == preferredTileWidth && size.height ==
preferredTileHeight) {
diff --git
a/endorsed/src/org.apache.sis.feature/main/org/apache/sis/image/ImageProcessor.java
b/endorsed/src/org.apache.sis.feature/main/org/apache/sis/image/ImageProcessor.java
index 6228fedd99..bd3e637c58 100644
---
a/endorsed/src/org.apache.sis.feature/main/org/apache/sis/image/ImageProcessor.java
+++
b/endorsed/src/org.apache.sis.feature/main/org/apache/sis/image/ImageProcessor.java
@@ -66,15 +66,15 @@ import org.apache.sis.measure.Units;
*
* <ul class="verbose">
* <li>
+ * {@linkplain #setImageLayout(ImageLayout) Preferences about the tiling}
+ * of an image in relationship with a given image size.
+ * </li><li>
* {@linkplain #setInterpolation(Interpolation) Interpolation method} to
use during resampling operations.
* </li><li>
* {@linkplain #setFillValues(Number...) Fill values} to use for pixels
that cannot be computed.
* </li><li>
* {@linkplain #setColorizer(Colorizer) Colorization algorithm} to apply
for colorizing a computed image.
* </li><li>
- * {@linkplain #setImageResizingPolicy(Resizing) Image resizing policy} to
apply
- * if a requested image size prevent the image to be tiled.
- * </li><li>
* {@linkplain #setPositionalAccuracyHints(Quantity...) Positional
accuracy hints}
* for enabling the use of faster algorithm when a lower accuracy is
acceptable.
* </li><li>
@@ -179,25 +179,34 @@ public class ImageProcessor implements Cloneable {
*
* @see #getImageResizingPolicy()
* @see #setImageResizingPolicy(Resizing)
+ *
+ * @deprecated Replaced by {@link ImageLayout}.
*/
+ @Deprecated(since="1.5", forRemoval=true)
public enum Resizing {
/**
* Image size is unmodified, the requested value is used
unconditionally.
* It may result in big tiles (potentially a single tile for the whole
image)
* if the image size is not divisible by a tile size.
+ *
+ * @deprecated Replaced by {@link ImageLayout#DEFAULT}.
*/
+ @Deprecated
NONE(ImageLayout.DEFAULT),
/**
* Image size can be increased. {@code ImageProcessor} will try to
increase
* by the smallest number of pixels allowing the image to be
subdivided in tiles.
+ *
+ * @deprecated Replaced by {@code
ImageLayout.DEFAULT.allowImageBoundsAdjustments(true)}.
*/
- EXPAND(new ImageLayout(null, true, true, true));
+ @Deprecated
+ EXPAND(ImageLayout.DEFAULT.allowImageBoundsAdjustments(true));
/**
* The layout corresponding to the enumeration value.
*/
- final ImageLayout layout;
+ public final ImageLayout layout;
/**
* Creates a new enumeration value for the given size policy.
@@ -307,18 +316,24 @@ public class ImageProcessor implements Cloneable {
}
/**
- * Returns the properties (size, tile size, sample model, <i>etc.</i>) of
destination images.
- * This method is not yet public because {@link ImageLayout} is not a
public class.
+ * Returns the preferences about the tiling of an image in relationship
with a given image size.
+ * The {@code ImageLayout} determines characteristics (size, tile size,
sample model, <i>etc.</i>)
+ * of destination images.
+ *
+ * @return preferences about the tiling of an image in relationship with a
given image size.
+ * @since 1.5
*/
- final synchronized ImageLayout getImageLayout() {
+ public synchronized ImageLayout getImageLayout() {
return layout;
}
/**
- * Sets the properties (size, tile size, sample model, <i>etc.</i>) of
destination images.
- * This method is not yet public because {@link ImageLayout} is not a
public class.
+ * Sets the preferences (size, tile size, sample model, <i>etc.</i>) of
destination images.
+ *
+ * @param layout new preferences about the tiling of an image in
relationship with a given image size.
+ * @since 1.5
*/
- final synchronized void setImageLayout(final ImageLayout layout) {
+ public synchronized void setImageLayout(final ImageLayout layout) {
this.layout = Objects.requireNonNull(layout);
}
@@ -407,7 +422,10 @@ public class ImageProcessor implements Cloneable {
* If this processor can use a different size, the enumeration value
specifies what kind of changes may be applied.
*
* @return the image resizing policy.
+ *
+ * @deprecated Replaced by {@link #getImageLayout()}.
*/
+ @Deprecated(since="1.5", forRemoval=true)
public synchronized Resizing getImageResizingPolicy() {
return layout.isImageBoundsAdjustmentAllowed ? Resizing.EXPAND :
Resizing.NONE;
}
@@ -416,7 +434,10 @@ public class ImageProcessor implements Cloneable {
* Sets whether {@code ImageProcessor} can produce an image of different
size compared to requested size.
*
* @param policy the new image resizing policy.
+ *
+ * @deprecated Replaced by {@link #setImageLayout(ImageLayout)}.
*/
+ @Deprecated(since="1.5", forRemoval=true)
public synchronized void setImageResizingPolicy(final Resizing policy) {
layout = policy.layout;
}
@@ -973,8 +994,8 @@ public class ImageProcessor implements Cloneable {
* <h4>Properties used</h4>
* This operation uses the following properties in addition to method
parameters:
* <ul>
- * <li>{@linkplain #getImageResizingPolicy() Image resizing policy} for
specifying whether
- * this method is allowed to change the tile size implied by the
given sample model.</li>
+ * <li>{@linkplain ImageLayout#isImageBoundsAdjustmentAllowed Image
bounds adjustment flag} for deciding
+ * whether to use a modified image size if {@code bounds} is not
divisible by a tile size.</li>
* </ul>
*
* @param sources the images to overlay. Null array elements are
ignored.
@@ -1012,8 +1033,8 @@ public class ImageProcessor implements Cloneable {
* <h4>Properties used</h4>
* This operation uses the following properties in addition to method
parameters:
* <ul>
- * <li>{@linkplain #getImageResizingPolicy() Image resizing policy} for
specifying whether
- * this method is allowed to change the tile size implied by the
given sample model.</li>
+ * <li>{@linkplain ImageLayout#isImageBoundsAdjustmentAllowed Image
bounds adjustment flag} for deciding
+ * whether to use a modified image size if the source image size is
not divisible by a tile size.</li>
* </ul>
*
* @param source the images to reformat.
@@ -1159,8 +1180,8 @@ public class ImageProcessor implements Cloneable {
* <ul>
* <li>{@linkplain #getInterpolation() Interpolation method} (nearest
neighbor, bilinear, <i>etc</i>).</li>
* <li>{@linkplain #getFillValues() Fill values} for pixels outside
source image.</li>
- * <li>{@linkplain #getImageResizingPolicy() Image resizing policy} to
apply
- * if {@code bounds} size is not divisible by a tile size.</li>
+ * <li>{@linkplain ImageLayout#isImageBoundsAdjustmentAllowed Image
bounds adjustment flag} for deciding
+ * whether to use a modified image size if {@code bounds} size is
not divisible by a tile size.</li>
* <li>{@linkplain #getPositionalAccuracyHints() Positional accuracy
hints}
* for enabling faster resampling at the cost of lower
precision.</li>
* </ul>
@@ -1170,8 +1191,8 @@ public class ImageProcessor implements Cloneable {
* if the source image notifies {@linkplain java.awt.image.TileObserver
tile observers}.
*
* @param source the image to be resampled.
- * @param bounds domain of pixel coordinates of resampled image to
create.
- * Updated by this method if {@link Resizing#EXPAND}
policy is applied.
+ * @param bounds domain of pixel coordinates of resampled image to
create. Fields are updated in-place
+ * by this method if the {@link
ImageLayout#isImageBoundsAdjustmentAllowed} flag is true.
* @param toSource conversion of pixel center coordinates from resampled
image to {@code source} image.
* @return resampled image (may be {@code source}).
*
@@ -1391,16 +1412,16 @@ public class ImageProcessor implements Cloneable {
* <ul>
* <li>{@linkplain #getInterpolation() Interpolation method} (nearest
neighbor, bilinear, <i>etc</i>).</li>
* <li>{@linkplain #getFillValues() Fill values} for pixels outside
source image.</li>
- * <li>{@linkplain #getImageResizingPolicy() Image resizing policy} to
apply
- * if {@code bounds} size is not divisible by a tile size.</li>
+ * <li>{@linkplain ImageLayout#isImageBoundsAdjustmentAllowed Image
bounds adjustment flag} for deciding
+ * whether to use a modified image size if {@code bounds} size is
not divisible by a tile size.</li>
* <li>{@linkplain #getPositionalAccuracyHints() Positional accuracy
hints}
* for enabling faster resampling at the cost of lower
precision.</li>
* <li>{@linkplain #getColorizer() Colorizer} for customizing the
rendered image color model.</li>
* </ul>
*
* @param source the image to be resampled and recolored.
- * @param bounds domain of pixel coordinates of resampled image to
create.
- * Updated by this method if {@link Resizing#EXPAND}
policy is applied.
+ * @param bounds domain of pixel coordinates of resampled image to
create. Fields are updated in-place
+ * by this method if the {@link
ImageLayout#isImageBoundsAdjustmentAllowed} flag is true.
* @param toSource conversion of pixel center coordinates from resampled
image to {@code source} image.
* @return resampled and recolored image for visualization purposes only.
*
diff --git
a/endorsed/src/org.apache.sis.portrayal/main/org/apache/sis/map/coverage/RenderingData.java
b/endorsed/src/org.apache.sis.portrayal/main/org/apache/sis/map/coverage/RenderingData.java
index 3861ce565d..c43355260f 100644
---
a/endorsed/src/org.apache.sis.portrayal/main/org/apache/sis/map/coverage/RenderingData.java
+++
b/endorsed/src/org.apache.sis.portrayal/main/org/apache/sis/map/coverage/RenderingData.java
@@ -49,6 +49,7 @@ import org.apache.sis.coverage.grid.PixelTranslation;
import org.apache.sis.geometry.AbstractEnvelope;
import org.apache.sis.geometry.Envelope2D;
import org.apache.sis.geometry.Shapes2D;
+import org.apache.sis.image.ImageLayout;
import org.apache.sis.image.PlanarImage;
import org.apache.sis.image.ErrorHandler;
import org.apache.sis.image.ImageProcessor;
@@ -126,6 +127,12 @@ public class RenderingData implements CloneAccess {
@Debug
private static final boolean CREATE_INDEX_COLOR_MODEL = true;
+ /**
+ * The image layout used for rendering. We allow creating images larger
then necessary
+ * if it can improve subdivisions in tiles.
+ */
+ private static final ImageLayout IMAGE_LAYOUT =
ImageLayout.DEFAULT.allowImageBoundsAdjustments(true);
+
/**
* Loader for reading and caching coverages at various resolutions.
* Required if no image has been explicitly assigned to {@link #data}.
@@ -249,7 +256,7 @@ public class RenderingData implements CloneAccess {
public RenderingData(final ErrorHandler errorHandler) {
processor = new ImageProcessor();
processor.setErrorHandler(errorHandler);
- processor.setImageResizingPolicy(ImageProcessor.Resizing.EXPAND);
+ processor.setImageLayout(IMAGE_LAYOUT);
}
/**
