Interface Coverage

    • Method Summary

      All Methods Instance Methods Abstract Methods 
      Modifier and Type Method Description
      Object evaluate​(DirectPosition point)
      Return the value vector for a given point in the coverage.
      boolean[] evaluate​(DirectPosition point, boolean[] destination)
      Return a sequence of boolean values for a given point in the coverage.
      byte[] evaluate​(DirectPosition point, byte[] destination)
      Return a sequence of unsigned byte values for a given point in the coverage.
      double[] evaluate​(DirectPosition point, double[] destination)
      Return a sequence of double values for a given point in the coverage.
      float[] evaluate​(DirectPosition point, float[] destination)
      Return a sequence of float values for a given point in the coverage.
      int[] evaluate​(DirectPosition point, int[] destination)
      Return a sequence of integer values for a given point in the coverage.
      Set<Record> evaluate​(DirectPosition p, Collection<String> list)
      Returns a set of records of feature attribute values for the specified direct position.
      Set<? extends DomainObject<?>> evaluateInverse​(Record v)
      Returns a set of domain objects for the specified record of feature attribute values.
      GeometryValuePair find​(DirectPosition p)
      Returns the nearest geometry-value pair from the specified direct position.
      List<? extends GeometryValuePair> find​(DirectPosition p, int limit)
      Returns the sequence of geometry-value pairs that include the domain objects nearest to the direct position and their distances from the direction position.
      CommonPointRule getCommonPointRule()
      Identifies the procedure to be used for evaluating the coverage at a position that falls either on a boundary between geometric objects or within the boundaries of two or more overlapping geometric objects.
      CoordinateReferenceSystem getCoordinateReferenceSystem()
      Returns the coordinate reference system to which the objects in its domain are referenced.
      Set<? extends DomainObject<?>> getDomainElements()
      Returns the set of domain objects in the domain.
      Set<Extent> getDomainExtents()
      Returns the extent of the domain of the coverage.
      Envelope getEnvelope()
      The bounding box for the coverage domain in coordinate reference system coordinates.
      int getNumSampleDimensions()
      The number of sample dimensions in the coverage.
      Collection<AttributeValues> getRangeElements()
      Returns the set of attribute values in the range.
      RecordType getRangeType()
      Describes the range of the coverage.
      RenderableImage getRenderableImage​(int xAxis, int yAxis)
      Returns 2D view of this coverage as a renderable image.
      SampleDimension getSampleDimension​(int index)
      Retrieve sample dimension information for the coverage.
      List<? extends Coverage> getSources()
      Returns the sources data for a coverage.
      Set<? extends GeometryValuePair> list()
      Returns the dictionary of geometry-value pairs that contain the objects in the domain of the coverage each paired with its record of feature attribute values.
      Set<? extends GeometryValuePair> select​(Geometry s, Period t)
      Returns the set of geometry-value pairs that contain domain objects that lie within the specified geometry and period.
    • Method Detail

      • getCoordinateReferenceSystem

        @UML(identifier="CRS",
             obligation=MANDATORY,
             specification=ISO_19123)
        CoordinateReferenceSystem getCoordinateReferenceSystem()
        Returns the coordinate reference system to which the objects in its domain are referenced. This is the CRS used when accessing a coverage or grid coverage with the evaluate(\u2026) methods. This coordinate reference system is usually different than coordinate system of the grid. It is the target coordinate reference system of the gridToCRS math transform.

        Grid coverage can be accessed (re-projected) with new coordinate reference system with the GridCoverageProcessor component. In this case, a new instance of a grid coverage is created.

        Returns:
        the coordinate reference system used when accessing a coverage or grid coverage with the evaluate(\u2026) methods.
      • getEnvelope

        @UML(identifier="envelope",
             obligation=MANDATORY,
             specification=OGC_01004)
        Envelope getEnvelope()
        The bounding box for the coverage domain in coordinate reference system coordinates. For grid coverages, the grid cells are centered on each grid coordinate. The envelope for a 2-D grid coverage includes the following corner positions.
         (Minimum row - 0.5, Minimum column - 0.5) for the minimum coordinates
         (Maximum row - 0.5, Maximum column - 0.5) for the maximum coordinates
         
        If a grid coverage does not have any associated coordinate reference system, the minimum and maximum coordinate points for the envelope will be empty sequences.
        Returns:
        the bounding box for the coverage domain in coordinate system coordinates.
        TODO:
        We need to explain the relationship with getDomainExtents(), if any.
      • getDomainExtents

        @UML(identifier="domainExtent",
             obligation=MANDATORY,
             specification=ISO_19123)
        Set<Extent> getDomainExtents()
        Returns the extent of the domain of the coverage. Extents may be specified in space, time or space-time. The collection must contains at least one element.
        Returns:
        the domain extent of the coverage.
      • getDomainElements

        @UML(identifier="domainElement",
             obligation=MANDATORY,
             specification=ISO_19123)
        Set<? extends DomainObject<?>> getDomainElements()
        Returns the set of domain objects in the domain. The collection must contains at least one element.
        Returns:
        the domain elements.
      • getRangeElements

        @UML(identifier="rangeElement",
             obligation=OPTIONAL,
             specification=ISO_19123)
        Collection<AttributeValues> getRangeElements()
        Returns the set of attribute values in the range. The range of a coverage shall be a homogeneous collection of records. That is, the range shall have a constant dimension over the entire domain, and each field of the record shall provide a value of the same attribute type over the entire domain.

        In the case of a discrete coverage, the size of the range collection equals that of the domains collection. In other words, there is one instance of AttributeValues for each instance of DomainObject. Usually, these are stored values that are accessed by the evaluate operation.

        In the case of a continuous coverage, there is a transfinite number of instances of AttributeValues for each DomainObject. A few instances may be stored as input for the evaluate operation, but most are generated as needed by that operation.

        Note: ISO 19123 does not specify how the domain and range associations are to be implemented. The relevant data may be generated in real time, it may be held in persistent local storage, or it may be electronically accessible from remote locations.
        Returns:
        the attribute values in the range.
      • getRangeType

        @UML(identifier="rangeType",
             obligation=MANDATORY,
             specification=ISO_19123)
        RecordType getRangeType()
        Describes the range of the coverage. It consists of a list of attribute name/data type pairs. A simple list is the most common form of range type, but RecordType can be used recursively to describe more complex structures. The range type for a specific coverage shall be specified in an application schema.
        Returns:
        the coverage range.
      • getCommonPointRule

        @UML(identifier="commonPointRule",
             obligation=MANDATORY,
             specification=ISO_19123)
        CommonPointRule getCommonPointRule()
        Identifies the procedure to be used for evaluating the coverage at a position that falls either on a boundary between geometric objects or within the boundaries of two or more overlapping geometric objects. The geometric objects are either domain objects or value objects.
        Returns:
        the procedure for evaluating the coverage on overlapping geometries.
      • list

        @UML(identifier="list",
             obligation=MANDATORY,
             specification=ISO_19123)
        Set<? extends GeometryValuePair> list()
        Returns the dictionary of geometry-value pairs that contain the objects in the domain of the coverage each paired with its record of feature attribute values. In the case of an analytical coverage, the operation shall return the empty set.
        Returns:
        the geometry-value pairs.
      • select

        @UML(identifier="select",
             obligation=MANDATORY,
             specification=ISO_19123)
        Set<? extends GeometryValuePair> select​(Geometry s,
                                                Period t)
        Returns the set of geometry-value pairs that contain domain objects that lie within the specified geometry and period. If s is null, the operation shall return all geometry-value pairs that contain domain objects within t. If the value of t is null, the operation shall return all geometry-value pair that contain domain objects within s. In the case of an analytical coverage, the operation shall return the empty set.
        Parameters:
        s - The spatial component.
        t - The temporal component.
        Returns:
        the values in the given spatio-temporal domain.
      • find

        @UML(identifier="find",
             obligation=MANDATORY,
             specification=ISO_19123)
        List<? extends GeometryValuePair> find​(DirectPosition p,
                                               int limit)
        Returns the sequence of geometry-value pairs that include the domain objects nearest to the direct position and their distances from the direction position. The sequence shall be ordered by distance from the direct position, beginning with the record containing the domain object nearest to the direct position. The length of the sequence (the number of geometry-value pairs returned) shall be no greater than the number specified by the parameter limit. The default shall be to return a single geometry-value pair. The operation shall return a warning if the last domain object in the sequence is at a distance from the direct position equal to the distance of other domain objects that are not included in the sequence. In the case of an analytical coverage, the operation shall return the empty set.
        Note: This operation is useful when the domain of a coverage does not exhaustively partition the extent of the coverage. Even in that case, the first element of the sequence returned may be the geometry-value pair that contains the input direct position.
        Parameters:
        p - The search position.
        limit - The maximal size of the list to be returned.
        Returns:
        the geometry-value pairs nearest to the given position.
      • find

        @UML(identifier="find",
             obligation=MANDATORY,
             specification=ISO_19123)
        GeometryValuePair find​(DirectPosition p)
        Returns the nearest geometry-value pair from the specified direct position. This is a shortcut for find(p,1).
        Parameters:
        p - The search position.
        Returns:
        the geometry-value pair nearest to the given position.
      • evaluate

        @UML(identifier="evaluate",
             obligation=MANDATORY,
             specification=ISO_19123)
        Set<Record> evaluate​(DirectPosition p,
                             Collection<String> list)
                      throws PointOutsideCoverageException,
                             CannotEvaluateException
        Returns a set of records of feature attribute values for the specified direct position. The parameter list is a sequence of feature attribute names each of which identifies a field of the range type. If list is null, the operation shall return a value for every field of the range type. Otherwise, it shall return a value for each field included in list. If the direct position passed is not in the domain of the coverage, then an exception is thrown. If the input direct position falls within two or more geometric objects within the domain, the operation shall return records of feature attribute values computed according to the common point rule.
        Note: Normally, the operation will return a single record of feature attribute values.
        Parameters:
        p - The position where to evaluate.
        list - The field of interest, or null for every fields.
        Returns:
        the feature attributes.
        Throws:
        PointOutsideCoverageException - if the point is outside the coverage domain.
        CannotEvaluateException - if the point can not be evaluated for some other reason.
      • evaluate

        @UML(identifier="evaluate",
             obligation=MANDATORY,
             specification=OGC_01004)
        Object evaluate​(DirectPosition point)
                 throws PointOutsideCoverageException,
                        CannotEvaluateException
        Return the value vector for a given point in the coverage. A value for each sample dimension is included in the vector. The default interpolation type used when accessing grid values for points which fall between grid cells is nearest neighbor. The coordinate reference system of the point is the same as the grid coverage coordinate reference system (specified by the getCoordinateReferenceSystem() method).
        Warning: This method is inherited from the legacy OGC 01-004 specification and may be deprecated in a future version. We are for more experience and feedbacks on the value of this method.
        Parameters:
        point - Point at which to find the grid values.
        Returns:
        the value vector for a given point in the coverage.
        Throws:
        PointOutsideCoverageException - if the point is outside the coverage envelope.
        CannotEvaluateException - if the point can not be evaluated for some other reason.
        See Also:
        Raster.getDataElements(int, int, Object)
      • evaluate

        @UML(identifier="evaluateAsBoolean",
             obligation=MANDATORY,
             specification=OGC_01004)
        boolean[] evaluate​(DirectPosition point,
                           boolean[] destination)
                    throws PointOutsideCoverageException,
                           CannotEvaluateException,
                           ArrayIndexOutOfBoundsException
        Return a sequence of boolean values for a given point in the coverage. A value for each sample dimension is included in the sequence. The default interpolation type used when accessing grid values for points which fall between grid cells is nearest neighbor.

        The coordinate reference system of the point is the same as the grid coverage coordinate reference system (specified by the getCoordinateReferenceSystem() method).

        Parameters:
        point - Point at which to find the coverage values.
        destination - An optionally preallocated array in which to store the values, or null if none.
        Returns:
        a sequence of boolean values for a given point in the coverage. If destination was non-null, then it is returned. Otherwise, a new array is allocated and returned.
        Throws:
        PointOutsideCoverageException - if the point is outside the coverage envelope.
        CannotEvaluateException - if the point can not be evaluated for some othe reason.
        ArrayIndexOutOfBoundsException - if the destination array is not null and too small to hold the output.
      • evaluate

        @UML(identifier="evaluateAsByte",
             obligation=MANDATORY,
             specification=OGC_01004)
        byte[] evaluate​(DirectPosition point,
                        byte[] destination)
                 throws PointOutsideCoverageException,
                        CannotEvaluateException,
                        ArrayIndexOutOfBoundsException
        Return a sequence of unsigned byte values for a given point in the coverage. A value for each sample dimension is included in the sequence. The default interpolation type used when accessing grid values for points which fall between grid cells is nearest neighbor.

        The coordinate reference system of the point is the same as the grid coverage coordinate reference system (specified by the getCoordinateReferenceSystem() method).

        Parameters:
        point - Point at which to find the coverage values.
        destination - An optionally preallocated array in which to store the values, or null if none.
        Returns:
        a sequence of unsigned byte values for a given point in the coverage. If destination was non-null, then it is returned. Otherwise, a new array is allocated and returned.
        Throws:
        PointOutsideCoverageException - if the point is outside the coverage envelope.
        CannotEvaluateException - if the point can not be evaluated for some othe reason.
        ArrayIndexOutOfBoundsException - if the destination array is not null and too small to hold the output.
      • evaluate

        @UML(identifier="evaluateAsInteger",
             obligation=MANDATORY,
             specification=OGC_01004)
        int[] evaluate​(DirectPosition point,
                       int[] destination)
                throws PointOutsideCoverageException,
                       CannotEvaluateException,
                       ArrayIndexOutOfBoundsException
        Return a sequence of integer values for a given point in the coverage. A value for each sample dimension is included in the sequence. The default interpolation type used when accessing grid values for points which fall between grid cells is nearest neighbor.

        The coordinate reference system of the point is the same as the grid coverage coordinate reference system (specified by the getCoordinateReferenceSystem() method).

        Parameters:
        point - Point at which to find the grid values.
        destination - An optionally preallocated array in which to store the values, or null if none.
        Returns:
        a sequence of integer values for a given point in the coverage. If destination was non-null, then it is returned. Otherwise, a new array is allocated and returned.
        Throws:
        PointOutsideCoverageException - if the point is outside the coverage envelope.
        CannotEvaluateException - if the point can not be evaluated for some othe reason.
        ArrayIndexOutOfBoundsException - if the destination array is not null and too small to hold the output.
        See Also:
        Raster.getPixel(int, int, int[])
      • evaluate

        float[] evaluate​(DirectPosition point,
                         float[] destination)
                  throws PointOutsideCoverageException,
                         CannotEvaluateException,
                         ArrayIndexOutOfBoundsException
        Return a sequence of float values for a given point in the coverage. A value for each sample dimension is included in the sequence. The default interpolation type used when accessing grid values for points which fall between grid cells is nearest neighbor.

        The coordinate reference system of the point is the same as the grid coverage coordinate reference system (specified by the getCoordinateReferenceSystem() method).

        Parameters:
        point - Point at which to find the grid values.
        destination - An optionally preallocated array in which to store the values, or null if none.
        Returns:
        a sequence of float values for a given point in the coverage. If destination was non-null, then it is returned. Otherwise, a new array is allocated and returned.
        Throws:
        PointOutsideCoverageException - if the point is outside the coverage envelope.
        CannotEvaluateException - if the point can not be evaluated for some othe reason.
        ArrayIndexOutOfBoundsException - if the destination array is not null and too small to hold the output.
        See Also:
        Raster.getPixel(int, int, float[])
      • evaluate

        @UML(identifier="evaluateAsDouble",
             obligation=MANDATORY,
             specification=OGC_01004)
        double[] evaluate​(DirectPosition point,
                          double[] destination)
                   throws PointOutsideCoverageException,
                          CannotEvaluateException,
                          ArrayIndexOutOfBoundsException
        Return a sequence of double values for a given point in the coverage. A value for each sample dimension is included in the sequence. The default interpolation type used when accessing grid values for points which fall between grid cells is nearest neighbor.

        The coordinate reference system of the point is the same as the grid coverage coordinate reference system (specified by the getCoordinateReferenceSystem() method).

        Parameters:
        point - Point at which to find the grid values.
        destination - An optionally preallocated array in which to store the values, or null if none.
        Returns:
        a sequence of double values for a given point in the coverage. If destination was non-null, then it is returned. Otherwise, a new array is allocated and returned.
        Throws:
        PointOutsideCoverageException - if the point is outside the coverage envelope.
        CannotEvaluateException - if the point can not be evaluated for some othe reason.
        ArrayIndexOutOfBoundsException - if the destination array is not null and too small to hold the output.
        See Also:
        Raster.getPixel(int, int, double[])
        Departure from OGC/ISO specification:
        OGC 01-004 defines this method as evaluate(DirectPosition). GeoAPI adds the double[] argument for reusing pre-allocated arrays, which is consistent with usage in java.awt.image.Raster.
      • evaluateInverse

        @UML(identifier="evaluateInverse",
             obligation=MANDATORY,
             specification=ISO_19123)
        Set<? extends DomainObject<?>> evaluateInverse​(Record v)
        Returns a set of domain objects for the specified record of feature attribute values. Normally, this method returns the set of objects in the domain that are associated with values equal to those in the input record. However, the operation may return other objects derived from those in the domain, as specified by the application schema.
        Example: The evaluateInverse operation could return a set of contours derived from the feature attribute values associated with the grid points of a grid coverage.
        Parameters:
        v - The feature attributes.
        Returns:
        the domain where the attributes are found.
      • getNumSampleDimensions

        @UML(identifier="numSampleDimensions",
             obligation=MANDATORY,
             specification=OGC_01004)
        int getNumSampleDimensions()
        The number of sample dimensions in the coverage. For grid coverages, a sample dimension is a band.
        Warning: This method is inherited from the legacy OGC 01-004 specification and may be deprecated in a future version. We are for more experience and feedbacks on the value of this method.
        Returns:
        the number of sample dimensions in the coverage.
      • getSampleDimension

        @UML(identifier="getSampleDimension",
             obligation=MANDATORY,
             specification=OGC_01004)
        SampleDimension getSampleDimension​(int index)
                                    throws IndexOutOfBoundsException
        Retrieve sample dimension information for the coverage. For a grid coverage a sample dimension is a band. The sample dimension information include such things as description, data type of the value (bit, byte, integer...), the no data values, minimum and maximum values and a color table if one is associated with the dimension. A coverage must have at least one sample dimension.
        Warning: This method is inherited from the legacy OGC 01-004 specification and may be deprecated in a future version. We are for more experience and feedbacks on the value of this method.
        Parameters:
        index - Index for sample dimension to retrieve. Indices are numbered 0 to (n-1).
        Returns:
        Sample dimension information for the coverage.
        Throws:
        IndexOutOfBoundsException - if index is out of bounds.
      • getSources

        @UML(identifier="getSource, numSource",
             obligation=MANDATORY,
             specification=OGC_01004)
        List<? extends Coverage> getSources()
        Returns the sources data for a coverage. This is intended to allow applications to establish what Coverages will be affected when others are updated, as well as to trace back to the "raw data".

        This implementation specification does not include interfaces for creating collections of coverages therefore the list size will usually be one indicating an adapted grid coverage, or zero indicating a raw grid coverage.

        Warning: This method is inherited from the legacy OGC 01-004 specification and may be deprecated in a future version. We are for more experience and feedbacks on the value of this method.
        Returns:
        the list of sources data for a coverage.
        Departure from OGC/ISO specification:
        Return type of Coverage.getSource(int) has been relaxed from GridCoverage to Coverage. Instead, the return type has been constrained to GridCoverage only in GridCoverage.getSource(int). This approach (return type covariance) was already used in "Spatial Referencing by Coordinates" (ISO 19111). It avoid forward dependency of Coverage toward GridCoverage and give more flexibility for use of Coverage with non-gridded sources.