Add extract functionality

[michaelkirk]

In a rust project I'm working on, I want to slice out a subset of a pmtiles archive (just like the go pmtiles extract command).

You can see it in action in this video, where I extract an area around the city of Seattle from a planet.pmtiles using the HTTP (range request) backend.

pmtile-extract-seattle.mov.mp4

In the log, the first 8 requests traverse the necessary metadata and directories to figure out where all the tiles live. The next 36 requests fetch the tile data.

It was a large endeavor, and to be honest, when I started, I wasn't sure it was going to work out, but it went relatively well! Unfortunately, this branch is kind of a mess. I'm going to carve out some bite-sized PR's from this branch, more suitable for human consumption, but I wanted to have this as a reference in case anyone wanted the bigger picture.

[michaelkirk]

I guess I should also say: It's obviously fine if you don't want this feature. We didn't discuss it up front or anything, so I won't feel burned. It was an itch I wanted to scratch for myself, but I would definitely rather upstream it, than live in permanent fork territory if it's useful to you.

[codecov]

Codecov Report

❌ Patch coverage is 85.07266% with 113 lines in your changes missing coverage. Please review.
✅ Project coverage is 80.59%. Comparing base (eb788e6) to head (31fd7d2).

Files with missing lines	Patch %	Lines
src/extract/extractor.rs	70.07%	54 Missing and 25 partials ⚠️
src/extract/mod.rs	92.41%	10 Missing and 1 partial ⚠️
src/directory.rs	79.54%	4 Missing and 5 partials ⚠️
src/extract/bbox.rs	82.60%	2 Missing and 6 partials ⚠️
src/extract/ranges.rs	97.88%	2 Missing and 1 partial ⚠️
src/backends/http.rs	95.23%	0 Missing and 1 partial ⚠️
src/tile.rs	98.68%	0 Missing and 1 partial ⚠️
src/writer.rs	80.00%	1 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #106      +/-   ##
==========================================
+ Coverage   77.84%   80.59%   +2.74%     
==========================================
  Files          11       15       +4     
  Lines        1422     2128     +706     
  Branches     1422     2128     +706     
==========================================
+ Hits         1107     1715     +608     
- Misses        210      277      +67     
- Partials      105      136      +31     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[michaelkirk]

@lseelenbinder - is adding the extract functionality to the library (not necessarily the CLI) something you're likely to consider from a feature perspective? Is there some discussion you'd like to have before I continue working on upstreaming my changes?

[lseelenbinder]

@michaelkirk extract is definitely within scope of the library, and assuming it doesn't add a lot of dependencies, I'd say it doesn't even need a feature gate.

[nyurik]

any CLI automatically requires Clap dep

[lseelenbinder]

any CLI automatically requires Clap dep

Agreed. :) I'm just saying the extract functionality is fine to have in the library, not that it's super useful without a CLI.

[michaelkirk]

My own use case for extract is within a mobile application - so not a CLI. But I freely admit it’s weird!