Skip to content

Move the three study notebooks out of the examples - #219

Merged
bpurinton merged 2 commits into
mainfrom
move-studies-to-workbench
Oct 22, 2026
Merged

bpurinton merged 2 commits into
mainfrom
move-studies-to-workbench

Conversation

@bpurinton

@bpurinton bpurinton commented Oct 22, 2026 •

Copy link
Copy Markdown
Member

This PR removes three notebooks from the examples:

Each answers a research question (which scene combination or which pair gives the best DEM) rather than showing how to use a feature of the package. Every re-execution also added a full new copy of the notebook to the repository's history.

What replaces them for a reader

  • DEMBenchmark: worldview_spacenet_atlanta_mvs.ipynb remains its worked example: run(), the stats table, summary_plot(), histogram_plot(), and the shared-point scoring and track bootstrap, which are on by default. The CLI doc's example figure is made from those same six DEMs.
  • Scene selection: docs/cli/stereo_geom.md covers assessing the geometry of every pair in a multi-scene delivery, with one overview figure plus one figure per pair.
  • How the example pairs were chosen: the UCSD stereo and Atlanta MVS notebooks linked to the scene-selection notebooks in 6 places. Those links are now sentences that carry what the links did. They say how each pair was chosen and how the candidates scored:
    • Atlanta: pair 13-10 at 0.57 m NMAD, against 0.71 and 0.88 m;
    • UCSD: the 21° pair at 1.53 m, against 1.77 and 1.97 m.
  • The benchmark notebook's two links from the Atlanta MVS notebook are removed, with no replacement. The notebooks and docs do not send readers to the issue tracker.

Only markdown cell sources are edited in those two notebooks. Neither is re-executed, so each edit costs about 1 KB of packed history, not a new copy of a 17–28 MB notebook.

Also

  • docs/examples/index.md: three cards and three toctree lines removed.
  • ARCHITECTURE.md: the WorldView bullet describes the examples that remain.
  • AGENTS.md:
    • The read_rpc() entry keeps only the package behaviour: it refuses a raster with a CRS. Its CORE3D conversion advice served only the removed studies, including the gdal_edit.py -unsetgt step, which breaks bundle_adjust with Matrix is singular in inverse().
    • The JP2 entry gains the NAS conda env's $ASP_ROOT/lib/gdalplugins path.
    • The outlier-cut entry drops its pointer to the benchmark notebook.
  • CHANGELOG.md: a "Removed" entry under [Unreleased].

Checks

  • git grep -n "scene_selection\|spacenet_benchmark" -- . ':!CHANGELOG.md' is empty.
  • The edits touch only the 8 intended markdown lines: 6 rewritten, 2 sentences removed. Both notebooks still parse. worldview_spacenet_atlanta_mvs.ipynb passes nbformat.validate. worldview_spacenet_ucsd_stereo.ipynb fails it on main as well (format 4.4 with cell ids), so this change does not cause that.
  • Docs, built from a clean export with the .readthedocs.yaml pre-build steps:
    • There are no "nonexisting document", "unknown document" or toctree warnings.
    • The warning set is main's minus the 32 that came from the removed notebooks.
    • sphinx-build -W fails on main and on this branch alike, from existing autoapi docstring and myst heading warnings.

The library change from #210 is already on main (#215). #210 will be closed once this merges.

The cropped scene-combination benchmark and the two scene-selection
notebooks answer research questions (which scene combination or pair
gives the best DEM) rather than showing how to use a feature, and each
re-execution added a full new copy to the repository's history.

They are removed with their docs cards and toctree entries. The links
to them from the UCSD stereo and Atlanta MVS notebooks become
sentences that state how each pair was chosen and how the candidates
scored, or point at the stereo_geom CLI doc and #169; only markdown
cell sources are edited, and neither notebook is re-executed. The
ARCHITECTURE.md bullet now describes the examples that remain, with
the Atlanta MVS notebook as the worked example of DEMBenchmark.

AGENTS.md: the read_rpc() entry keeps only the package behaviour (it
refuses a raster with a CRS); its CORE3D conversion advice, including
the gdal_edit.py -unsetgt step that breaks bundle_adjust with 'Matrix
is singular in inverse()', served only the studies. The JP2 entry
gains the NAS conda env's gdalplugins path, and the outlier-cut entry
drops its pointer to the benchmark notebook.
Two cells of the Atlanta MVS notebook and the Removed entry sent
readers to issue #169 (and #207) for the benchmark's results. Docs and
example notebooks should not redirect readers to the issue tracker:
issues get closed, and their threads mix results with discussion. The
sentences are dropped; the cells and the entry stand without them.
Markdown only; the notebook is not re-executed.
@bpurinton
bpurinton merged commit 74b176b into main Oct 22, 2026
1 check passed
@bpurinton
bpurinton deleted the move-studies-to-workbench branch October 22, 2026 23:30
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant