You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@sis.apache.org by de...@apache.org on 2020/08/19 17:38:33 UTC
[sis] branch geoapi-4.0 updated (e6cffdb -> 4363b5d)
This is an automated email from the ASF dual-hosted git repository.
desruisseaux pushed a change to branch geoapi-4.0
in repository https://gitbox.apache.org/repos/asf/sis.git.
from e6cffdb Add a ModifiableMetadata.deepCopy(…) method.
new cd06a45 Add a DefaultMetadata.deepCopy(Metadata) convenience method. For now we add that convenience method only for the root Metadata object because it is the kind of objects returned by DataStore.getMetadata() methods.
new 4363b5d Documentation for clarifying the use of properties versus method parameters.
The 2 revisions listed above as "new" are entirely new to this
repository and will be described in separate emails. The revisions
listed as "add" were already present in the repository and have only
been added to this reference.
Summary of changes:
.../java/org/apache/sis/image/ImageProcessor.java | 89 ++++++++++++++++++++++
.../apache/sis/metadata/ModifiableMetadata.java | 7 +-
.../apache/sis/metadata/iso/DefaultMetadata.java | 41 +++++++++-
.../java/org/apache/sis/storage/DataStore.java | 1 +
.../main/java/org/apache/sis/storage/Resource.java | 7 ++
5 files changed, 142 insertions(+), 3 deletions(-)
[sis] 02/02: Documentation for clarifying the use of properties
versus method parameters.
Posted by de...@apache.org.
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 4363b5d3656adf944de71672db8812f9aacffa2a
Author: Martin Desruisseaux <ma...@geomatys.com>
AuthorDate: Wed Aug 19 16:49:40 2020 +0200
Documentation for clarifying the use of properties versus method parameters.
---
.../java/org/apache/sis/image/ImageProcessor.java | 89 ++++++++++++++++++++++
1 file changed, 89 insertions(+)
diff --git a/core/sis-feature/src/main/java/org/apache/sis/image/ImageProcessor.java b/core/sis-feature/src/main/java/org/apache/sis/image/ImageProcessor.java
index 7e90776..e36a6c8 100644
--- a/core/sis-feature/src/main/java/org/apache/sis/image/ImageProcessor.java
+++ b/core/sis-feature/src/main/java/org/apache/sis/image/ImageProcessor.java
@@ -63,6 +63,12 @@ import org.apache.sis.measure.Units;
* </li><li>
* {@linkplain #setFillValues(Number...) Fill values} to use for pixels that can not be computed.
* </li><li>
+ * {@linkplain #setCategoryColors(Function) Category colors} for mapping sample values
+ * (identified by their range, name or unit of measurement) to colors.
+ * </li><li>
+ * {@linkplain #setPositionalAccuracyHints(Quantity...) Positional accuracy hints}
+ * for enabling the use of faster algorithm when a lower accuracy is acceptable.
+ * </li><li>
* Whether operations can be executed in parallel. By default operations on unknown
* {@link RenderedImage} implementations are executed sequentially in the caller thread, for safety reasons.
* Some operations can be parallelized, but it should be enabled only if the {@link RenderedImage} is known
@@ -77,6 +83,18 @@ import org.apache.sis.measure.Units;
* </li>
* </ul>
*
+ * For each image operations, above properties are combined with parameters given to the operation method.
+ * Each method in this {@code ImageProcessor} class documents the properties used in addition of method parameters.
+ *
+ * <div class="note"><b>API design:</b>
+ * properties (setter methods) are used for values that can be applied unchanged on many different images.
+ * For example the {@linkplain #getInterpolation() interpolation method} can be specified once and used
+ * unchanged for many {@link #resample resample(…)} operations.
+ * On the other hand, method arguments are used for values that are usually specific to the image to process.
+ * For example the {@link MathTransform} argument given to the {@link #resample resample(…)} operation depends
+ * tightly on the source image and destination bounds (also given in arguments); those information usually need
+ * to be recomputed for each image.</div>
+ *
* <h2>Area of interest</h2>
* Some operations accept an optional <cite>area of interest</cite> argument specified as a {@link Shape} instance in
* pixel coordinates. If a shape is given, it should not be modified after {@code ImageProcessor} method call because
@@ -99,6 +117,8 @@ import org.apache.sis.measure.Units;
*
* <h2>Thread-safety</h2>
* {@code ImageProcessor} is safe for concurrent use in multi-threading environment.
+ * Note however that {@code ImageProcessor} instances are mutable;
+ * consider {@linkplain #clone() cloning} if setter methods are invoked on a shared instance.
*
* @author Martin Desruisseaux (Geomatys)
* @version 1.1
@@ -485,6 +505,13 @@ public class ImageProcessor implements Cloneable {
* <li>Otherwise statistics are computed for the whole image.</li>
* </ul>
*
+ * <h4>Properties used</h4>
+ * This operation uses the following properties in addition to method parameters:
+ * <ul>
+ * <li>{@linkplain #getExecutionMode() Execution mode} (parallel or sequential).</li>
+ * <li>{@linkplain #getErrorAction() Error action} (custom action executed if an exception is thrown).</li>
+ * </ul>
+ *
* @param source the image for which to compute statistics.
* @param areaOfInterest pixel coordinates of the area of interest, or {@code null} for the default.
* @return the statistics of sample values in each band.
@@ -534,6 +561,13 @@ public class ImageProcessor implements Cloneable {
* is returned.</li>
* </ul>
*
+ * <h4>Properties used</h4>
+ * This operation uses the following properties in addition to method parameters:
+ * <ul>
+ * <li>{@linkplain #getExecutionMode() Execution mode} (parallel or sequential).</li>
+ * <li>{@linkplain #getErrorAction() Error action} (whether to fail if an exception is thrown).</li>
+ * </ul>
+ *
* @param source the image for which to provide statistics.
* @param areaOfInterest pixel coordinates of the area of interest, or {@code null} for the default.
* @return an image with an {@value StatisticsCalculator#STATISTICS_KEY} property.
@@ -609,6 +643,12 @@ public class ImageProcessor implements Cloneable {
* </tr>
* </table>
*
+ * <h4>Properties used</h4>
+ * This operation uses the following properties in addition to method parameters:
+ * <ul>
+ * <li>(none)</li>
+ * </ul>
+ *
* <h4>Limitation</h4>
* Current implementation can stretch only gray scale images (a future version may extend support to images
* using {@linkplain java.awt.image.IndexColorModel index color models}). If this method can not stretch the
@@ -633,6 +673,12 @@ public class ImageProcessor implements Cloneable {
* pixel values are not copied. Consequently changes in the source image are reflected
* immediately in the returned image.</p>
*
+ * <h4>Properties used</h4>
+ * This operation uses the following properties in addition to method parameters:
+ * <ul>
+ * <li>(none)</li>
+ * </ul>
+ *
* @param source the image in which to select bands.
* @param bands indices of bands to retain.
* @return image width selected bands.
@@ -665,6 +711,12 @@ public class ImageProcessor implements Cloneable {
* and extraneous elements are ignored. Those ranges do not need to encompass all possible values;
* it is sufficient to provide only typical or "most interesting" ranges.</p>
*
+ * <h4>Properties used</h4>
+ * This operation uses the following properties in addition to method parameters:
+ * <ul>
+ * <li>(none)</li>
+ * </ul>
+ *
* @param source the image for which to convert sample values.
* @param sourceRanges approximate ranges of values for each band in source image, or {@code null} if unknown.
* @param converters the transfer functions to apply on each band of the source image.
@@ -700,6 +752,15 @@ public class ImageProcessor implements Cloneable {
* then this method will use {@linkplain PlanarImage#getSources() the source} of the given source.
* The intent is to avoid resampling a resampled image; instead this method works on the original data.</p>
*
+ * <h4>Properties used</h4>
+ * This operation uses the following properties in addition to method parameters:
+ * <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 #getPositionalAccuracyHints() Positional accuracy hints}
+ * for enabling faster resampling at the cost of lower precision.</li>
+ * </ul>
+ *
* @param source the image to be resampled.
* @param bounds domain of pixel coordinates of resampled image to create.
* @param toSource conversion of pixel coordinates from resampled image to {@code source} image.
@@ -764,6 +825,12 @@ public class ImageProcessor implements Cloneable {
* have a mechanism for specifying which tile to produce in replacement of tiles that can not be computed.
* This behavior may be changed in a future version.</div>
*
+ * <h4>Properties used</h4>
+ * This operation uses the following properties in addition to method parameters:
+ * <ul>
+ * <li>{@linkplain #getExecutionMode() Execution mode} (parallel or sequential).</li>
+ * </ul>
+ *
* @param source the image to compute immediately (may be {@code null}).
* @param areaOfInterest pixel coordinates of the region to prefetch, or {@code null} for the whole image.
* @return image with all tiles intersecting the AOI computed, or {@code null} if the given image was null.
@@ -800,6 +867,12 @@ public class ImageProcessor implements Cloneable {
* There is no guarantees about the number of bands in returned image or about which formula is used for converting
* floating point values to integer values.</p>
*
+ * <h4>Properties used</h4>
+ * This operation uses the following properties in addition to method parameters:
+ * <ul>
+ * <li>(none)</li>
+ * </ul>
+ *
* @param source the image to recolor for visualization purposes.
* @param colors colors to use for each range of values in the source image.
* @return recolored image for visualization purposes only.
@@ -835,6 +908,12 @@ public class ImageProcessor implements Cloneable {
* There is no guarantees about the number of bands in returned image or about which formula is used for converting
* floating point values to integer values.</p>
*
+ * <h4>Properties used</h4>
+ * This operation uses the following properties in addition to method parameters:
+ * <ul>
+ * <li>{@linkplain #getCategoryColors() Category colors}.</li>
+ * </ul>
+ *
* @param source the image to recolor for visualization purposes.
* @param ranges description of {@code source} bands, or {@code null} if none. This is typically
* obtained by {@link org.apache.sis.coverage.grid.GridCoverage#getSampleDimensions()}.
@@ -867,6 +946,16 @@ public class ImageProcessor implements Cloneable {
* There is no guarantees about the number of bands in returned image or about which formula is used for converting
* floating point values to integer values.</p>
*
+ * <h4>Properties used</h4>
+ * This operation uses the following properties in addition to method parameters:
+ * <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 #getPositionalAccuracyHints() Positional accuracy hints}
+ * for enabling faster resampling at the cost of lower precision.</li>
+ * <li>{@linkplain #getCategoryColors() Category colors}.</li>
+ * </ul>
+ *
* @param source the image to be resampled and recolored.
* @param bounds domain of pixel coordinates of resampled image to create.
* @param toSource conversion of pixel coordinates from resampled image to {@code source} image.
[sis] 01/02: Add a DefaultMetadata.deepCopy(Metadata) convenience
method. For now we add that convenience method only for the root Metadata
object because it is the kind of objects returned by
DataStore.getMetadata() methods.
Posted by de...@apache.org.
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 cd06a450f02fd074cff6ae0fbf9701c09b67f38d
Author: Martin Desruisseaux <ma...@geomatys.com>
AuthorDate: Wed Aug 19 13:16:14 2020 +0200
Add a DefaultMetadata.deepCopy(Metadata) convenience method.
For now we add that convenience method only for the root Metadata object
because it is the kind of objects returned by DataStore.getMetadata() methods.
---
.../apache/sis/metadata/ModifiableMetadata.java | 7 +++-
.../apache/sis/metadata/iso/DefaultMetadata.java | 41 ++++++++++++++++++++--
.../java/org/apache/sis/storage/DataStore.java | 1 +
.../main/java/org/apache/sis/storage/Resource.java | 7 ++++
4 files changed, 53 insertions(+), 3 deletions(-)
diff --git a/core/sis-metadata/src/main/java/org/apache/sis/metadata/ModifiableMetadata.java b/core/sis-metadata/src/main/java/org/apache/sis/metadata/ModifiableMetadata.java
index 40a0add..dee99d7 100644
--- a/core/sis-metadata/src/main/java/org/apache/sis/metadata/ModifiableMetadata.java
+++ b/core/sis-metadata/src/main/java/org/apache/sis/metadata/ModifiableMetadata.java
@@ -31,6 +31,7 @@ import java.lang.reflect.Modifier;
import java.nio.charset.Charset;
import javax.xml.bind.annotation.XmlTransient;
import org.opengis.util.CodeList;
+import org.opengis.metadata.Metadata; // For javadoc
import org.apache.sis.util.resources.Errors;
import org.apache.sis.util.collection.Containers;
import org.apache.sis.util.collection.CodeListSet;
@@ -150,7 +151,10 @@ public abstract class ModifiableMetadata extends AbstractMetadata {
*
* @author Martin Desruisseaux (Geomatys)
* @version 1.0
- * @since 1.0
+ *
+ * @see ModifiableMetadata#state()
+ *
+ * @since 1.0
* @module
*/
public enum State {
@@ -330,6 +334,7 @@ public abstract class ModifiableMetadata extends AbstractMetadata {
* @return a copy (except in above-cited special case) of this metadata in the specified state.
*
* @see MetadataCopier
+ * @see org.apache.sis.metadata.iso.DefaultMetadata#deepCopy(Metadata)
*
* @since 1.1
*/
diff --git a/core/sis-metadata/src/main/java/org/apache/sis/metadata/iso/DefaultMetadata.java b/core/sis-metadata/src/main/java/org/apache/sis/metadata/iso/DefaultMetadata.java
index e80b0d9..bf7db5f 100644
--- a/core/sis-metadata/src/main/java/org/apache/sis/metadata/iso/DefaultMetadata.java
+++ b/core/sis-metadata/src/main/java/org/apache/sis/metadata/iso/DefaultMetadata.java
@@ -60,6 +60,8 @@ import org.opengis.referencing.ReferenceSystem;
import org.opengis.util.InternationalString;
import org.apache.sis.util.iso.SimpleInternationalString;
import org.apache.sis.util.Emptiable;
+import org.apache.sis.metadata.MetadataCopier;
+import org.apache.sis.metadata.MetadataStandard;
import org.apache.sis.metadata.iso.citation.DefaultCitation;
import org.apache.sis.metadata.iso.citation.DefaultCitationDate;
import org.apache.sis.metadata.iso.citation.DefaultOnlineResource;
@@ -135,8 +137,11 @@ import org.apache.sis.math.FunctionProperty;
* @author Touraïvane (IRD)
* @author Cédric Briançon (Geomatys)
* @author Cullen Rombach (Image Matters)
- * @version 1.0
- * @since 0.3
+ * @version 1.1
+ *
+ * @see org.apache.sis.storage.Resource#getMetadata()
+ *
+ * @since 0.3
* @module
*/
@XmlType(name = "MD_Metadata_Type", propOrder = {
@@ -386,6 +391,12 @@ public class DefaultMetadata extends ISOMetadata implements Metadata {
* metadata contained in the given object are not recursively copied.</li>
* </ul>
*
+ * <h4>Use case</h4>
+ * This method is useful before {@linkplain org.apache.sis.xml.XML#marshal(Object) XML marshalling}
+ * or serialization, which may not be supported by all implementations.
+ * However the returned metadata is not guaranteed to be {@linkplain State#EDITABLE editable}.
+ * For editable metadata, see {@link #deepCopy(Metadata)}.
+ *
* @param object the object to get as a SIS implementation, or {@code null} if none.
* @return a SIS implementation containing the values of the given object (may be the
* given object itself), or {@code null} if the argument was null.
@@ -397,6 +408,32 @@ public class DefaultMetadata extends ISOMetadata implements Metadata {
return new DefaultMetadata(object);
}
+ /**
+ * Returns an editable copy of the given metadata. All children are also copied.
+ * This method is more expensive than {@link #castOrCopy(Metadata)} because the
+ * copy is unconditional and much deeper.
+ * However the result is guaranteed to be editable.
+ *
+ * <h4>Use case</h4>
+ * Metadata returned by {@link org.apache.sis.storage.Resource#getMetadata()} are typically unmodifiable.
+ * This {@code deepCopy(…)} method is useful for completing those metadata with new elements, for example
+ * before insertion in a catalog.
+ *
+ * @param object the metadata to copy, or {@code null} if none.
+ * @return a deep copy of the given object, or {@code null} if the argument was null.
+ *
+ * @see #deepCopy(State)
+ * @see State#EDITABLE
+ *
+ * @since 1.1
+ */
+ public static DefaultMetadata deepCopy(final Metadata object) {
+ if (object == null) {
+ return null;
+ }
+ return (DefaultMetadata) new MetadataCopier(MetadataStandard.ISO_19115).copy(Metadata.class, object);
+ }
+
/*
* Note about deprecated methods implementation: as a general guideline in our metadata implementation,
* the deprecated getter methods invoke only the non-deprecated getter replacement, and the deprecated
diff --git a/storage/sis-storage/src/main/java/org/apache/sis/storage/DataStore.java b/storage/sis-storage/src/main/java/org/apache/sis/storage/DataStore.java
index e4368b1..5487b25 100644
--- a/storage/sis-storage/src/main/java/org/apache/sis/storage/DataStore.java
+++ b/storage/sis-storage/src/main/java/org/apache/sis/storage/DataStore.java
@@ -356,6 +356,7 @@ public abstract class DataStore implements Resource, Localized, AutoCloseable {
* @throws DataStoreException if an error occurred while reading the metadata.
*
* @see #getIdentifier()
+ * @see org.apache.sis.metadata.iso.DefaultMetadata#deepCopy(Metadata)
*/
@Override
public abstract Metadata getMetadata() throws DataStoreException;
diff --git a/storage/sis-storage/src/main/java/org/apache/sis/storage/Resource.java b/storage/sis-storage/src/main/java/org/apache/sis/storage/Resource.java
index e37a1ca..0ed22e5 100644
--- a/storage/sis-storage/src/main/java/org/apache/sis/storage/Resource.java
+++ b/storage/sis-storage/src/main/java/org/apache/sis/storage/Resource.java
@@ -126,10 +126,17 @@ public interface Resource {
* sample dimension names (or band numbers in simpler cases) of coverages or rasters included in this resource.</li>
* </ul>
*
+ * <h4>Metadata edition</h4>
+ * This method often returns an {@linkplain org.apache.sis.metadata.ModifiableMetadata.State#FINAL unmodifiable}
+ * metadata, for making possible to return efficiently a cached instance.
+ * If the caller wants to modify some metadata elements, it may be necessary to perform a
+ * {@linkplain org.apache.sis.metadata.iso.DefaultMetadata#deepCopy(Metadata) deep copy} first.
+ *
* @return information about this resource. Should not be {@code null}.
* @throws DataStoreException if an error occurred while reading the metadata.
*
* @see DataStore#getMetadata()
+ * @see org.apache.sis.metadata.iso.DefaultMetadata#deepCopy(Metadata)
*/
Metadata getMetadata() throws DataStoreException;