.. _quick_start: Quick Start =========== .. image:: https://dev.azure.com/MPAS-Dev/geometric_features%20testing/_apis/build/status/MPAS-Dev.geometric_features?branchName=main :target: https://dev.azure.com/MPAS-Dev/geometric_features%20testing/_build/latest?definitionId=3&branchName=main :alt: Build Status This repository houses definitions of geometric features. These features can include regions, transects, and points, described in geojson format. For example, here are some regions for Antarctica. .. image:: https://cloud.githubusercontent.com/assets/4179064/12921663/93282b64-cf4e-11e5-9260-a78dfadc4459.png :target: https://cloud.githubusercontent.com/assets/4179064/12921663/93282b64-cf4e-11e5-9260-a78dfadc4459.png :alt: alt text The python ``geometric_features`` package can be used to help maintain and use this repository. Several example scripts that make use of the package can be found in the ``examples`` directory. Each of the classes and functions that make up the package have extensive documentation. More user-level documentation will be added shortly. To use geometric features, you can install it in a conda environment: .. code-block:: bash conda create -n geometric_features -c conda-forge python=3.9 geometric_features conda activate geometric_features To develop ``geometric_features`` (e.g. to add new features), create and activate an environment with all of the required dependencies: .. code-block:: bash conda create -y -n mpas_dev --file dev-spec.txt conda activate mpas_dev python -m pip install -e . A typical workflow will look like: * Create a ``GeometricFeatures`` object and point it to a location where you have stored (or would like to store) geometry data. * ``gf = GeometricFeatures(localCache='./geometric_data')`` * Read in one or more ``FeatureCollection``\ s from the ``geojson`` files in the ``geometric_data`` directory. * ``fcArctic = gf.read('ocean', 'region', featureNames=['Arctic Ocean'])`` * ``fcAtlantic = gf.read('ocean', 'region', tags=['Atlantic_Basin'])`` * Edit features: * Merge, combine, tag, mask out or simplify the features, see below. * Use the ``shapely`` package to edit the geometry in more sophisticated ways * Visualize features: * ``fc.plot(projection='cyl')`` * Split feature collection back into individual features for inclusion in the repo: * ``gf.split(fc)`` Available functionality includes: * ``fc.merge(other)`` - Merge two feature collection together. * ``fc.combine()`` - Combine features into a single feature. * ``fc.difference()`` - Mask features using shapes in a second feature file. * ``fc.fix_antimeridian()`` - Split a feature at the antimeridian (+/- 180 longitude). The resulting feature has all points between -180 and 180 lon. * ``fc.set_group_name()`` - Set the "groupName" property of the ``FeatureCollection`` * ``fc.tag()`` - Add one or more tags to the "tag" property of each feature in a collection. This can be useful for reading back a collection of features with that tag. **IMPORTANT:** Always use the ``gf.split(fc)`` script when placing features into the ``geometric_data`` directory. This will help everyone maintain the repository, and allow tools to parse them cleanly. Many of this functionality can also be accessed with a command-line interface: .. code-block:: bash merge_features combine_features difference_features set_group_name split_features simplify_features tag_features plot_features Use the ``-h`` flag to find out more. An example workflow to read in, plot and write out a set of features is .. code-block:: python #!/usr/bin/env python from geometric_features import GeometricFeatures import matplotlib.pyplot as plt # create a GeometricFeatures object that points to a local cache of geometric # data and knows which branch of geometric_feature to use to download # missing data gf = GeometricFeatures(cacheLocation='./geometric_data') # read in a FeatureCollection containing all ocean regions in the Atlantic # basin fcAtlantic = gf.read(componentName='ocean', objectType='region', tags=['Atlantic_Basin']) fcAtlantic.plot('cyl') plt.title('Atlantic merged') # combine them all into a single feature fcAtlantic = fcAtlantic.combine(featureName='Atlantic_Basin') fcAtlantic.plot('cyl') plt.title('Atlantic combined') # make another feature containing the regions in Filchner-Ronne Ice Shelf fcFilchnerRonne = gf.read(componentName='iceshelves', objectType='region', featureNames=['Filchner_1', 'Filchner_2', 'Filchner_3', 'Ronne_1', 'Ronne_2']) fcFilchnerRonne.plot('southpole') plt.title('Filchner-Ronne') # make one more collection of all the IMBIE basins in West Antarctica fcWestAntarctica = gf.read(componentName='landice', objectType='region', tags=['WestAntarcticaIMBIE']) fcWestAntarctica.plot('southpole') plt.title('West Antarctica') fcWestAntarctica.to_geojson('west_antarctica.geojson') plt.show()