Quickstart

This guide walks you through the basic shapelib workflow: read a file, run a few operations on it and save the result.

Read a file

Everything starts with read_file(). Give it a path — to any supported format, local or remote — and it returns the object that matches the content: a Lines, Polygons or Points instance.

from shapelib import read_file

lines = read_file("planting_lines.shp")
fields = read_file("fields.gpkg", layer="fields_2026")

# Straight from the cloud, too
remote = read_file("s3://my-bucket/data/lines.fgb")

See Reading & saving for the full list of supported formats and cloud protocols.

Operate on it

The returned object is a regular geopandas GeoDataFrame — every geopandas method still works — plus the shapelib operations:

# Geodesic length of every line, stored in a "length" column
lines.calculate_length()

# Drop lines shorter than the threshold
lines.filter_by_length(10)

# Total field area (geodesic, in hectares)
fields.calculate_area()
total = fields.get_total_area()

# Buffer the lines into polygons (meters)
polygons = lines.buffer_m(1.5)

Operations that take distances in meters (like buffer_m) reproject internally; for everything else you can hop into a metric CRS with to_utm() or the temp_crs context manager — see Work in meters.

Save the result

save() mirrors read_file: local paths and cloud destinations work the same way, and the format follows the file extension.

lines.save("filtered_lines.shp")
lines.save("s3://my-bucket/outputs/filtered_lines.fgb")

Next steps

• Understand the types in Concepts.

• Explore the line tools and raster converters in Tools.

• Follow a complete recipe in the How-to guides.