sis-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From desruisse...@apache.org
Subject [sis] 01/02: Make Category class public. Constructors are accessible for allowing customization, but most common usages should use SampleDimension.Builder instead.
Date Fri, 07 Dec 2018 19:56:36 GMT
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 df1cc0b948ff6812098a949198d4e26ce9d3c5e0
Author: Martin Desruisseaux <martin.desruisseaux@geomatys.com>
AuthorDate: Fri Dec 7 11:16:50 2018 +0100

    Make Category class public. Constructors are accessible for allowing customization, but
most common usages should use SampleDimension.Builder instead.
---
 .../java/org/apache/sis/coverage/Category.java     | 33 +++++++++++++---------
 .../org/apache/sis/coverage/SampleDimension.java   | 21 +++++++++++---
 .../java/org/apache/sis/coverage/CategoryTest.java |  3 +-
 3 files changed, 39 insertions(+), 18 deletions(-)

diff --git a/core/sis-raster/src/main/java/org/apache/sis/coverage/Category.java b/core/sis-raster/src/main/java/org/apache/sis/coverage/Category.java
index 013326d..0e09912 100644
--- a/core/sis-raster/src/main/java/org/apache/sis/coverage/Category.java
+++ b/core/sis-raster/src/main/java/org/apache/sis/coverage/Category.java
@@ -36,18 +36,24 @@ import org.apache.sis.util.iso.Types;
 
 
 /**
- * A category delimited by a range of sample values. A category may be either <em>qualitative</em>
or <em>quantitative</em>.
- * For example an image may have a qualitative category defining sample value {@code 0} as
water,
- * another qualitative category defining sample value {@code 1} as forest, <i>etc</i>.
- * Another image may define elevation data as sample values in the range [0…100].
- * The later is a <em>quantitative</em> category because sample values are related
to measurements in the real world.
- * For example, elevation data may be related to an altitude in metres through the following
linear relation:
+ * Describes a sub-range of sample values in a sample dimension.
+ * A category maps a range of values to an observation, which may be either <em>qualitative</em>
or <em>quantitative</em>:
  *
- * <blockquote><var>altitude</var> = (<var>sample value</var>)×100</blockquote>
+ * <ul class="verbose">
+ *   <li><b>Examples of qualitative observations:</b>
+ *   a sample dimension may have one {@code Category} instance specifying that sample value
{@code 0} stands for water,
+ *   another {@code Category} instance specifying that sample value {@code 1} stands for
forest, <i>etc</i>.</li>
+ *
+ *   <li><b>Example of quantitative observation:</b>
+ *   another sample dimension may have a {@code Category} instance specifying that sample
values in the range [0…100]
+ *   stands for elevation data. Those sample values are related to measurements in the real
world (altitudes in metres)
+ *   through a <cite>transfer function</cite>, foe example <var>altitude</var>
= (<var>sample value</var>)×100 - 25.</li>
+ * </ul>
  *
  * Some image mixes both qualitative and quantitative categories. For example, images of
<cite>Sea Surface Temperature</cite>
  * (SST) may have a quantitative category for temperature with values ranging from -2 to
35°C, and three qualitative categories
- * for cloud, land and ice.
+ * for cloud, land and ice. There is usually at most one quantitative category per sample
dimension, but Apache SIS accepts an
+ * arbitrary amount of them.
  *
  * <p>All categories must have a human readable name. In addition, quantitative categories
  * may define a conversion from sample values <var>s</var> to real values <var>x</var>.
@@ -65,7 +71,7 @@ import org.apache.sis.util.iso.Types;
  * @since   1.0
  * @module
  */
-final class Category implements Serializable {
+public class Category implements Serializable {
     /**
      * Serial number for inter-operability with different versions.
      */
@@ -153,7 +159,8 @@ final class Category implements Serializable {
     final Category converted;
 
     /**
-     * Constructs a qualitative of quantitative category.
+     * Constructs a qualitative or quantitative category. This constructor is provided for
sub-classes.
+     * For other usages, {@link SampleDimension.Builder} should be used instead.
      *
      * @param  name       the category name (mandatory).
      * @param  samples    the minimum and maximum sample values (mandatory).
@@ -163,12 +170,14 @@ final class Category implements Serializable {
      *                    This is the target units after conversion by {@code toUnits}.
      * @param  padValues  an initially empty set to be filled by this constructor for avoiding
pad value collisions.
      *                    The same set shall be given to all {@code Category} created for
the same sample dimension.
+     *                    Content can be discarded after all categories have been created.
      */
-    Category(final CharSequence name, final NumberRange<?> samples, final MathTransform1D
toUnits, final Unit<?> units,
+    protected Category(final CharSequence name, final NumberRange<?> samples, final
MathTransform1D toUnits, final Unit<?> units,
              final Set<Integer> padValues)
     {
         ArgumentChecks.ensureNonEmpty("name", name);
         ArgumentChecks.ensureNonNull("samples", samples);
+        ArgumentChecks.ensureNonNull("padValues", padValues);
         this.name    = Types.toInternationalString(name);
         this.range   = samples;
         this.minimum = samples.getMinDouble(true);
@@ -334,8 +343,6 @@ search:         if (!padValues.add(ordinal)) {
      * @return the range of sample values in this category.
      *
      * @see SampleDimension#getSampleRange()
-     * @see NumberRange#getMinValue()
-     * @see NumberRange#getMaxValue()
      */
     public NumberRange<?> getSampleRange() {
         // Same assumption than in 'isQuantitative()'.
diff --git a/core/sis-raster/src/main/java/org/apache/sis/coverage/SampleDimension.java b/core/sis-raster/src/main/java/org/apache/sis/coverage/SampleDimension.java
index 3d57af1..7682122 100644
--- a/core/sis-raster/src/main/java/org/apache/sis/coverage/SampleDimension.java
+++ b/core/sis-raster/src/main/java/org/apache/sis/coverage/SampleDimension.java
@@ -102,12 +102,13 @@ public class SampleDimension implements Serializable {
     private transient MathTransform1D transferFunction;
 
     /**
-     * Creates a sample dimension with the specified properties.
+     * Creates a sample dimension with the specified name and categories.
+     * Note that {@link Builder} provides a more convenient way to create sample dimensions.
      *
      * @param name        the sample dimension title or description, or {@code null} for
default.
      * @param categories  the list of categories.
      */
-    SampleDimension(InternationalString name, final Collection<? extends Category>
categories) {
+    public SampleDimension(CharSequence name, final Collection<? extends Category>
categories) {
         ArgumentChecks.ensureNonNull("categories", categories);
         final CategoryList list;
         if (categories.isEmpty()) {
@@ -122,7 +123,7 @@ public class SampleDimension implements Serializable {
                 name = Vocabulary.formatInternational(Vocabulary.Keys.Untitled);
             }
         }
-        this.name        = name;
+        this.name        = Types.toInternationalString(name);
         this.categories  = list;
         transferFunction = list.getTransferFunction();
     }
@@ -151,6 +152,18 @@ public class SampleDimension implements Serializable {
     }
 
     /**
+     * Returns all categories in this sample dimension. Note that a {@link Category} object
may apply to an arbitrary range
+     * of sample values. Consequently, the first element in this collection may not be directly
related to the sample value
+     * {@code 0}.
+     *
+     * @return the list of categories in this sample dimension, or an empty list if none.
+     */
+    @SuppressWarnings("ReturnOfCollectionOrArrayField")
+    public List<Category> getCategories() {
+        return categories;                      // Safe to return because immutable.
+    }
+
+    /**
      * Returns the values to indicate "no data" for this sample dimension.
      *
      * @return the values to indicate no data values for this sample dimension, or an empty
set if none.
@@ -658,7 +671,7 @@ public class SampleDimension implements Serializable {
          * @return the sample dimension.
          */
         public SampleDimension build() {
-            return new SampleDimension(Types.toInternationalString(dimensionName), categories);
+            return new SampleDimension(dimensionName, categories);
         }
     }
 }
diff --git a/core/sis-raster/src/test/java/org/apache/sis/coverage/CategoryTest.java b/core/sis-raster/src/test/java/org/apache/sis/coverage/CategoryTest.java
index c8bf4e1..bf0ab7a 100644
--- a/core/sis-raster/src/test/java/org/apache/sis/coverage/CategoryTest.java
+++ b/core/sis-raster/src/test/java/org/apache/sis/coverage/CategoryTest.java
@@ -16,6 +16,7 @@
  */
 package org.apache.sis.coverage;
 
+import java.util.Collections;
 import java.util.HashSet;
 import java.util.Random;
 import java.util.Set;
@@ -112,7 +113,7 @@ public final strictfp class CategoryTest extends TestCase {
             final double  scale = 10*random.nextDouble() + 0.1;         // Must be positive
for this test.
             final double offset = 10*random.nextDouble() - 5.0;
             final Category category = new Category("Random", NumberRange.create(lower, true,
upper, true),
-                    (MathTransform1D) MathTransforms.linear(scale, offset), null, null);
+                    (MathTransform1D) MathTransforms.linear(scale, offset), null, Collections.emptySet());
 
             assertBoundEquals("range.minValue",     lower,              category.range.getMinValue());
             assertBoundEquals("range.maxValue",     upper,              category.range.getMaxValue());


Mime
View raw message