0
# Fiona
1

2
Fiona is a Python library for reading and writing geospatial vector data formats. It provides a minimal, uncomplicated interface to the OGR library, integrating readily with other Python GIS packages like pyproj, Rtree, and Shapely. Fiona streams simple feature data to and from GIS formats like GeoPackage and Shapefile, supporting multi-layered GIS formats, zipped and in-memory virtual file systems, and cloud storage access.
3

4
## Package Information
5

6
- **Package Name**: fiona
7
- **Language**: Python
8
- **Installation**: `pip install fiona`
9

10
## Core Imports
11

12
```python
13
import fiona
14
```
15

16
Common pattern for working with collections:
17

18
```python
19
from fiona import open as fiona_open
20
```
21

22
For specific classes and functions:
23

24
```python
25
from fiona import Feature, Geometry, Properties, bounds, listlayers
26
from fiona.collection import Collection
27
from fiona.crs import CRS
28
from fiona.env import Env
29
```
30

31
## Basic Usage
32

33
```python
34
import fiona
35

36
# Reading a shapefile
37
with fiona.open('data.shp', 'r') as collection:
38
    # Get basic information
39
    print(f"Driver: {collection.driver}")
40
    print(f"CRS: {collection.crs}")
41
    print(f"Schema: {collection.schema}")
42
    print(f"Bounds: {collection.bounds}")
43
    
44
    # Iterate over features
45
    for feature in collection:
46
        print(f"Feature ID: {feature['id']}")
47
        print(f"Geometry: {feature['geometry']['type']}")
48
        print(f"Properties: {feature['properties']}")
49

50
# Writing a new file
51
schema = {
52
    'geometry': 'Point',
53
    'properties': {'name': 'str', 'value': 'float'}
54
}
55

56
with fiona.open('output.geojson', 'w', driver='GeoJSON', 
57
                schema=schema, crs='EPSG:4326') as collection:
58
    # Write a feature
59
    feature = {
60
        'geometry': {'type': 'Point', 'coordinates': [-122.5, 37.5]},
61
        'properties': {'name': 'Test Point', 'value': 42.0}
62
    }
63
    collection.write(feature)
64
```
65

66
## Architecture
67

68
Fiona's design is built around several key components:
69

70
- **Collection**: File-like interface to vector datasets, serving as the main entry point for reading and writing geospatial data
71
- **Feature**: GeoJSON-like objects with geometry, properties, and ID representing individual geographic features
72
- **Geometry/Properties**: Specialized mappings for geometry coordinates and feature attributes
73
- **CRS**: Coordinate reference system handling for geographic projections and transformations
74
- **Environment**: GDAL configuration and credential management for various data sources
75

76
This architecture provides a clean, Pythonic interface to the powerful GDAL/OGR library while maintaining compatibility with the broader Python geospatial ecosystem.
77

78
## Capabilities
79

80
### File I/O Operations
81

82
Core functionality for opening, reading, and writing geospatial vector data files. Supports multiple formats including Shapefile, GeoJSON, GeoPackage, and many others through GDAL/OGR drivers.
83

84
```python { .api }
85
def open(fp, mode="r", driver=None, schema=None, crs=None, **kwargs): ...
86
def listlayers(fp, opener=None, vfs=None, **kwargs): ...
87
def listdir(fp, opener=None): ...
88
def remove(path_or_collection, driver=None, layer=None, opener=None): ...
89
```
90

91
[File I/O Operations](./file-io.md)
92

93
### Data Model Classes
94

95
GeoJSON-like data structures for representing geospatial features, geometries, and properties. These classes provide the foundation for working with geospatial data in a familiar, dictionary-like interface.
96

97
```python { .api }
98
class Feature:
99
    def __init__(self, geometry=None, id=None, properties=None, **data): ...
100
    @classmethod
101
    def from_dict(cls, ob=None, **kwargs): ...
102

103
class Geometry:
104
    def __init__(self, coordinates=None, type=None, geometries=None, **data): ...
105
    @classmethod
106
    def from_dict(cls, ob=None, **kwargs): ...
107

108
class Properties:
109
    def __init__(self, **kwds): ...
110
    @classmethod
111
    def from_dict(cls, mapping=None, **kwargs): ...
112
```
113

114
[Data Model](./data-model.md)
115

116
### Collection Management
117

