Merge pull request #205 from csiro-coasts/geometry-rewrite

Geometry rewrite

Author: mx-moth

continuous-integration/docs.yaml

@@ -3,8 +3,8 @@ channels:
 
 dependencies:
   - geos ~=3.12.2
-  - python =3.12
+  - python =3.14
   - wheel
   - pip:
-    - -r ./requirements-3.12.txt
+    - -r ./requirements-3.14.txt
     - -e ..[docs]

docs/_static/images/animated-plot.mp4

@@ -14,14 +14,11 @@ Arakawa C grid datasets have four :ref:`grids <grids>`:
 *face*, *left*, *back*, and *node*.
 :class:`ArakawaCGridKind` represents this.
 Each grid is :ref:`indexed <indexing>` by a grid kind and two integers *i* and *j*.
-The convention native index type is :data:`ArakawaCIndex`.
 
 .. autoclass:: ArakawaCGridKind
    :members:
    :undoc-members:
 
-.. autodata:: ArakawaCIndex
-
 Topology
 ========
 

docs/_static/images/animated-plot.png

@@ -17,14 +17,11 @@ Indexing
 CF grid datasets have one :ref:`grid <grids>`: *face*.
 :class:`CFGridKind` represents this.
 Each face is :ref:`indexed <indexing>` by two integers *x* and *y*.
-The convention native index type is :data:`CFGridIndex`.
 
 .. autoclass:: CFGridKind
    :members:
    :undoc-members:
 
-.. autodata:: CFGridIndex
-
 Topology
 ========
 

docs/_static/images/plot-set-extent.png

@@ -15,27 +15,33 @@ the :class:`~emsarray.conventions.Convention` interface.
 .. autofunction:: emsarray.open_dataset
 .. autofunction:: emsarray.get_dataset_convention
 
-.. autoclass:: emsarray.conventions.Convention
-   :members:
+Convention
+==========
 
-.. autoclass:: emsarray.conventions.DimensionConvention
+All dataset conventions have the following methods:
 
-   .. autoattribute:: grid_dimensions
-   .. automethod:: unpack_index
-   .. automethod:: pack_index
+.. autoclass:: emsarray.conventions.Convention
+   :members:
 
-.. autoclass:: emsarray.conventions.SpatialIndexItem
+.. autoclass:: emsarray.conventions.Grid
    :members:
 
+Concepts
+========
+
 .. type:: GridKind
 
-    Some type that can enumerate the different :ref:`grid types <grids>`
-    present in a dataset.
-    This can be an :class:`enum.Enum` listing each different kind of grid.
+    All datasets define variables on one or more  :ref:`grid<grids>`.
+    :type:`GridKind` enumerates all the available grids for a specific convention,
+    while :class:`Grid` provides methods for introspecting a particular grid.
+
+    The :type:`GridKind` for a dataset is usually an :class:`enum.Enum` listing each different kind of grid.
+
+    .. rubric:: Notes
 
     :type:`Index` values will be included in the feature properties
     of exported geometry from :mod:`emsarray.operations.geometry`.
-    If the index type includes the grid kind,
+    As the native index for a convention usually includes the grid kind,
     the grid kind needs to be JSON serializable.
     The easiest way to achieve this is to make your GridKind type subclass :class:`str`:
 
@@ -59,6 +65,20 @@ the :class:`~emsarray.conventions.Convention` interface.
     this should be a tuple whos first element is :type:`.GridKind`.
     For conventions with a single grid, :type:`.GridKind` is not required.
 
+Dimension conventions
+=====================
+
+Most dataset conventions have grids that are uniquely identifiable by their dimensions.
+For these conventions the DimensionConvention subclass provides many default implementations.
+These details are most relevant for developers implementing new Convention subclasses.
+
+.. autoclass:: emsarray.conventions.DimensionConvention
+
+   .. autoattribute:: grid_dimensions
+
+.. autoclass:: emsarray.conventions.DimensionGrid
+   :members: dimensions
+
 .. autoclass:: emsarray.conventions.Specificity
    :members:
    :undoc-members:

docs/_static/images/plot-with-clim.png

@@ -13,14 +13,11 @@ Indexing
 UGRID datasets have three :ref:`grids <grids>`: *face*, *edge* and *node*.
 :class:`UGridKind` represents this.
 Each grid is :ref:`indexed <indexing>` by a single integer.
-The convention native index type is :data:`UGridIndex`.
 
 .. autoclass:: UGridKind
    :members:
    :undoc-members:
 
-.. autodata:: UGridIndex
-
 Topology
 ========
 

docs/api/conventions/arakawa-c.rst

@@ -2,7 +2,7 @@
 emsarray.plot
 =============
 
-.. currentmodule:: emsarray.plot
+.. module:: emsarray.plot
 
 Plotting an entire figure
 =========================
@@ -14,6 +14,15 @@ and have limited customisation options.
 Consult the :ref:`examples gallery <examples>`
 for demonstrations on making more customised plots.
 
+The :ref:`examples <examples>` section contains many worked examples on how to generate plots.
+:ref:`example-plot-with-clim` is a good place to start.
+
+Shortcuts
+=========
+
+These functions will generate an entire plot,
+but have limited customisation options.
+
 .. autofunction:: plot_on_figure
 .. autofunction:: animate_on_figure
 
@@ -36,3 +45,36 @@ Utilities
 .. autofunction:: polygons_to_collection
 .. autofunction:: bounds_to_extent
 .. autofunction:: make_plot_title
+
+Artist functions
+================
+
+.. module:: emsarray.plot.artists
+
+These functions will make a matplotlib :class:`~matplotlib.artist.Artist`
+that can plot variables directly from a support emsarray dataset.
+These functions and the associated artists can be imported from
+:mod:`emsarray.plot.artists`.
+
+.. autofunction:: make_polygon_scalar_collection
+.. autofunction:: make_polygon_vector_quiver
+.. autofunction:: make_polygon_contour
+.. autofunction:: make_node_scalar_artist
+
+Artists
+=======
+
+.. autoclass:: GridArtist
+   :members: set_data_array
+
+.. autoclass:: PolygonScalarCollection
+   :members: from_grid
+
+.. autoclass:: PolygonVectorQuiver
+   :members: from_grid
+
+.. autoclass:: PolygonTriContourSet
+   :members: from_grid
+
+.. autoclass:: NodeTriMesh
+   :members: from_grid