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 2021/10/19 15:11:34 UTC
[sis] branch geoapi-4.0 updated (098b3bc -> 8e1df6f)
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 098b3bc Popup a dialog box if an error occurred while downloading optional resources.
new 38066bc Cherry-pick documentation improvement from pull request #24: doc(Core): improve SampleDimension apidoc regarding background value management.
new 8e1df6f Provide an extension mechanism for allowing users to provide their own solution for https://github.com/apache/sis/pull/24
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:
.../org/apache/sis/coverage/SampleDimension.java | 86 ++++++++++++++++++++--
1 file changed, 79 insertions(+), 7 deletions(-)
[sis] 01/02: Cherry-pick documentation improvement from pull
request #24: doc(Core): improve SampleDimension apidoc regarding background
value management.
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 38066bc9938f6b2f5dbeb4036c9f62bfe0a84ed8
Author: Martin Desruisseaux <ma...@geomatys.com>
AuthorDate: Tue Oct 19 16:42:53 2021 +0200
Cherry-pick documentation improvement from pull request #24:
doc(Core): improve SampleDimension apidoc regarding background value management.
---
.../org/apache/sis/coverage/SampleDimension.java | 53 +++++++++++++++++++++-
1 file changed, 51 insertions(+), 2 deletions(-)
diff --git a/core/sis-feature/src/main/java/org/apache/sis/coverage/SampleDimension.java b/core/sis-feature/src/main/java/org/apache/sis/coverage/SampleDimension.java
index fe97d55..f8308c4 100644
--- a/core/sis-feature/src/main/java/org/apache/sis/coverage/SampleDimension.java
+++ b/core/sis-feature/src/main/java/org/apache/sis/coverage/SampleDimension.java
@@ -69,7 +69,14 @@ import org.apache.sis.util.Debug;
* but organized in a different way. The use of the same name may seem a risk, but those two types are typically
* not used at the same time.
*
+ * <h2>Definition of missing data</h2>
+ * An important aspect of sample dimensions is the {@linkplain #getBackground() background value}.
+ * It defines how to initialize an empty image or canvas with respect to the sample definition.
+ * It can be thought as the value for "lack of data" (fill value, no-data, missing value) category
+ * when the missing value can not be categorized more precisely (cloud, instrument error, <i>etc</i>).
+ *
* @author Martin Desruisseaux (IRD, Geomatys)
+ * @author Alexis Manin (Geomatys)
* @version 1.1
*
* @see org.opengis.metadata.content.SampleDimension
@@ -223,8 +230,10 @@ public class SampleDimension implements Serializable {
}
/**
- * Returns the background value. If this sample dimensions has quantitative categories, then the background
- * value should be one of the value returned by {@link #getNoDataValues()}. However this is not mandatory.
+ * Returns the background value. This is the value used for filling empty spaces (e.g. in image corners)
+ * after a {@linkplain org.apache.sis.image.ImageProcessor#resample resampling operation}.
+ * If this sample dimensions has quantitative categories, then the background value should be
+ * one of the value returned by {@link #getNoDataValues()}. However this is not mandatory.
*
* @return the background value, typically (but not necessarily) one of {@link #getNoDataValues()}.
*/
@@ -696,6 +705,11 @@ public class SampleDimension implements Serializable {
* Adds a qualitative category for samples of the given boolean value.
* The {@code true} value is represented by 1 and the {@code false} value is represented by 0.
*
+ * <div class="note"><b>Usage note:</b>
+ * the {@link #setBackground(CharSequence, Number)} method should be used instead of this method
+ * when the aim is to define a default "no data" category to use when the missing value can not
+ * be categorized more precisely (cloud, instrument error, <i>etc</i>).</div>
+ *
* <div class="note"><b>Implementation note:</b>
* this convenience method delegates to {@link #addQualitative(CharSequence, NumberRange)}.</div>
*
@@ -713,6 +727,11 @@ public class SampleDimension implements Serializable {
* Adds a qualitative category for samples of the given tiny (8 bits) integer value.
* The argument is treated as a signed integer ({@value Byte#MIN_VALUE} to {@value Byte#MAX_VALUE}).
*
+ * <div class="note"><b>Usage note:</b>
+ * the {@link #setBackground(CharSequence, Number)} method should be used instead of this method
+ * when the aim is to define a default "no data" category to use when the missing value can not
+ * be categorized more precisely (cloud, instrument error, <i>etc</i>).</div>
+ *
* <div class="note"><b>Implementation note:</b>
* this convenience method delegates to {@link #addQualitative(CharSequence, NumberRange)}.</div>
*
@@ -729,6 +748,11 @@ public class SampleDimension implements Serializable {
* Adds a qualitative category for samples of the given short (16 bits) integer value.
* The argument is treated as a signed integer ({@value Short#MIN_VALUE} to {@value Short#MAX_VALUE}).
*
+ * <div class="note"><b>Usage note:</b>
+ * the {@link #setBackground(CharSequence, Number)} method should be used instead of this method
+ * when the aim is to define a default "no data" category to use when the missing value can not
+ * be categorized more precisely (cloud, instrument error, <i>etc</i>).</div>
+ *
* <div class="note"><b>Implementation note:</b>
* this convenience method delegates to {@link #addQualitative(CharSequence, NumberRange)}.</div>
*
@@ -745,6 +769,11 @@ public class SampleDimension implements Serializable {
* Adds a qualitative category for samples of the given integer value.
* The argument is treated as a signed integer ({@value Integer#MIN_VALUE} to {@value Integer#MAX_VALUE}).
*
+ * <div class="note"><b>Usage note:</b>
+ * the {@link #setBackground(CharSequence, Number)} method should be used instead of this method
+ * when the aim is to define a default "no data" category to use when the missing value can not
+ * be categorized more precisely (cloud, instrument error, <i>etc</i>).</div>
+ *
* <div class="note"><b>Implementation note:</b>
* this convenience method delegates to {@link #addQualitative(CharSequence, NumberRange)}.</div>
*
@@ -760,6 +789,11 @@ public class SampleDimension implements Serializable {
/**
* Adds a qualitative category for samples of the given floating-point value.
*
+ * <div class="note"><b>Usage note:</b>
+ * the {@link #setBackground(CharSequence, Number)} method should be used instead of this method
+ * when the aim is to define a default "no data" category to use when the missing value can not
+ * be categorized more precisely (cloud, instrument error, <i>etc</i>).</div>
+ *
* <div class="note"><b>Implementation note:</b>
* this convenience method delegates to {@link #addQualitative(CharSequence, NumberRange)}.</div>
*
@@ -782,6 +816,11 @@ public class SampleDimension implements Serializable {
/**
* Adds a qualitative category for samples of the given double precision floating-point value.
*
+ * <div class="note"><b>Usage note:</b>
+ * the {@link #setBackground(CharSequence, Number)} method should be used instead of this method
+ * when the aim is to define a default "no data" category to use when the missing value can not
+ * be categorized more precisely (cloud, instrument error, <i>etc</i>).</div>
+ *
* <div class="note"><b>Implementation note:</b>
* this convenience method delegates to {@link #addQualitative(CharSequence, NumberRange)}.</div>
*
@@ -804,6 +843,11 @@ public class SampleDimension implements Serializable {
/**
* Adds a qualitative category for samples in the given range of values.
*
+ * <div class="note"><b>Usage note:</b>
+ * the {@link #setBackground(CharSequence, Number)} method should be used instead of this method
+ * when the aim is to define a default "no data" category to use when the missing value can not
+ * be categorized more precisely (cloud, instrument error, <i>etc</i>).</div>
+ *
* <div class="note"><b>Implementation note:</b>
* this convenience method delegates to {@link #addQualitative(CharSequence, NumberRange)}.</div>
*
@@ -825,6 +869,11 @@ public class SampleDimension implements Serializable {
* This is the most generic method for adding a qualitative category.
* All other {@code addQualitative(name, …)} methods are convenience methods delegating their work to this method.
*
+ * <div class="note"><b>Usage note:</b>
+ * the {@link #setBackground(CharSequence, Number)} method should be used instead of this method
+ * when the aim is to define a default "no data" category to use when the missing value can not
+ * be categorized more precisely (cloud, instrument error, <i>etc</i>).</div>
+ *
* @param name the category name as a {@link String} or {@link InternationalString} object,
* or {@code null} for a default "no data" name.
* @param samples the minimum and maximum sample values in the category.
[sis] 02/02: Provide an extension mechanism for allowing users to
provide their own solution for https://github.com/apache/sis/pull/24
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 8e1df6f18cb38e9f0c1f73a8573af8907084f3da
Author: Martin Desruisseaux <ma...@geomatys.com>
AuthorDate: Tue Oct 19 17:05:43 2021 +0200
Provide an extension mechanism for allowing users to provide their own solution for https://github.com/apache/sis/pull/24
---
.../org/apache/sis/coverage/SampleDimension.java | 33 ++++++++++++++++++----
1 file changed, 28 insertions(+), 5 deletions(-)
diff --git a/core/sis-feature/src/main/java/org/apache/sis/coverage/SampleDimension.java b/core/sis-feature/src/main/java/org/apache/sis/coverage/SampleDimension.java
index f8308c4..ce4e432 100644
--- a/core/sis-feature/src/main/java/org/apache/sis/coverage/SampleDimension.java
+++ b/core/sis-feature/src/main/java/org/apache/sis/coverage/SampleDimension.java
@@ -200,7 +200,7 @@ public class SampleDimension implements Serializable {
* @see #forConvertedValues(boolean)
*/
private SampleDimension converted() {
- // Transfer function shall never be null if 'converse' is non-null.
+ // Transfer function shall never be null if `converse` is non-null.
return (converse != null && !transferFunction.isIdentity()) ? converse : this;
}
@@ -439,7 +439,7 @@ public class SampleDimension implements Serializable {
* @see org.apache.sis.coverage.grid.GridCoverage#forConvertedValues(boolean)
*/
public SampleDimension forConvertedValues(final boolean converted) {
- // Transfer function shall never be null if 'converse' is non-null.
+ // Transfer function shall never be null if `converse` is non-null.
if (converse != null && transferFunction.isIdentity() != converted) {
return converse;
}
@@ -543,6 +543,7 @@ public class SampleDimension implements Serializable {
* subclasses can override.
*
* @author Martin Desruisseaux (IRD, Geomatys)
+ * @author Alexis Manin (Geomatys)
* @version 1.2
* @since 1.0
* @module
@@ -655,7 +656,7 @@ public class SampleDimension implements Serializable {
case Numbers.FLOAT: {
final float min = minimum.floatValue();
final float max = maximum.floatValue();
- if (!Float.isNaN(min) || !Float.isNaN(max)) { // Let 'create' throws an exception if only one value is NaN.
+ if (!Float.isNaN(min) || !Float.isNaN(max)) { // Let `create` throws an exception if only one value is NaN.
return NumberRange.create(min, true, max, true);
}
if (minimum.getClass() != Float.class) minimum = min;
@@ -665,7 +666,7 @@ public class SampleDimension implements Serializable {
default: {
final double min = minimum.doubleValue();
final double max = maximum.doubleValue();
- if (!Double.isNaN(min) || !Double.isNaN(max)) { // Let 'create' throws an exception if only one value is NaN.
+ if (!Double.isNaN(min) || !Double.isNaN(max)) { // Let `create` throws an exception if only one value is NaN.
return NumberRange.create(min, true, max, true);
}
if (minimum.getClass() != Double.class) minimum = min;
@@ -679,6 +680,25 @@ public class SampleDimension implements Serializable {
}
/**
+ * Returns the background value to use by default if none were explicitly defined.
+ * This method is invoked at {@linkplain #build() build} time
+ * if the {@link #setBackground(CharSequence, Number)} method has never been invoked
+ * since {@code Builder} construction or since the last call to {@link #clear()}.
+ * The background value returned by this method is not associated to any category.
+ *
+ * <p>The default implementation returns {@code null}.
+ * Subclasses can override this method and compute a background value
+ * for example by analyzing the content of {@link #categories()} list.</p>
+ *
+ * @return the default background value, or {@code null} if none.
+ *
+ * @since 1.2
+ */
+ protected Number defaultBackground() {
+ return null;
+ }
+
+ /**
* Adds a qualitative category and marks that category as the background value.
* This is the value to be returned by {@link SampleDimension#getBackground()}.
* If this method is invoked more than once, then the last specified value prevails
@@ -695,7 +715,7 @@ public class SampleDimension implements Serializable {
name = Vocabulary.formatInternational(Vocabulary.Keys.FillValue);
}
final NumberRange<?> samples = range(sample.getClass(), sample, sample);
- // Use of 'getMinValue()' below shall be consistent with ToNaN.remove(Category).
+ // Use of `getMinValue()` below shall be consistent with ToNaN.remove(Category).
toNaN.background = samples.getMinValue();
add(new Category(name, samples, null, null, toNaN));
return this;
@@ -1153,6 +1173,9 @@ defName: if (name == null) {
}
name = createLocalName(Vocabulary.formatInternational(Vocabulary.Keys.Untitled));
}
+ if (toNaN.background == null) {
+ toNaN.background = defaultBackground();
+ }
return new SampleDimension(name, toNaN.background, UnmodifiableArrayList.wrap(categories, 0, count));
}