search

rgeo / rgeo-geojson

RGeo component for reading and writing GeoJSON
https://rgeo.info
Other
189 stars 40 forks source link

I would like to add a more detailed example / getting started guide #40

Open crawfoal opened 6 years ago

crawfoal commented 6 years ago

I would like to use this gem but am having trouble finding information on how to use it. I've read the README for this and rgeo, and most of the documentation for this gem. I've also started looking through the source code and have some questions.

If you're open to it, I'd like to add a getting started wiki. I can get a PR together but would need a little help. Here are some of my questions:

  1. When I'm creating an EntityFactory or Feature, what type of object do I need to pass in as the geometry object (first argument)? I see that Coder#_encode_geometry checks to see if it is one of many RGeo::Feature objects, but when I looked at RGeo::Feature::Point I realized that it was a module, not an object. Does the geometry object just need to respond to interface laid out in RGeo::Feature::Point? And maybe coordinates too, since Coder#_encode_geometry will call that method?
  2. What is the purpose / use case for EntityFactory? To me, it doesn't seem any easier to use EntityFactory to build a feature than it is to just use the feature class itself (i.e. Feature.new(...)). Is it maybe supposed to serve as a base class for your own customized factories?
  3. Can RGeo::GeoJSON.encode accept both EntityFactory and Feature/FeatureCollection objects?

I can play around with things in a pry console and try to answer some of my own questions, but I thought it would be helpful to document these here and keep them in mind when writing a getting started guide.

It might also be helpful for me to look at the source code of an application that is using this gem. I found a list of projects that are using the gem (I think it was in an issue somewhere), but it was too hard to find the corresponding source code repos (maybe they're private). Do you have a recommendation for a repo to look at?

teeparham commented 6 years ago

That would be great. The tests in the rgeo gem have a lot of examples for creating features, so that's a good place to look. For example: https://github.com/rgeo/rgeo/blob/master/test/simple_mercator/point_test.rb

Basically, use rgeo factories (ex: RGeo::Cartesian.simple_factory, RGeo::Geographic.simple_mercator_factory) to create the features. Then you can pass the feature to RGeo::GeoJSON.encode(feature)

point = RGeo::Cartesian.simple_factory.point(1, 2)
RGeo::GeoJSON.encode(point)

Frankly, I'm not sure what the purpose of EntityFactory is either.

jnicho02 commented 5 years ago

I guess the EntityFactory is what you said....to allow you to define your own Features/FeatureCollections or to decode other formats.

I started off extending Feature, but soon found I wanted to make small changes to how it handles property keys, etc. and wanted to avoid overcomplicated monkey patches.

In my case I have lots of properties that I want to refer to in my code. I redefined Feature to fix property names that come in mixed-case, with spaces, or with colons. I use method_missing to treat anything unknown with no args as a property request so I can write myfeature.prop1 instead of myfeature.properties[:prop1]. My geojson is a returned resultset with a precalculated 'distance' property so I sort my collection into nearest first order and have some other helper methods.

BuonOmo commented 4 years ago

@crawfoal would you still be encline to write documentation ? That is one of our current milestones and you could be of a great help!