Allow alternative input coordinate reference systems.

rgwozdz commented 3 years ago

This PR adds functionality for winnow to geometrically filter and transform input data that uses various coordinate systems as opposed to just WGS84. Non-WGS84 input datasets are defined by:

the inputCrs option. This can be the well-known id or well-known text of the coordinate system
the "named" crs property of a GeoJSON feature collection input object

Winnow depends on proj4 for projecting, and this library only supports a few well-known ids. A follow-on PR will use exisiting dependencies to convert well-known ids set with inputCrs to their well-known text equivalents.

rgwozdz commented 3 years ago

@haoliangyu - There is a lot of variation in option names, and a lot of these alternative option names remain so we do not introduce breaking changes. A few are there due to direct support for Geoservices API query parameters. Here is a breakdown:

Option names for input data coordinate system:

sourceSR - this is an undocumented, legacy name. It was added specifically for use with the preparedQuery by opendata-koop. It's no longer used there and it is unclear if other parties are currently using it.
inputCrs - the new option name added in this PR. Added because it is more descriptive and is camelCase

Option names for output coordinate system

projection - legacy and documented, but not (in my opinion) a good description of what the variable actually contains and refers to
srsname - legacy and undocumented
srsName - legacy and undocumented
outSR - a Geoservices API query parameter, documented. I assume this was added at some point to allow FeatureServer to pass on its query parameters without converting them to winnow equivalents
outputCrs - the new option name added in this PR. Added because it is more descriptive (i.e., this is the CRS for the output data, not the input data or the geometry filter)

Option names for the geometryFilter

inSR - Geoservices API query parameter, documented. I assume this was added at some point to allow FeatureServer to pass on its query parameters without converting them to winnow equivalents
the CRS for the geometry filter may also be a property found on the geometry filter if it is an Esri-style envelope

At some point I think we should deprecate everything except inputCrs, outputCrs, and perhaps add a filterCrs. But that will cause breaking changes and would require changes to FeatureServer. I'd like to refactor FeatureServer before starting that kind of work.

haoliangyu commented 3 years ago

@rgwozdz Thanks for explaining the naming. I think it is good for now, but I don't see the mentioned outputCrs in this PR. Is it planned for the next one?

rgwozdz commented 3 years ago

@rgwozdz Thanks for explaining the naming. I think it is good for now, but I don't see the mentioned outputCrs in this PR. Is it planned for the next one?

Yes, thanks for pointing that out. I have a subsequent PR that is currently WIP that includes that.

koopjs / winnow