This is an automated email from the ASF dual-hosted git repository.
amanin pushed a commit to branch feat/default-background
in repository https://gitbox.apache.org/repos/asf/sis.git
commit 5fa1d3da4987fb774d279e2d360a72b33aa2d161
Author: Alexis Manin <alexis.ma...@geomatys.com>
AuthorDate: Thu Oct 14 14:26:22 2021 +0200
doc(Core): improve SampleDimension apidoc regarding background value
management.
---
.../org/apache/sis/coverage/SampleDimension.java | 33 ++++++++++++++++++++++
1 file changed, 33 insertions(+)
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 551a3af..3d0b742 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
@@ -73,6 +73,15 @@ 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 {@link #getBackground()
background value}. It defines how to
+ * initialize an empty canvas/matrix with respect to the sample definition. It
is the value that defines the main/
+ * default "lack of data" (fill value, no-data, missing value) category.
+ *
+ * It is recommended to define it to enforce stable behavior upon associated
data processing. As a last resort, sample
+ * dimension {@link Builder builder} will try to identify an acceptable
default background value by searching for a
+ * qualitative category named <q>background</q>, <q>fill-value</q> or
<q>no-data</q>.
+ *
* @author Martin Desruisseaux (IRD, Geomatys)
* @version 1.1
*
@@ -699,6 +708,9 @@ 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.
+ * <p>
+ * It is strongly recommended using {@link
#setBackground(CharSequence, Number)} instead of this method when the
+ * aim is to define a main/primary fill value.
*
* <div class="note"><b>Implementation note:</b>
* this convenience method delegates to {@link
#addQualitative(CharSequence, NumberRange)}.</div>
@@ -716,6 +728,9 @@ 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}).
+ * <p>
+ * It is strongly recommended using {@link
#setBackground(CharSequence, Number)} instead of this method when the
+ * aim is to define a main/primary fill value.
*
* <div class="note"><b>Implementation note:</b>
* this convenience method delegates to {@link
#addQualitative(CharSequence, NumberRange)}.</div>
@@ -732,6 +747,9 @@ 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}).
+ * <p>
+ * It is strongly recommended using {@link
#setBackground(CharSequence, Number)} instead of this method when the
+ * aim is to define a main/primary fill value.
*
* <div class="note"><b>Implementation note:</b>
* this convenience method delegates to {@link
#addQualitative(CharSequence, NumberRange)}.</div>
@@ -748,6 +766,9 @@ 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}).
+ * <p>
+ * It is strongly recommended using {@link
#setBackground(CharSequence, Number)} instead of this method when the
+ * aim is to define a main/primary fill value.
*
* <div class="note"><b>Implementation note:</b>
* this convenience method delegates to {@link
#addQualitative(CharSequence, NumberRange)}.</div>
@@ -766,6 +787,9 @@ public class SampleDimension implements Serializable {
*
* <div class="note"><b>Implementation note:</b>
* this convenience method delegates to {@link
#addQualitative(CharSequence, NumberRange)}.</div>
+ * <p>
+ * It is strongly recommended using {@link
#setBackground(CharSequence, Number)} instead of this method when the
+ * aim is to define a main/primary fill value.
*
* @param name the category name as a {@link String} or {@link
InternationalString} object,
* or {@code null} for a default "no data" name.
@@ -788,6 +812,9 @@ public class SampleDimension implements Serializable {
*
* <div class="note"><b>Implementation note:</b>
* this convenience method delegates to {@link
#addQualitative(CharSequence, NumberRange)}.</div>
+ * <p>
+ * It is strongly recommended using {@link
#setBackground(CharSequence, Number)} instead of this method when the
+ * aim is to define a main/primary fill value.
*
* @param name the category name as a {@link String} or {@link
InternationalString} object,
* or {@code null} for a default "no data" name.
@@ -810,6 +837,9 @@ public class SampleDimension implements Serializable {
*
* <div class="note"><b>Implementation note:</b>
* this convenience method delegates to {@link
#addQualitative(CharSequence, NumberRange)}.</div>
+ * <p>
+ * It is strongly recommended using {@link
#setBackground(CharSequence, Number)} instead of this method when the
+ * aim is to define a main/primary fill value.
*
* @param name the category name as a {@link String} or {@link
InternationalString} object,
* or {@code null} for a default "no data" name.
@@ -828,6 +858,9 @@ public class SampleDimension implements Serializable {
* Adds a qualitative category for all samples in the specified range
of values.
* 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.
+ * <p>
+ * It is strongly recommended using {@link
#setBackground(CharSequence, Number)} instead of this method when the
+ * aim is to define a main/primary fill value.
*
* @param name the category name as a {@link String} or {@link
InternationalString} object,
* or {@code null} for a default "no data" name.
