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.
Watch “GIS for Solid Waste Management” (GIS Day 2024). You’ll learn what a residential pickup operation looks like, the three-tier GIS data taxonomy (operational, support, strategic), and the auto vs manual vehicle distinction. Short, dense, no fluff.
Watch the RouteView live demo (first ~17 min) of the ASPRS SDSU Chapter presentation on cloud-native geospatial integration. You’ll see the tool running on real data — parquet compression, DuckDB speed, MapLibre HTML output, GitHub Pages deployment. 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 — routes (AUTO + HTC) and facilities | HTC buffer rule; 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.