refactor(vizx): rebrand the visualization module to VizX#45
Merged
Conversation
Promote the visualization module to a first-class VizX package, consistent with RasterX/GridX/VectorX. Clean rename (beta, no aliases): module databricks.labs.gbx.viz -> .vizx; extra [viz] -> [vizx]; all imports + install snippets across code, docs, tests, CI, notebooks, READMEs, release notes. Docs: viz.mdx -> vizx.mdx with the new VizX logo in the title; sidebar entry "VizX" under GridX; a VizX section after VectorX on the overview. New resources/images/VizX.png (emerald isometric-cube icon matching the package set, generated by vizx-icon.py). Historical superpowers specs/plans left as-is. vizx tests 27 passed; lint clean; Docusaurus build green (no dangling /api/viz). Co-authored-by: Isaac
mjohns-databricks
temporarily deployed
to
runtime
GitHub Actions
Inactive
mjohns-databricks
temporarily deployed
to
runtime
GitHub Actions
Inactive
H1 is the VizX logo + "Function Reference" (the logo carries the name, like the GridX/RasterX pages); frontmatter title -> "VizX Function Reference". Co-authored-by: Isaac
mjohns-databricks
temporarily deployed
to
runtime
GitHub Actions
Inactive
mjohns-databricks
temporarily deployed
to
runtime
GitHub Actions
Inactive
mjohns-databricks
temporarily deployed
to
runtime
GitHub Actions
Inactive
mjohns-databricks
temporarily deployed
to
runtime
GitHub Actions
Inactive
The xView notebook defined its own plot_raster/plot_file inline (raw rasterio.plot.show, no decimation/stretch/nodata masking). Replace them with the tier-agnostic VizX helpers so the preview path matches eo-series and gains decimation, percentile stretch, and nodata masking for free. xView passes dbfs:-qualified Volume paths to plot_file, so normalize a leading dbfs:/file: scheme to the bare FUSE path inside vizx.plot_file (benefits every Databricks caller) rather than stripping at each call site. Update the install to geobrix[light,vizx], the README, and the vizx docs accordingly. Co-authored-by: Isaac
mjohns-databricks
temporarily deployed
to
runtime
GitHub Actions
Inactive
mjohns-databricks
temporarily deployed
to
runtime
GitHub Actions
Inactive
mjohns-databricks
temporarily deployed
to
runtime
GitHub Actions
Inactive
mjohns-databricks
temporarily deployed
to
runtime
GitHub Actions
Inactive
added 14 commits
June 24, 2026 20:07
Design for a tier-agnostic vizx.plot_static that renders Spark/GeoPandas geometries (and DGGS cells) over a contextily basemap as a static, GitHub-renderable figure — the non-interactive counterpart to .explore(). Auto-resolves geometry encodings (WKT/EWKT/WKB/EWKB + native GEOMETRY/GEOGRAPHY) via the shared parse_geom; grid_system param (h3 in v1; quadbin/bng/custom forward-declared as fast-follow); basemap with graceful no-egress fallback. Co-authored-by: Isaac
Adds _static_map.py with _geom_strategy, _detect_geom_col, _collect_limited, and _resolve_gdf (geometry path); reuses gbx._geom.parse_geom for WKT/WKB decoding. _resolve_cells stub deferred to Task 3. All 8 tests green.
The 3857 reproject was gated on basemap=True, so a basemap=False overlay (e.g. a canvas-boundary layer) was drawn in raw 4326 degrees while the base layer was in Web Mercator meters -> the layers landed in different coordinate spaces and did not overlay. Reproject every layer to 3857 regardless; basemap now only toggles whether tiles are fetched. Adds a regression test asserting a basemap=False layer is in meters, not degrees. Co-authored-by: Isaac
Two overlay-ergonomics improvements: - fill=False draws geometries as outlines (facecolor none) so a boundary layer (e.g. a shared-canvas rectangle) doesn't cover the filled layers beneath it. - plot_static no longer calls pyplot.show(); the inline/Databricks backend auto-displays the figure at cell end with all overlaid layers. Calling show() on the figure-creating call flushed the base layer before an ax= overlay was added, so overlays didn't render in real notebooks (masked in tests by the no-op Agg backend). Together these make the documented overlay pattern correct: ax = plot_static(cells_df, grid_system='h3', column='band_level', title=...) plot_static(grid_gdf, ax=ax, fill=False, edgecolor='red', basemap=False) Adds fill true/false and no-show regression tests; docs updated. Notebook cell left to the user (live-edited). Co-authored-by: Isaac
h3-rasterize: adopt vizx.plot_static for the polyfill and shared-canvas overlay map cells (per-cell H3 choropleth over a basemap; fill=False outline for the canvas rectangle), with cluster-executed outputs. xView: refresh cluster-executed outputs (no code change).
The geometry/cell column auto-detection was only exercised through the happy-path end-to-end tests, leaving its error branches unverified. Add direct tests: no geometry column found (grid_system=None) and an ambiguous multi-column cell input (grid_system set) both raise ValueError, and a lone column with grid_system set is selected. Closes the QC test-completeness gap.
mjohns-databricks
temporarily deployed
to
runtime
GitHub Actions
Inactive
mjohns-databricks
temporarily deployed
to
runtime
GitHub Actions
Inactive
mjohns-databricks
temporarily deployed
to
runtime
GitHub Actions
Inactive
mjohns-databricks
temporarily deployed
to
runtime
GitHub Actions
Inactive
mjohns-databricks
added a commit
that referenced
this pull request
Jun 25, 2026
…/0.4.0 → main) (#46) * fix(images): re-render full-height function-categories PNG (un-clip bottom) (#44) The portrait infographic SVG auto-sizes to its content (now 1416x1782), but the PNG was screenshotted at the stale fixed height 1100, clipping the bottom of the right column (Vector-Raster Bridge, H3 Grid, Quadbin Grid, Web-Mercator Tile Output) once rst_h3_rasterize_agg pushed Aggregators to a second row. Re-screenshot at the real height. To stop this recurring, the script now prints the portrait canvas size and the docstring says to use that printed height (it grows as functions are added). Co-authored-by: Isaac Co-authored-by: Michael Johns <user.name> * refactor(vizx): rebrand the visualization module to VizX (#45) * refactor(vizx): rebrand the visualization module viz -> VizX (gbx.vizx) Promote the visualization module to a first-class VizX package, consistent with RasterX/GridX/VectorX. Clean rename (beta, no aliases): module databricks.labs.gbx.viz -> .vizx; extra [viz] -> [vizx]; all imports + install snippets across code, docs, tests, CI, notebooks, READMEs, release notes. Docs: viz.mdx -> vizx.mdx with the new VizX logo in the title; sidebar entry "VizX" under GridX; a VizX section after VectorX on the overview. New resources/images/VizX.png (emerald isometric-cube icon matching the package set, generated by vizx-icon.py). Historical superpowers specs/plans left as-is. vizx tests 27 passed; lint clean; Docusaurus build green (no dangling /api/viz). Co-authored-by: Isaac * docs(vizx): title "Function Reference" (logo only), matching GridX H1 is the VizX logo + "Function Reference" (the logo carries the name, like the GridX/RasterX pages); frontmatter title -> "VizX Function Reference". Co-authored-by: Isaac * refactor(xview): adopt VizX plot helpers; strip dbfs:/file: in plot_file The xView notebook defined its own plot_raster/plot_file inline (raw rasterio.plot.show, no decimation/stretch/nodata masking). Replace them with the tier-agnostic VizX helpers so the preview path matches eo-series and gains decimation, percentile stretch, and nodata masking for free. xView passes dbfs:-qualified Volume paths to plot_file, so normalize a leading dbfs:/file: scheme to the bare FUSE path inside vizx.plot_file (benefits every Databricks caller) rather than stripping at each call site. Update the install to geobrix[light,vizx], the README, and the vizx docs accordingly. Co-authored-by: Isaac * docs(spec): VizX plot_static static-map helper design Design for a tier-agnostic vizx.plot_static that renders Spark/GeoPandas geometries (and DGGS cells) over a contextily basemap as a static, GitHub-renderable figure — the non-interactive counterpart to .explore(). Auto-resolves geometry encodings (WKT/EWKT/WKB/EWKB + native GEOMETRY/GEOGRAPHY) via the shared parse_geom; grid_system param (h3 in v1; quadbin/bng/custom forward-declared as fast-follow); basemap with graceful no-egress fallback. Co-authored-by: Isaac * docs(plan): VizX plot_static implementation plan (6 tasks, TDD) * build(vizx): add contextily dep, hash-pin in CI + dev-container locks * feat(vizx): _static_map geometry-path resolution (parse_geom reuse) Adds _static_map.py with _geom_strategy, _detect_geom_col, _collect_limited, and _resolve_gdf (geometry path); reuses gbx._geom.parse_geom for WKT/WKB decoding. _resolve_cells stub deferred to Task 3. All 8 tests green. * feat(vizx): plot_static h3 cell dispatch; quadbin/bng/custom forward-declared * feat(vizx): plot_static renderer with contextily basemap + fallback * docs(vizx): document plot_static static-map helper * docs(notebooks): adopt vizx.plot_static in h3-rasterize map cell * docs(spec): note quadbin/bng fast-follow via quadbin_aswkb/bng_aswkb * docs(spec): quadbin/bng fast-follow uses driver-side _aswkb (h3-style) * fix(vizx): plot_static reprojects to 3857 always so overlays align The 3857 reproject was gated on basemap=True, so a basemap=False overlay (e.g. a canvas-boundary layer) was drawn in raw 4326 degrees while the base layer was in Web Mercator meters -> the layers landed in different coordinate spaces and did not overlay. Reproject every layer to 3857 regardless; basemap now only toggles whether tiles are fetched. Adds a regression test asserting a basemap=False layer is in meters, not degrees. Co-authored-by: Isaac * feat(vizx): plot_static fill= outline mode + drop internal plt.show() Two overlay-ergonomics improvements: - fill=False draws geometries as outlines (facecolor none) so a boundary layer (e.g. a shared-canvas rectangle) doesn't cover the filled layers beneath it. - plot_static no longer calls pyplot.show(); the inline/Databricks backend auto-displays the figure at cell end with all overlaid layers. Calling show() on the figure-creating call flushed the base layer before an ax= overlay was added, so overlays didn't render in real notebooks (masked in tests by the no-op Agg backend). Together these make the documented overlay pattern correct: ax = plot_static(cells_df, grid_system='h3', column='band_level', title=...) plot_static(grid_gdf, ax=ax, fill=False, edgecolor='red', basemap=False) Adds fill true/false and no-show regression tests; docs updated. Notebook cell left to the user (live-edited). Co-authored-by: Isaac * docs(notebooks): plot_static in h3-rasterize; refresh outputs h3-rasterize: adopt vizx.plot_static for the polyfill and shared-canvas overlay map cells (per-cell H3 choropleth over a basemap; fill=False outline for the canvas rectangle), with cluster-executed outputs. xView: refresh cluster-executed outputs (no code change). * test(vizx): cover _detect_geom_col error and single-column paths The geometry/cell column auto-detection was only exercised through the happy-path end-to-end tests, leaving its error branches unverified. Add direct tests: no geometry column found (grid_system=None) and an ambiguous multi-column cell input (grid_system set) both raise ValueError, and a lone column with grid_system set is selected. Closes the QC test-completeness gap. --------- Co-authored-by: Michael Johns <user.name>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Promotes the visualization module to a first-class VizX package — consistent with the RasterX / GridX / VectorX naming + iconography. Beta + no-aliases, so it's a clean rename (no back-compat shim).
databricks.labs.gbx.viz→databricks.labs.gbx.vizx(git mv, history preserved).geobrix[viz]→geobrix[vizx](deps unchanged → CI hash-lock unaffected).api/viz.mdx→api/vizx.mdxwith the new VizX logo in the H1; sidebar entry "VizX" placed under GridX; a VizX section after VectorX on the API overview (icon + description + reference link). Not added to the home page (it's a tier-agnostic supporting module, not a core spatial-processing package).resources/images/VizX.png— an emerald isometric-cube logo matching the sibling set (colormap on top, bar chart on the left, the shared compass on the right), framed on the identical 7990×4098 canvas. Reproducible viaresources/images/vizx-icon.py.docs/superpowers/specs|plans/*left as-is (they record the work under its then-name).VizX is Python-only (no heavyweight counterpart) — it is "the" place for visualization — so no
gbx_*SQL functions and no binding-parity impact.Testing
test/vizx— 27 passed; Python lint clean.api/vizxbuilds,VizX.pngbundled, no/api/vizdangling links.This pull request and its description were written by Isaac.