<commit_before>
== Zoocasa GEOS Extensions

The Zoocasa GEOS Extensions library (ZGEL) is a set of utilities and tools that
extend the GEOS Ruby bindings module. From http://geos.refractions.net/ ...

  GEOS (Geometry Engine - Open Source) is a C++ port of the  Java Topology
  Suite (JTS). As such, it aims to contain the complete functionality of JTS
  in C++. This includes all the OpenGIS Simple Features for SQL spatial
  predicate functions and spatial operators, as well as specific JTS
  enhanced topology functions.

The GEOS bindings for Ruby can be installed by installing the GEOS library
itself using the --enable-ruby switch during configure or can often be
installed via package managers. There is also an FFI-based Ruby gem being
written available at https://github.com/dark-panda/ffi-geos .

ZGEL contains a number of enhancements to the GEOS Ruby library:

* a host of helper methods to make reading and writing to and from WKT
  and WKB easier. For instance, rather than

    Geos::WktReader.new.read('POINT(0 0')

  you can quickly use

    Geos.read('POINT(0 0)')

  The Geos.read method also works with WKB in both binary and hex,
  recognizes EWKB and EWKT and can read several of Google Maps
  JavaScript output formats that we use for our applications. There are
  also similar methods for outputting to WKT and WKB such as
  Geos::Geometry#to_wkt, #to_kml, #to_georss and a number of methods to
  output to Google Maps API v2-style JavaScript.

* a bunch of helper methods to quickly grab some information from
  geometries like Geos::Point#lat and Geos::Point#lng.

* in all, some 70+ helper methods have been added to Geos::Geometry types.

* Geos::GeometryCollection has been made an Enumerable.

We've also included some Rails integration for PostGIS, including:

* automatic detection of geometry columns and just-in-time conversions
  for input and output to and from WKB when using PostGIS. This allows
  you to do stuff like this with your ActiveRecord models:

    m = MyModel.find(12345)
    m.the_geom # => spits out the untouched geometry value as a string in WKB
    m.the_geom_geos # => spits out the geometry wrapped in a Geos::Geometry object
    m.the_geom = 'POINT(0 0)' # => setters will automatically make
    conversions from any of the formats that the Geos.read can recognize,
    so Google Maps formats, WKT, WKB, etc. are all converted
    automatically.
    m.the_geom_wkt # => automatically converts to a WKT string
    m.the_geom_wkb_bin # => automatically converts to WKB in binary

  There's also some funky SRID handling code that will automatically
  look in the geometry_columns table to make conversions for you when
  necessary. Saving WKT as "SRID=default; POINT(0 0)" for instance will
  automatically set the SRID when saving the ActiveRecord, or the SRID
  can be specified manually.

* multiple geometry columns are supported and detected for
  automatically. These column accessors are all generated dynamically at
  run time.

* automatic generation of named scopes for ActiveRecord models. The
  usual suspects are supported:

  * st_contains
  * st_containsproperly
  * st_covers
  * st_coveredby
  * st_crosses
  * st_disjoint
  * st_equals
  * st_intersects
  * st_orderingequals
  * st_overlaps
  * st_touches
  * st_within
  * st_dwithin

  These let you chain together scopes to build geospatial queries:

    neighbourhood = Neighbourhood.find(12345)
    my_model = MyModel.active.
      recent.
      st_within(neighbourhood.the_geom_geos.envelope).
      st_dwithin(point, 0.1).
      all(
        :limit => 10
      )

=== Running ActiveRecord Tests

ActiveRecord unit tests can be run by setting the TEST_ACTIVERECORD
environment variable when running `rake test`. The test database name
is geos_extensions_unit_tests and requires PostGIS to be installed. The
test scripts will try to find your postgis.sql and spatial_ref_sys.sql
files, but if it needs a hint, set the POSTGIS_PATH environment variable
to the directory the files are in to create the database properly. You
can also set the database up manually before running the tests -- just
make sure the database has PostGIS installed with the spatial_ref_sys
table populated and you'll be fine.
<commit_msg>Add some documentation on ordering scopes.<commit_after>
== Zoocasa GEOS Extensions

The Zoocasa GEOS Extensions library (ZGEL) is a set of utilities and tools that
extend the GEOS Ruby bindings module. From http://geos.refractions.net/ ...

  GEOS (Geometry Engine - Open Source) is a C++ port of the  Java Topology
  Suite (JTS). As such, it aims to contain the complete functionality of JTS
  in C++. This includes all the OpenGIS Simple Features for SQL spatial
  predicate functions and spatial operators, as well as specific JTS
  enhanced topology functions.

The GEOS bindings for Ruby can be installed by installing the GEOS library
itself using the --enable-ruby switch during configure or can often be
installed via package managers. There is also an FFI-based Ruby gem being
written available at https://github.com/dark-panda/ffi-geos .

ZGEL contains a number of enhancements to the GEOS Ruby library:

* a host of helper methods to make reading and writing to and from WKT
  and WKB easier. For instance, rather than

    Geos::WktReader.new.read('POINT(0 0')

  you can quickly use

    Geos.read('POINT(0 0)')

  The Geos.read method also works with WKB in both binary and hex,
  recognizes EWKB and EWKT and can read several of Google Maps
  JavaScript output formats that we use for our applications. There are
  also similar methods for outputting to WKT and WKB such as
  Geos::Geometry#to_wkt, #to_kml, #to_georss and a number of methods to
  output to Google Maps API v2-style JavaScript.

* a bunch of helper methods to quickly grab some information from
  geometries like Geos::Point#lat and Geos::Point#lng.

* in all, some 70+ helper methods have been added to Geos::Geometry types.

* Geos::GeometryCollection has been made an Enumerable.

We've also included some Rails integration for PostGIS, including:

* automatic detection of geometry columns and just-in-time conversions
  for input and output to and from WKB when using PostGIS. This allows
  you to do stuff like this with your ActiveRecord models:

    m = MyModel.find(12345)
    m.the_geom # => spits out the untouched geometry value as a string in WKB
    m.the_geom_geos # => spits out the geometry wrapped in a Geos::Geometry object
    m.the_geom = 'POINT(0 0)' # => setters will automatically make
    conversions from any of the formats that the Geos.read can recognize,
    so Google Maps formats, WKT, WKB, etc. are all converted
    automatically.
    m.the_geom_wkt # => automatically converts to a WKT string
    m.the_geom_wkb_bin # => automatically converts to WKB in binary

  There's also some funky SRID handling code that will automatically
  look in the geometry_columns table to make conversions for you when
  necessary. Saving WKT as "SRID=default; POINT(0 0)" for instance will
  automatically set the SRID when saving the ActiveRecord, or the SRID
  can be specified manually.

* multiple geometry columns are supported and detected for
  automatically. These column accessors are all generated dynamically at
  run time.

* automatic generation of named scopes for ActiveRecord models. The
  usual suspects are supported:

  * st_contains
  * st_containsproperly
  * st_covers
  * st_coveredby
  * st_crosses
  * st_disjoint
  * st_equals
  * st_intersects
  * st_orderingequals
  * st_overlaps
  * st_touches
  * st_within
  * st_dwithin

  Ordering scopes are also included:

  * order_by_ndims
  * order_by_npoints
  * order_by_nrings
  * order_by_numgeometries
  * order_by_numinteriorring
  * order_by_numinteriorrings
  * order_by_numpoints
  * order_by_length3d
  * order_by_length
  * order_by_length2d
  * order_by_perimeter
  * order_by_perimeter2d
  * order_by_perimeter3d
  * order_by_distance
  * order_by_distance_sphere
  * order_by_maxdistance
  * order_by_hausdorffdistance
  * order_by_distance_spheroid
  * order_by_length2d_spheroid
  * order_by_length3d_spheroid
  * order_by_length_spheroid

  These let you chain together scopes to build geospatial queries:

    neighbourhood = Neighbourhood.find(12345)
    my_model = MyModel.active.
      recent.
      st_within(neighbourhood.the_geom_geos.envelope).
      st_dwithin(point, 0.1).
      all(
        :limit => 10
      )

=== Running ActiveRecord Tests

ActiveRecord unit tests can be run by setting the TEST_ACTIVERECORD
environment variable when running `rake test`. The test database name
is geos_extensions_unit_tests and requires PostGIS to be installed. The
test scripts will try to find your postgis.sql and spatial_ref_sys.sql
files, but if it needs a hint, set the POSTGIS_PATH environment variable
to the directory the files are in to create the database properly. You
can also set the database up manually before running the tests -- just
make sure the database has PostGIS installed with the spatial_ref_sys
table populated and you'll be fine.
{'fraction_non_alphanumeric': 0.048734873487348736, 'fraction_numerical': 0.006160616061606161, 'mean_word_length': 3.9488296135002723, 'pattern_counts': {'":': 0, '<': 3, '<?xml version=': 0, '>': 15, 'https://': 2, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '5026880', 'n_tokens_mistral': 2758, 'n_tokens_neox': 2578, 'n_words': 1163}