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.
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:
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:
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:
GeometricFeaturesobject 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
FeatureCollections from the
geojsonfiles in the
fcArctic = gf.read('ocean', 'region', featureNames=['Arctic Ocean'])
fcAtlantic = gf.read('ocean', 'region', tags=['Atlantic_Basin'])
Merge, combine, tag, mask out or simplify the features, see below.
shapelypackage to edit the geometry in more sophisticated ways
Split feature collection back into individual features for inclusion in the repo:
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
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
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:
merge_features combine_features difference_features set_group_name split_features simplify_features tag_features plot_features
-h flag to find out more.
An example workflow to read in, plot and write out a set of features is
#!/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()