GeoAPI
  1. GeoAPI
  2. GEO-135

DirectPosition.getCoordinates() should be singular

    Details

    • Type: Bug Bug
    • Status: Closed Closed
    • Priority: Minor Minor
    • Resolution: Fixed
    • Affects Version/s: 2.1
    • Fix Version/s: 2.2-M1
    • Component/s: coverage, geometry
    • Labels:
      None
    • Patch Submitted:
      Yes
    • Number of attachments :
      1

      Description

      A coordinate is a collection of ordinates. DirectPosition can be considered a structure consisting of one group of ordinates and some referent describing what those ordinates mean. Therefore DirectPosition "has" one single coordinate and the method name should be:

      DirectPosition.getCoordinate()    // note the singular
      

      Note that ISO 19107 uses the singular form as well.

      FIx will be to add the method above, deprecate DirectPosition.getCoordinates() and fix the javadoc.

      Reference: DirectPosition.getCoordinates() javadoc

      patch attached.

        Activity

        Martin Desruisseaux made changes -
        Field Original Value New Value
        Description A cooridinate is a collection of ordinates. DirectPosition can be considered a structure consisting of one group of ordinates and some referent describing what those ordinates mean. Therefore DirectPosition "has" one single coordinate and the method name should be:

        DirectPosition.getCoordinate() //note the singular


        FIx will be to add the method above, deprecate
        DirectPosition.getCoordinates()
        and fix the javadoc.

        patch attached
        A coordinate is a collection of ordinates. {{DirectPosition}} can be considered a structure consisting of one group of ordinates and some referent describing what those ordinates mean. Therefore {{DirectPosition}} "has" one single coordinate and the method name should be:

        {code:java}
        DirectPosition.getCoordinate() //note the singular
        {code}

        Note that ISO 19107 uses the singular form as well.

        FIx will be to add the method above, deprecate {{DirectPosition.getCoordinates()}} and fix the javadoc.

        patch attached.
        Priority Major [ 3 ] Minor [ 4 ]
        Martin Desruisseaux made changes -
        Description A coordinate is a collection of ordinates. {{DirectPosition}} can be considered a structure consisting of one group of ordinates and some referent describing what those ordinates mean. Therefore {{DirectPosition}} "has" one single coordinate and the method name should be:

        {code:java}
        DirectPosition.getCoordinate() //note the singular
        {code}

        Note that ISO 19107 uses the singular form as well.

        FIx will be to add the method above, deprecate {{DirectPosition.getCoordinates()}} and fix the javadoc.

        patch attached.
        A coordinate is a collection of ordinates. {{DirectPosition}} can be considered a structure consisting of one group of ordinates and some referent describing what those ordinates mean. Therefore {{DirectPosition}} "has" one single coordinate and the method name should be:

        {code:java}
        DirectPosition.getCoordinate() // note the singular
        {code}

        Note that ISO 19107 uses the singular form as well.

        FIx will be to add the method above, deprecate {{DirectPosition.getCoordinates()}} and fix the javadoc.

        http://geoapi.sourceforge.net/2.2/javadoc/org/opengis/geometry/DirectPosition.html#getCoordinates()

        patch attached.
        Martin Desruisseaux made changes -
        Description A coordinate is a collection of ordinates. {{DirectPosition}} can be considered a structure consisting of one group of ordinates and some referent describing what those ordinates mean. Therefore {{DirectPosition}} "has" one single coordinate and the method name should be:

        {code:java}
        DirectPosition.getCoordinate() // note the singular
        {code}

        Note that ISO 19107 uses the singular form as well.

        FIx will be to add the method above, deprecate {{DirectPosition.getCoordinates()}} and fix the javadoc.

        http://geoapi.sourceforge.net/2.2/javadoc/org/opengis/geometry/DirectPosition.html#getCoordinates()

        patch attached.
        A coordinate is a collection of ordinates. {{DirectPosition}} can be considered a structure consisting of one group of ordinates and some referent describing what those ordinates mean. Therefore {{DirectPosition}} "has" one single coordinate and the method name should be:

        {code:java}
        DirectPosition.getCoordinate() // note the singular
        {code}

        Note that ISO 19107 uses the singular form as well.

        FIx will be to add the method above, deprecate {{DirectPosition.getCoordinates()}} and fix the javadoc.

        Reference: [DirectPosition.getCoordinates() javadoc|http://geoapi.sourceforge.net/2.2/javadoc/org/opengis/geometry/DirectPosition.html#getCoordinates()]

        patch attached.
        Hide
        Martin Desruisseaux added a comment -

        ISO 19111 said:

        In this International Standard, a coordinate is one of n scalar values that define the position of a single point. In other contexts, the term ordinate is used for a single value and coordinate for multiple ordinates. Such usage is not part of this International Standard.

        A coordinate tuple is an ordered list of n coordinates that define the position of a single point. In this International Standard, the coordinate tuple shall be composed of one, two or three spatial coordinates.

        However other standards (ISO 19107, ISO 19123) seems to use "coordinate" in the sense of "coordinate tuple". The following classes are singular in ISO standards:

        • TM_Coordinate in ISO 19108
        • CV_GridCoordinate in ISO 19123. Note that the ISO document mixes the singular and plural forms (both in textual description and in UML diagrams), but the later seems to be a typo since the section which is precisely about CV_GridCoordinate uses the singular form.

        We need to bring a little bit more consistency in GeoAPI. Using the singular form seems reasonable, but in such case we need to rename GridCoordinates as well:

        Show
        Martin Desruisseaux added a comment - ISO 19111 said: In this International Standard, a coordinate is one of n scalar values that define the position of a single point. In other contexts, the term ordinate is used for a single value and coordinate for multiple ordinates. Such usage is not part of this International Standard. A coordinate tuple is an ordered list of n coordinates that define the position of a single point. In this International Standard, the coordinate tuple shall be composed of one, two or three spatial coordinates. However other standards (ISO 19107, ISO 19123) seems to use "coordinate" in the sense of "coordinate tuple". The following classes are singular in ISO standards: TM_Coordinate in ISO 19108 CV_GridCoordinate in ISO 19123. Note that the ISO document mixes the singular and plural forms (both in textual description and in UML diagrams), but the later seems to be a typo since the section which is precisely about CV_GridCoordinate uses the singular form. We need to bring a little bit more consistency in GeoAPI. Using the singular form seems reasonable, but in such case we need to rename GridCoordinates as well: TemporalCoordinate javadoc GridCoordinates javadoc
        Martin Desruisseaux made changes -
        Component/s coverage [ 11093 ]
        Hide
        Martin Desruisseaux added a comment -

        In the particular case of DirectPosition.getCoordinates(), we are returning an array of double primitive type, not a single object. The singular form would be appropriate for the class name (so GridCoordinates needs to be renamed). But for this method returning an array, I think that "coordinates" is to be understood in the ISO 19111 sense (see above comment), so the plural form would be appropriate.

        However I admit that this is confusing given the various interpretation given to "coordinates". A possible fix is to name this method as "getCoordinateValues()" instead. It would have the beneficial side-effect to be consistent with method names in GridCoordinate and TemporalCoordinate (see javadoc links in above comment).

        If we perform such renaming, then we need to consider if we should rename get/setOrdinate(int) as get/setCoordinateValue(int) for consistency.

        Show
        Martin Desruisseaux added a comment - In the particular case of DirectPosition.getCoordinates() , we are returning an array of double primitive type, not a single object. The singular form would be appropriate for the class name (so GridCoordinates needs to be renamed). But for this method returning an array, I think that "coordinates" is to be understood in the ISO 19111 sense (see above comment), so the plural form would be appropriate. However I admit that this is confusing given the various interpretation given to "coordinates". A possible fix is to name this method as "getCoordinateValues()" instead. It would have the beneficial side-effect to be consistent with method names in GridCoordinate and TemporalCoordinate (see javadoc links in above comment). If we perform such renaming, then we need to consider if we should rename get/setOrdinate(int) as get/setCoordinateValue(int) for consistency.
        Hide
        Adrian Custer added a comment -

        Yes, 19111 has a non-mathematical, sloppy use of coordinate for ordinate. The only consistency we could salvage from this mess would be to use ordinate for the single numerical value and tuple for the grouped set of coherent values, deprecating all uses of coordinate. That's probably too radical a move so we are stuck trying to be consistent across less than the whole library. At least within a particular module it's critical to be internally consistent. ISO Geometry, aka 19107, is internally perfectly consistent and matches standard mathematical language so there appears no reason to break that internal consistency to match other specs written by people closer to geodesy than to geometry.

        Did you really mean getCoordinateValue*s*() ? That's getting even more confusing.

        I don't really buy the "you have to have a class to have a single structure" argument. An array of data is a perfectly acceptable single data structure so getCoordinate(): double[] seems perfectly clear from that stand point.

        That said, if we want to emphasize that we are always returning the data by value and not by reference, we could append "value" to all our method names. To be consistent we start having to rename all methods to get*Value()---it seems easier to state in the javadoc that data elements are passed out by value and not by reference. We need to do this anyhow since we can't really have methods getDirectPositionValue().

        So far given the choices, the original modification still seems the best.

        Show
        Adrian Custer added a comment - Yes, 19111 has a non-mathematical, sloppy use of coordinate for ordinate. The only consistency we could salvage from this mess would be to use ordinate for the single numerical value and tuple for the grouped set of coherent values, deprecating all uses of coordinate. That's probably too radical a move so we are stuck trying to be consistent across less than the whole library. At least within a particular module it's critical to be internally consistent. ISO Geometry, aka 19107, is internally perfectly consistent and matches standard mathematical language so there appears no reason to break that internal consistency to match other specs written by people closer to geodesy than to geometry. Did you really mean getCoordinateValue*s*() ? That's getting even more confusing. I don't really buy the "you have to have a class to have a single structure" argument. An array of data is a perfectly acceptable single data structure so getCoordinate(): double[] seems perfectly clear from that stand point. That said, if we want to emphasize that we are always returning the data by value and not by reference, we could append "value" to all our method names. To be consistent we start having to rename all methods to get*Value()---it seems easier to state in the javadoc that data elements are passed out by value and not by reference. We need to do this anyhow since we can't really have methods getDirectPositionValue(). So far given the choices, the original modification still seems the best.
        Hide
        Martin Desruisseaux added a comment -

        Commited as of revision 1251.

        Show
        Martin Desruisseaux added a comment - Commited as of revision 1251.
        Martin Desruisseaux made changes -
        Resolution Fixed [ 1 ]
        Status Open [ 1 ] Closed [ 6 ]
        Assignee Martin Desruisseaux [ desruisseaux ]
        Martin Desruisseaux made changes -
        Resolution Fixed [ 1 ]
        Status Closed [ 6 ] Reopened [ 4 ]
        Martin Desruisseaux made changes -
        Fix Version/s 2.2 [ 12386 ]
        Resolution Fixed [ 1 ]
        Fix Version/s 2.2-M1 [ 14472 ]
        Status Reopened [ 4 ] Closed [ 6 ]

          People

          • Assignee:
            Martin Desruisseaux
            Reporter:
            Adrian Custer
          • Votes:
            0 Vote for this issue
            Watchers:
            0 Start watching this issue

            Dates

            • Created:
              Updated:
              Resolved: