<commit_before>========
GEOS API
========

.. module:: django.contrib.gis.geos
    :synopsis: GeoDjango's high-level interface to the GEOS library.

Background
==========

What is GEOS?
-------------

`GEOS`__ stands for **Geometry Engine - Open Source**,
and is a C++ library, ported from the  `Java Topology Suite`__.  GEOS
implements the OpenGIS `Simple Features for SQL`__ spatial predicate functions
and spatial operators. GEOS, now an OSGeo project, was initially developed and
maintained by `Refractions Research`__ of Victoria, Canada.

__ https://libgeos.org/
__ https://sourceforge.net/projects/jts-topo-suite/
__ https://www.ogc.org/standards/sfs
__ http://www.refractions.net/

Features
--------

GeoDjango implements a high-level Python wrapper for the GEOS library, its
features include:

* A BSD-licensed interface to the GEOS geometry routines, implemented purely
  in Python using ``ctypes``.
* Loosely-coupled to GeoDjango.  For example, :class:`GEOSGeometry` objects
  may be used outside of a Django project/application.  In other words,
  no need to have :envvar:`DJANGO_SETTINGS_MODULE` set or use a database, etc.
* Mutability: :class:`GEOSGeometry` objects may be modified.
* Cross-platform and tested; compatible with Windows, Linux, Solaris, and
  macOS platforms.

.. _geos-tutorial:

Tutorial
========

This section contains a brief introduction and tutorial to using
:class:`GEOSGeometry` objects.

Creating a Geometry
-------------------

:class:`GEOSGeometry` objects may be created in a few ways.  The first is
to simply instantiate the object on some spatial input -- the following
are examples of creating the same geometry from WKT, HEX, WKB, and GeoJSON::

    >>> from django.contrib.gis.geos import GEOSGeometry
    >>> pnt = GEOSGeometry('POINT(5 23)') # WKT
    >>> pnt = GEOSGeometry('010100000000000000000014400000000000003740') # HEX
    >>> pnt = GEOSGeometry(buffer('\x01\x01\x00\x00\x00\x00\x00\x00\x00\x00\x00\x14@\x00\x00\x00\x00\x00\x007@'))
    >>> pnt = GEOSGeometry('{ "type": "Point", "coordinates": [ 5.000000, 23.000000 ] }') # GeoJSON

Another option is to use the constructor for the specific geometry type
that you wish to create.  For example, a :class:`Point` object may be
created by passing in the X and Y coordinates into its constructor::

    >>> from django.contrib.gis.geos import Point
    >>> pnt = Point(5, 23)

All these constructors take the keyword argument ``srid``. For example::

    >>> from django.contrib.gis.geos import GEOSGeometry, LineString, Point
    >>> print(GEOSGeometry('POINT (0 0)', srid=4326))
    SRID=4326;POINT (0 0)
    >>> print(LineString((0, 0), (1, 1), srid=4326))
    SRID=4326;LINESTRING (0 0, 1 1)
    >>> print(Point(0, 0, srid=32140))<commit_msg>Updated example of creating GEOSGeometry from WKB to use memoryview.<commit_after>========
GEOS API
========

.. module:: django.contrib.gis.geos
    :synopsis: GeoDjango's high-level interface to the GEOS library.

Background
==========

What is GEOS?
-------------

`GEOS`__ stands for **Geometry Engine - Open Source**,
and is a C++ library, ported from the  `Java Topology Suite`__.  GEOS
implements the OpenGIS `Simple Features for SQL`__ spatial predicate functions
and spatial operators. GEOS, now an OSGeo project, was initially developed and
maintained by `Refractions Research`__ of Victoria, Canada.

__ https://libgeos.org/
__ https://sourceforge.net/projects/jts-topo-suite/
__ https://www.ogc.org/standards/sfs
__ http://www.refractions.net/

Features
--------

GeoDjango implements a high-level Python wrapper for the GEOS library, its
features include:

* A BSD-licensed interface to the GEOS geometry routines, implemented purely
  in Python using ``ctypes``.
* Loosely-coupled to GeoDjango.  For example, :class:`GEOSGeometry` objects
  may be used outside of a Django project/application.  In other words,
  no need to have :envvar:`DJANGO_SETTINGS_MODULE` set or use a database, etc.
* Mutability: :class:`GEOSGeometry` objects may be modified.
* Cross-platform and tested; compatible with Windows, Linux, Solaris, and
  macOS platforms.

.. _geos-tutorial:

Tutorial
========

This section contains a brief introduction and tutorial to using
:class:`GEOSGeometry` objects.

Creating a Geometry
-------------------

:class:`GEOSGeometry` objects may be created in a few ways.  The first is
to simply instantiate the object on some spatial input -- the following
are examples of creating the same geometry from WKT, HEX, WKB, and GeoJSON::

    >>> from django.contrib.gis.geos import GEOSGeometry
    >>> pnt = GEOSGeometry('POINT(5 23)') # WKT
    >>> pnt = GEOSGeometry('010100000000000000000014400000000000003740') # HEX
    >>> pnt = GEOSGeometry(memoryview(b'\x01\x01\x00\x00\x00\x00\x00\x00\x00\x00\x00\x14@\x00\x00\x00\x00\x00\x007@')) # WKB
    >>> pnt = GEOSGeometry('{ "type": "Point", "coordinates": [ 5.000000, 23.000000 ] }') # GeoJSON

Another option is to use the constructor for the specific geometry type
that you wish to create.  For example, a :class:`Point` object may be
created by passing in the X and Y coordinates into its constructor::

    >>> from django.contrib.gis.geos import Point
    >>> pnt = Point(5, 23)

All these constructors take the keyword argument ``srid``. For example::

    >>> from django.contrib.gis.geos import GEOSGeometry, LineString, Point
    >>> print(GEOSGeometry('POINT (0 0)', srid=4326))
    SRID=4326;POINT (0 0)
    >>> print(LineString((0, 0), (1, 1), srid=4326))
    SRID=4326;LINESTRING (0 0, 1 1)
    >>> print(Point(0, 0, srid=32140))
{'fraction_non_alphanumeric': 0.13254310344827586, 'fraction_numerical': 0.04849137931034483, 'mean_word_length': 4.039819004524887, 'pattern_counts': {'":': 4, '<': 3, '<?xml version=': 0, '>': 69, 'https://': 6, 'lorem ipsum': 0, 'www.': 4, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 4, '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': '1051240', 'n_tokens_mistral': 1971, 'n_tokens_neox': 1714, 'n_words': 601}