Skip to content

Draw regions and paths on 3-D panels - #81

Merged
CSSFrancis merged 2 commits into
mainfrom
feat/plot3d-patches
Oct 15, 2026
Merged

CSSFrancis merged 2 commits into
mainfrom
feat/plot3d-patches

Conversation

@CSSFrancis

Copy link
Copy Markdown
Owner

Stacked on #80 (needs the model rotation for frame="world" to mean anything); retarget to main once that merges.

Why

To mark the part of a sphere a detector sees, a grain's spread on a pole sphere, or the trace of a lattice plane, a 3-D panel needs regions that sit on the surface: edges that follow the sphere, the far side visibly behind, and a choice between belonging to the object and belonging to the instrument.

What

  • Plot3D.add_patch(points, *, frame="data"|"world", closed=True, geodesic=True, facecolor, edgecolor, alpha, back_alpha, linewidth, label, name) -> Patch3D, plus remove_patch, patches, and Patch3D.set(...) / .remove(). Light pushes only (no geometry resend).
  • geodesic=True (default): Python joins corners by great-circle arcs about the centre of the data bounds in ≤2° steps, interpolating radius. Four corners make a detector's footprint, because a flat detector's straight edges are great circles on the sphere. Opposite points and points at the centre are rejected with a clear message.
  • frame="world" uses the camera alone, so the patch stays put while set_rotation turns the data under it; "data" turns with it.
  • Renderer: each patch is split at the view-space plane through the centre; the back half is drawn at back_alpha, dashed. Where a geodesic patch is cut, the fill follows the silhouette arc rather than a chord across the disc; the outline draws only the patch's own edges. Labels anchor on the patch's surface (front-most point for a full great circle), with a black/white halo picked against the label colour.
  • The Kikuchi sphere example gains the detector footprint (world) and the (111) trace (data).

Tests

tests/test_plot3d/test_patches.py: geodesic edges stay on the sphere at ≤2° steps, straight/open variants, validation, set/remove as light pushes, name replacement; Playwright: a "data" patch moves under set_rotation and a "world" patch does not, and a far-side patch is drawn dimmer. test_plot3d + test_examples: 172 passed.

Plot3D.add_patch draws a filled region (or, with closed=False, a path) over
the geometry. Edges follow great circles about the data centre by default,
which is exactly the shape a flat detector's straight edge makes on a
sphere, so four corners give a detector's footprint. frame="world" keeps a
patch fixed while set_rotation turns the data under it; frame="data" turns
it with the data.

The renderer splits each patch at the plane through the centre facing the
camera and draws the back half dimmer and dashed. Where a geodesic patch is
cut there, the fill follows the sphere's silhouette instead of a chord.
Labels anchor on the patch's surface, with a halo chosen to contrast with
the label colour.

The Kikuchi sphere example now shows both frames: the detector footprint
(world) and the (111) trace (data).
@CSSFrancis
CSSFrancis changed the base branch from feat/plot3d-model-rotation to main October 15, 2026 01:48
@codecov-commenter

Copy link
Copy Markdown

Codecov Report

❌ Patch coverage is 92.85714% with 6 lines in your changes missing coverage. Please review.
✅ Project coverage is 91.24%. Comparing base (ae048a0) to head (d0c8bd4).
⚠️ Report is 1 commits behind head on main.

Files with missing lines Patch % Lines
anyplotlib/plot3d/_plot3d.py 92.59% 6 Missing ⚠️
Additional details and impacted files
@@            Coverage Diff             @@
##             main      #81      +/-   ##
==========================================
+ Coverage   91.22%   91.24%   +0.02%     
==========================================
  Files          41       41              
  Lines        4910     4991      +81     
==========================================
+ Hits         4479     4554      +75     
- Misses        431      437       +6     

☔ View full report in Codecov by Harness.
📢 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.
  • 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

@CSSFrancis
CSSFrancis merged commit 632eb4c into main Oct 15, 2026
10 checks passed
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.

2 participants