1   The Fiona User Manual

Author:Sean Gillies, <sean.gillies@gmail.com>
Revision:1.0
Date:10 January 2012
Copyright:This work is licensed under a Creative Commons Attribution 3.0 United States License.
Abstract:This document explains how to use the Fiona package for reading and writing geospatial data files.

1.1   Introduction

Fiona is a Python wrapper for the OGR vector data access library. A very simple wrapper for minimalists. It reads features from files as GeoJSON-like mappings and writes the same kind of mappings as features back to files. That’s it. There are no layers, no cursors, no geometric operations, no transformations between coordinate systems. Fiona doesn’t just push the complexity of OGR around, it tries to remove as much of it as possible. Simple to understand and use, with no gotchas. Vector data access for humans.

1.1.1   Is it Useful?

Yes. But understand that Fiona is geared to excel in a certain range of tasks and isn’t going to be optimal for others. Fiona trades memory and speed for simplicity and reliability. It copies vector data from the data source to Python objects, where OGR’s Python bindings use C pointers. The Python objects are simpler and safer to use, but more memory intensive. Fiona’s performance is relatively more slow if you only need access to a single feature property – and of course if you just want to reproject or filter data files, nothing beats the ogr2ogr program – but Fiona’s performance is much better than OGR’s Python bindings if you want all feature data (all properties and all coordinates). The copying is a constraint, yes, but it simplifies things. With Fiona, you don’t have to track references to C objects to avoid crashes, and you can work with feature data using familiar Python mapping accessors. Less worry, less time spent reading API documentation.

1.1.2   Guidance

In what cases would you benefit from using Fiona?

  • If the features of interest are from or destined for a file in a non-text format like ESRI Shapefiles, Mapinfo TAB files, etc.
  • If you’re more interested in the values of many feature properties than in a single property’s value.
  • If you’re more interested in all the coordinate values of a feature’s geometry than in a single value.
  • If your processing system is distributed or not contained to a single process.
  • If you don’t need transactional capability.

In what cases would you not benefit from using Fiona?

  • If your data is from or for a GeoJSON document you should use Python’s json or simplejson.
  • If your data is in a RDBMS like PostGIS, use a Python DB package or ORM like SQLAlchemy or GeoAlchemy. You’re probably using GeoDjango in this case already, so carry on.
  • If your data is served via HTTP from CouchDB or CartoDB, etc, use an HTTP package (httplib2, Requests, etc) or the provider’s Python API.
  • If you want to make only small, in situ changes to a shapefile, use osgeo.ogr.

1.1.3   Example

The canonical example for Fiona is this: copying from one shapefile to another, making a trivial transformation of feature geometry.

from fiona import collection

# Open a source of features
with collection("docs/data/test_uk.shp", "r") as source:

    # Define a schema for the feature sink
    schema = source.schema.copy()
    schema['geometry'] = 'Point'

    # Open a new sink for features
    with collection(
            "test_write.shp", "w",
            driver=source.driver,
            schema=schema,
            crs=source.crs
            ) as sink:

        # Process only the features intersecting a box
        for f in source.filter(bbox=(-5.0, 55.0, 0.0, 60.0)):

            # Get point on the boundary of the feature
            f['geometry'] = f['geometry'] = {
                'type': 'Point',
                'coordinates': f['geometry']['coordinates'][0][0] }

            # Stage feature for writing
            sink.write(f)

    # The sink shapefile is written to disk when its ``with`` block ends

1.2   Reading and Writing Data

TODO.

Table Of Contents

Previous topic

README

This Page