[Possible feature?] Points and polygons from plus codes

[aazuspan]

Hi @davemlz. First of all, eemont is a great tool. Thanks for creating it!

I'm not sure if you're familiar with open location code, but it's a geocoding tool that generates more readable coordinates (aka plus codes) from latitude/longitude (e.g. [39.777062, -105.006438] == 85FPQXGV+RC). Plus codes can also be shortened by including a nearby location (e.g. 85FPQXGV+RC == QXGV+RC Denver, CO).

It would be handy to have a tool for generating EE geometries from plus codes, and I was wondering if you think it would fit in eemont? Unfortunately there are no open web APIs that I know of to decode plus codes, so it would require adding openlocationcode as a dependency.

As far as implementation, I'm thinking it would extend ee.Geometry with a few static methods using your decorators. To handle shortened plus codes, an address could be geocoded using the same approach you use for ee.Geometry.PointFromQuery. Another feature might be the ability to retrieve a plus code from an ee.Geometry.Point. Usage might look something like below.

# Create a point from a full plus code
pt = ee.Geometry.PointFromPlusCode("85FPQXGV+RC")
# Create a point from a partial plus code and a nearby location reference
pt = ee.Geometry.PointFromPlusCode("QXGV+RC Denver, CO")
# Create a polygon from a list of plus codes
poly = ee.Geometry.PolygonFromPlusCodes(
    ["85GGXXJ2+R6"],
    ["85GVXVRV+5H"],
    ["859V2WJG+FQ"],
    ["859G2WQH+XF"]
)

# Create a point from coordinates
pt = ee.Geometry.Point([39.777062, -105.006438])
# Get the plus code of the point
pt.plus_code()

>> "85FPQXGV+RC"

If you think this would fit in eemont and it's worth adding another dependency for the feature, I'd be happy to implement and make a PR. If not, no worries! It could work as a little standalone package instead.

[davemlz]

Hi, @aazuspan!

This is a really awesome idea! I heard about Plus Codes last year and I think they're amazing and a perfect fit for eemont, as you are saying!

There is just one issue with openlocationcode: it is not on conda-forge, and right now I'm waiting for the conda-forge team for the review of eemont. But I think we can tackle this issue. I'll explain the idea here:

Since each Plus Code represents a pair of coordinates, I think that we can create constructors for all EE geometries:

• ee.Geometry.PointFromPlusCode
• ee.Geometry.MultiPointFromPlusCode
• ee.Geometry.PolygonFromPlusCode
• ee.Geometry.MultiPolygonFromPlusCode
• ee.Geometry.LineStringFromPlusCode
• ee.Geometry.MultiLineStringFromPlusCode
• ee.Geometry.LinearRingFromPlusCode
• ee.Geometry.RectangleFromPlusCode
• ee.Geometry.BBoxFromPlusCode

All these constructors require a pair of coordinates, or a list of pairs of coordinates, or a nested list of pairs of coordinates. Taking this into account, I think that a private function can be created in the common.py (this is the module where I store all common functions for extending EE objects) that converts a Plus Code, or a list of Plus Codes, or a nested list of Plus Codes, into a pair of coordinates, a list of pairs of coordinates, or a nested list of pairs of coordinates, and then, create each one of the constructors in the geometry.py module using this private function from the common.py module.

However, we still have the openlocationcode issue. I think we can still use it as a Soft Dependency. We can use the package (that is available from PyPI), but without listing it in the requirements of eemont. See this:

def _convert_pluscode_to_coordinates(pluscode):
    """Converts a Plus Code, or a list of Plus Codes, into a pair of coordinates, or a list of pairs of coordinates.

    Parameters
    ---------------
    pluscode: str, list[str]
        Plus Code, or list of Plus Codes.

    Returns
    -------
    list
        Coordinates, or list of coordinates.
    """
    try:
        import openlocationcode
    except:
        raise Exception("openlocationcode could not be loaded. Please make sure openlocation code is installed...")

    coordinates = "something..."

    return coordinates

I think that in this way we can avoid requiring openlocationcode as a dependency, but still using it. Of course it is just a simple example, but we can give more detailed instructions to the community, or create a more robust function that installs the package. After this function is created (in the common.py module), the constructors in the geometry.py module can be created by using it:

from .common import _convert_pluscode_to_coordinates

@_extend_staticmethod_eeGeometry()
def PointFromPlusCode(pluscode):
    """Constructs an ee.Geometry describing a point from a pluscode by using the openlocationcode package.

    Tip
    ----------
    Check more info about constructors in the :ref:`User Guide<Constructors>`.

    Parameters
    ----------
    pluscode: str
        Plus Code.

    Returns
    -------
    ee.Geometry.Point
        Geometry describing a point from the specified pluscode.

    See Also
    --------
    MultiPointFromPlusCode : Constructs an ee.Geometry describing a MultiPoint from a pluscode by using the openlocationcode package.

    Examples
    --------
    >>> import ee, eemont
    >>> ee.Authenticate()
    >>> ee.Initialize()
    >>> ee.Geometry.PointFromPlusCode("85GGXXJ2+R6")
    """
    coordinates = _convert_pluscode_to_coordinates(pluscode)
    return ee.Geometry.Point(coordinates)

What do you think?

Ah! And the idea of retrieving the PlusCode from a point is great! Just one thing, by following the standard names of Earth Engine, I'm trying not to use "_" for public functions, maybe renaming it as:

# Create a point from coordinates
pt = ee.Geometry.Point([39.777062, -105.006438])
# Get the plus code of the point
pt.plusCode()
>> "85FPQXGV+RC"

And since this one is not a static method, another decorator must be created.

Let me know if you're interested in adding these features, and I'd be more than happy if you implement it! :) Just let me know and I'll assign you this Issue, I'll create the decorator that is required for the geometry.py module and then you can submit the PR!

Oh! And before I forget, in the tests folder there is a file for the geometry.py module (test_geometry.py). There you can test the features!

[aazuspan]

That sounds like a solid design! And I think the soft dependency is a good workaround for the conda-forge issue. I'll also open an issue at openlocationcode suggesting they add it to conda-forge, but I don't think development is very active there.

Please do assign me this issue and create the non-static decorator whenever you get the chance. I'll start putting together the features and tests and submit a PR when they're ready!

[davemlz]

Perfect! I'll create the decorator and let you know!

PD: Let's hope the guys at openlocationcode see the issue!

Thank you, @aazuspan!

[davemlz]

I have added new decorators for ee.Geometry, ee.Feature and ee.FeatureCollection object classes:

@_extend_eeGeometry()
@_extend_eeFeature()
@_extend_eeFeatureCollection()

For this case, the decorator for ee.Geometry would be the one. I was thinking that the .plusCode() method could be maybe added for the ee.Feature class, but I'm not sure about it.

Let me know!

And if you require anything, just tell me! :)