sis-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From desruisse...@apache.org
Subject [sis] 05/05: Initial draft of SampleDimension class for coverages.
Date Thu, 29 Nov 2018 18:09:21 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 616a963d335599026643aff6d67468c2309fe27a
Author: Martin Desruisseaux <martin.desruisseaux@geomatys.com>
AuthorDate: Thu Nov 29 19:09:00 2018 +0100

    Initial draft of SampleDimension class for coverages.
---
 .../org/apache/sis/coverage/SampleDimension.java   | 161 +++++++++++++++++++++
 .../java/org/apache/sis/coverage/package-info.java |  30 ++++
 .../operation/transform/TransferFunction.java      |   5 +-
 3 files changed, 195 insertions(+), 1 deletion(-)

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
new file mode 100644
index 0000000..62bbc58
--- /dev/null
+++ b/core/sis-raster/src/main/java/org/apache/sis/coverage/SampleDimension.java
@@ -0,0 +1,161 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements.  See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License.  You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.apache.sis.coverage;
+
+import java.util.Optional;
+import javax.measure.Unit;
+import org.opengis.util.InternationalString;
+import org.opengis.referencing.operation.MathTransform1D;
+import org.apache.sis.measure.NumberRange;
+import org.apache.sis.util.Classes;
+
+
+/**
+ * Describes the data values in a coverage (the range) when those values are numbers.
+ * For a grid coverage or a raster, a sample dimension may be a band.
+ *
+ * <div class="section">Relationship with metadata</div>
+ * This class provides the same information than ISO 19115 {@link org.opengis.metadata.content.SampleDimension},
+ * but organized in a different way. The use of the same name may seem a risk, but those
two types are typically
+ * not used in same time.
+ *
+ * @author  Martin Desruisseaux (Geomatys)
+ * @version 1.0
+ * @since   1.0
+ * @module
+ */
+public class SampleDimension {
+    /**
+     * Description for this sample dimension. Typically used as a way to perform a band select
by
+     * using human comprehensible descriptions instead of just numbers. Web Coverage Service
(WCS)
+     * can use this name in order to perform band sub-setting as directed from a user request.
+     */
+    private final InternationalString name;
+
+    /**
+     * The range of sample values.
+     * May be {@code null} if this sample dimension has no non-{@code NaN} value.
+     */
+    private final NumberRange<?> range;
+
+    /**
+     * The values to indicate "no data" for this sample dimension.
+     */
+    private final Number[] noDataValues;
+
+    /**
+     * The transform from sample to geophysics value. May be {@code null} if this sample
dimension
+     * do not defines any transform (which is not the same that defining an identity transform).
+     */
+    private final MathTransform1D transferFunction;
+
+    /**
+     * The units of measurement for this sample dimension, or {@code null} if not applicable.
+     */
+    private final Unit<?> units;
+
+    /**
+     * Creates a sample dimension with the specified properties.
+     *
+     * @param name     the sample dimension title or description.
+     * @param nodata   the values to indicate "no data".
+     * @param range    the range of sample values.
+     * @param toUnit   the transfer function for converting sample values to geophysics values
in {@code units}.
+     * @param units    the units of measurement for this sample dimension, or {@code null}
if not applicable.
+     */
+    <T extends Number & Comparable<? super T>> SampleDimension(
+            final InternationalString name,
+            final NumberRange<T>      range,
+            final T[]                 nodata,
+            final MathTransform1D     toUnit,
+            final Unit<?>             units)
+    {
+        this.name             = name;
+        this.range            = range;
+        this.noDataValues     = nodata;
+        this.transferFunction = toUnit;
+        this.units            = units;
+    }
+
+    /**
+     * Returns a name or description for this sample dimension. This is typically used as
a way to perform a band select
+     * by using human comprehensible descriptions instead of just numbers. Web Coverage Service
(WCS) can use this name
+     * in order to perform band sub-setting as directed from a user request.
+     *
+     * @return The title or description of this sample dimension.
+     */
+    public InternationalString getName() {
+        return name;
+    }
+
+    /**
+     * 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
array if none.
+     */
+    public Number[] getNoDataValues() {
+        return noDataValues.clone();
+    }
+
+    /**
+     * Returns the range of values in this sample dimension.
+     * May be absent if this sample dimension has no non-{@code NaN} value.
+     *
+     * @return the range of values.
+     */
+    public Optional<NumberRange<?>> getRange() {
+        return Optional.ofNullable(range);
+    }
+
+    /**
+     * Returns the <cite>transfer function</cite> from sample values to geophysics
values.
+     * This method returns a transform expecting sample values as input and computing geophysics
values as output.
+     * This transform will take care of converting all "{@linkplain #getNoDataValues() no
data values}" into {@code NaN} values.
+     * The <code>transferFunction.{@linkplain MathTransform1D#inverse() inverse()}</code>
transform is capable to differentiate
+     * {@code NaN} values to get back the original sample value.
+     *
+     * @return The <cite>transfer function</cite> from sample to geophysics values.
May be absent if this sample dimension
+     *         do not defines any transform (which is not the same that defining an identity
transform).
+     *
+     * @see org.apache.sis.referencing.operation.transform.TransferFunction
+     */
+    public Optional<MathTransform1D> getTransferFunction() {
+        return Optional.ofNullable(transferFunction);
+    }
+
+    /**
+     * Returns the units of measurement for this sample dimension.
+     * This unit applies to values obtained after the {@linkplain #getTransferFunction()
transfer function}.
+     * May be absent if not applicable.
+     *
+     * @return the units of measurement.
+     */
+    public Optional<Unit<?>> getUnits() {
+        return Optional.ofNullable(units);
+    }
+
+    /**
+     * Returns a string representation of this sample dimension.
+     * This string is for debugging purpose only and may change in future version.
+     *
+     * @return a string representation of this sample dimension for debugging purpose.
+     */
+    @Override
+    public String toString() {
+        return Classes.getShortClassName(this) + "[“" + name + "”]";
+    }
+}
diff --git a/core/sis-raster/src/main/java/org/apache/sis/coverage/package-info.java b/core/sis-raster/src/main/java/org/apache/sis/coverage/package-info.java
new file mode 100644
index 0000000..6bdf0cc
--- /dev/null
+++ b/core/sis-raster/src/main/java/org/apache/sis/coverage/package-info.java
@@ -0,0 +1,30 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements.  See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License.  You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+
+/**
+ * Functions that associates positions within a bounded space (its domain) to values (its
range).
+ * This package makes no assumption on the domain geometry; it is not necessarily a grid.
+ * For the most common case — a coverage backed by a regular grid (also called "raster")
— see
+ * {@link org.apache.sis.coverage.grid}.
+ *
+ * @author  Martin Desruisseaux (Geomatys)
+ * @version 1.0
+ * @since   1.0
+ * @module
+ */
+package org.apache.sis.coverage;
diff --git a/core/sis-referencing/src/main/java/org/apache/sis/referencing/operation/transform/TransferFunction.java
b/core/sis-referencing/src/main/java/org/apache/sis/referencing/operation/transform/TransferFunction.java
index 7a138eb..77fd203 100644
--- a/core/sis-referencing/src/main/java/org/apache/sis/referencing/operation/transform/TransferFunction.java
+++ b/core/sis-referencing/src/main/java/org/apache/sis/referencing/operation/transform/TransferFunction.java
@@ -59,7 +59,10 @@ import org.apache.sis.referencing.operation.matrix.Matrix2;
  *
  * @author  Martin Desruisseaux (Geomatys)
  * @version 1.0
- * @since   0.5
+ *
+ * @see org.apache.sis.coverage.SampleDimension#getTransferFunction()
+ *
+ * @since 0.5
  * @module
  */
 public class TransferFunction implements Cloneable, Serializable {


Mime
View raw message