118
Advanced collection handling including filtering, iteration patterns, schema management, and batch operations for efficient processing of large geospatial datasets.
119

120
```python { .api }
121
class Collection:
122
    def __init__(self, path, mode="r", driver=None, schema=None, crs=None, **kwargs): ...
123
    def filter(self, *args, **kwds): ...
124
    def items(self, *args, **kwds): ...
125
    def keys(self, *args, **kwds): ...
126
    def write(self, record): ...
127
    def writerecords(self, records): ...
128
```
129

130
[Collection Management](./collection-management.md)
131

132
### Coordinate Reference Systems
133

134
Comprehensive CRS handling including creation from various formats (EPSG, WKT, PROJ), conversion between formats, and validation. Essential for proper geospatial data processing and coordinate transformations.
135

136
```python { .api }
137
class CRS:
138
    def __init__(self, initialdata=None, **kwargs): ...
139
    @classmethod
140
    def from_epsg(cls, code): ...
141
    @classmethod
142
    def from_wkt(cls, wkt, morph_from_esri_dialect=False): ...
143
    def to_dict(self, projjson=False): ...
144
    def to_wkt(self, morph_to_esri_dialect=False, version=None): ...
145
```
146

147
[Coordinate Reference Systems](./crs.md)
148

149
### Coordinate Transformations
150

151
Functions for transforming coordinates and geometries between different coordinate reference systems, essential for integrating data from different sources and projections.
152

153
```python { .api }
154
def transform(src_crs, dst_crs, xs, ys): ...
155
def transform_geom(src_crs, dst_crs, geom, **kwargs): ...
156
```
157

158
[Coordinate Transformations](./transforms.md)
159

160
### Environment Management
161

162
GDAL environment configuration, credential management for cloud storage access, and driver management for controlling which data formats are available.
163

164
```python { .api }
165
class Env:
166
    def __init__(self, session=None, aws_unsigned=False, profile_name=None, **kwargs): ...
167
    @classmethod
168
    def from_defaults(cls, *args, **kwargs): ...
169
    def drivers(self): ...
170
```
171

172
[Environment Management](./environment.md)
173

174
### Schema and Field Types
175

176
Schema definition and validation system for specifying the structure of geospatial data, including field types, geometry types, and validation rules.
177

178
```python { .api }
179
def prop_type(text): ...
180
def prop_width(val): ...
181
```
182

183
[Schema and Field Types](./schema.md)
184

185
### Command Line Interface
186

187
Complete command-line interface (fio) for processing geospatial data without writing Python code, including format conversion, data inspection, and spatial analysis operations.
188

189
```bash
190
fio info data.shp
191
fio cat data.shp
192
fio bounds data.shp
193
fio ls archive.zip
194
```
195

196
[Command Line Interface](./cli.md)
197

198
### Utility Functions
199

200
Helper functions for common geospatial operations including bounds calculation, driver information, and version management.
201

202
```python { .api }
203
def bounds(ob): ...
204
```
205

206
[Utility Functions](./utilities.md)
207

208
### Error Handling
209

210
Comprehensive exception hierarchy for handling various error conditions in geospatial data processing, providing specific error types for different failure modes.
211

212
```python { .api }
213
# Base exceptions
214
class FionaError(Exception): ...
215
class FionaValueError(FionaError, ValueError): ...
216

217
# Specific exceptions  
218
class DriverError(FionaError): ...
219
class SchemaError(FionaError): ...
220
class CRSError(FionaValueError): ...
221
class DataIOError(FionaError): ...
222
class TransformError(FionaError): ...
223
class UnsupportedOperation(FionaError): ...
224
```
225

226
## Types
227

228
```python { .api }
229
# Core data types
230
FeatureDict = dict  # GeoJSON-like feature with geometry, properties, id
231
GeometryDict = dict  # GeoJSON-like geometry with type, coordinates
232
PropertiesDict = dict  # Feature properties/attributes
233

234
# Bounds type
235
BoundsTuple = tuple[float, float, float, float]  # (minx, miny, maxx, maxy)
236

237
# Schema types
238
SchemaDict = dict  # Schema definition with geometry and properties
239
DriverDict = dict  # Driver capabilities and metadata
240

241
# CRS types
242
CRSDict = dict  # PROJ4 parameter dictionary
243
WKTString = str  # Well-Known Text representation
244
EPSGCode = int  # EPSG authority code
245
```