opentrash, one lesson at a time.A hands-on course that walks you through building a real open source Python package for residential waste operations — from an empty repository to a published, documented, installable tool. You watch each lesson, then build that slice of the package yourself.
opentrash is an open source Python package for analyzing residential
solid waste collection operations using GPS telematics, enterprise waste-management
data, and municipal parcel layers. By the end you’ll have built two working
products and published the package.
Given one route and one day, produce a polished interactive HTML map showing the route polygon, the serving vehicle’s GPS trail, landfill tips, parcels served vs missed, and tonnage delivered. Runs in seconds. Embeddable in apps, notebooks, or a batch job writing hundreds of HTMLs to a folder.
Given a long GPS history, detect each parcel’s weekly and biweekly service signature — typical day, hour, vehicle, regularity. Produces a portable parquet file RouteView can optionally consume to compare today’s operation against the yearly pattern.
Where the project heads after the core release. None of these are built in the current run — they’re named so you know the direction of travel.
A third sister product alongside RouteView and Patterns. An interactive HTML map for editing routes — selection tools (click, lasso, polygon), a side panel listing selected parcels and route assignments, and an audit trail of every move. The open source counterpart to enterprise tools like EasyRoute.
A small, redistributable synthetic dataset so anyone can clone the repo and run RouteView and Patterns end-to-end without operational data. Critical for tutorials, onboarding, and reproducibility.
A live, publicly browsable RouteView instance running on the synthetic dataset, deployed via Streamlit or similar. Lets evaluators try it before installing anything.
Experimental: an ESP32 + RFID reader to read container tags, and a low-cost vehicle-mounted LiDAR (Raspberry Pi) to measure alley widths for routing safety. Surfaced from real operational pain points.
Just want to use the package rather than build it? You’ll want the
opentrash package documentation site instead — this course is about
learning to build it from scratch.
Three things get you grounded before Lesson 1. Plan roughly 75 minutes of focused time, spread across the week.
Get a picture of what a residential pickup operation looks like: routes are driven daily by a fleet of collection vehicles, GIS layers describe the territory in three tiers (operational, support, strategic), and vehicles split into automated and manual collection styles. The lessons introduce each of these concepts as you build — a domain-overview video will be linked here soon.
Skim the package documentation at opentrash.app — the Features section describes what RouteView and Patterns produce: parquet-backed pipelines, DuckDB speed, self-contained MapLibre HTML output. A recorded demo on the forthcoming synthetic sample dataset will be linked here. This is what you’ll be building.
Follow the Setup Guide — a step-by-step walkthrough for macOS, Windows, and Linux that gets your machine ready and your repository created. Prefer watching to reading? Dr. Wu’s Geographic Software Design lectures 2 and 3 (in Resources) cover the same ground.
Each lesson is a recorded screencast. You watch it, then build that layer of the package yourself. Lessons unlock as the series progresses. Companion resources are listed per lesson when available — optional supporting material; the lessons are self-contained.
| # | Lesson | Core concepts | Companion | Status |
|---|---|---|---|---|
| 0 | From notebook to package | Repo skeleton; prep/sites; install & CI | PEP 621; src vs flat layouts | Available |
| 1 | Orientation — repo, environment, package anatomy | pyproject.toml, editable installs, the layout map | pip editable installs; PEP 621 optional deps | Available |
| 2 | The foundation — CRS, DuckDB, parcels | core/{crs,duckdb_session}; prep/parcels | EPSG:2230; DuckDB spatial extension | Available |
| 3 | Routes & facilities | prep/static_layers — automated and manual route layers, plus facilities | buffer rules; dissolve-by-attribute | Available |
| 4 | Sites — customer accounts | prep/sites — points layer, spatial join to parcels | GeoPandas sjoin; point-in-polygon | Available |
| 5 | Tonnage — Excel to parquet | tonnage/*; core/vehicle_ids; docs deploy | idempotent upsert; hash-based dedup; MkDocs Material | Available |
| 6 | GPS adapters & cache | adapters/gps/{base,geotab,postgres}; cache/gps_cache | Protocol; env-var config; cache-first reads | Available |
| 7 | The substrate — indexes & WKB | prep/parcels_wkb; cache/{gps_indexes,master_index} | WKB; STAC-like bbox cross-join | Available |
| 8 | Routing engine — enrichment | engine/{enrichment,config} — ping ↔ all GIS layers | One DuckDB CTAS; speed-gated parcel attribution | Available |
| 9 | Segments — load-organized timeline | engine/segments — depot / windshield / collection / dump + violations | haversine; gap-and-island; load-numbering | Available |
| 10 | Pattern detection — route-agnostic chunked DuckDB | patterns/{config,window,detector,runner,validator} | (parcel, vehicle) ranking; composite biweekly; idempotent chunks | Available |
| 11 | RouteView — the interactive map | routeview/{rank,trail,parcel_eval,render,runner} | MapLibre HTML; trail as dots; patterns overlay | Available |
| 12 | Publishing | LICENSE · README · CHANGELOG · CITATION · release.yml | Apache 2.0; PyPI; the repeatable release loop | Available |
opentrash. video link to be added