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 <martin.desruisse...@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.
