Skip to content

Fix scale bar handling in orientation/phase maps and show_2d; align cluster pole figure frame - #320

Open
maclariz wants to merge 6 commits into
electronmicroscopy:devfrom
maclariz:fix/orientation-scalebar
Open

maclariz wants to merge 6 commits into
electronmicroscopy:devfrom
maclariz:fix/orientation-scalebar

Conversation

@maclariz

Copy link
Copy Markdown
Contributor

What problem this PR addreseses

Several scale bar and pole-figure problems found while using ACOM orientation and cluster maps:

Scale bars on orientation/phase maps ignored most of ScalebarConfig

  • plot_orientation_map, plot_cluster_map and PhaseMap.plot_phase read only sampling, units, length and color from a scalebar dict; loc, fontsize, box, outline_color, display_units, etc. were silently dropped, and a ScalebarConfig or True raised.
  • Passing any scalebar to these plots (and to CrystalMap.plot_dynamical / plot_correlation) replaced the scan calibration entirely, so {"display_units": "nm"} failed with "Cannot convert scale bar units 'pixels' to 'nm'".
  • Fix: all scan-map plots resolve the bar through _resolve_scalebar, and a new with_scan_calibration() fills sampling/units from the scan unless the user gives them.

Uncalibrated data now warns instead of failing or silently using pixels

  • display_units on an uncalibrated image or scan now warns and draws the bar unconverted, instead of raising. A real-space ↔ reciprocal mismatch still raises.
  • show_2d warns when a scale bar is requested for a plain array without sampling and units (e.g. show_2d(ds.array, scalebar=True)), pointing the user to pass the Dataset2d instead.
  • Warnings are attributed to the caller's line, so they appear at every call site in a notebook, not only once.
  • Dataset3d.show now passes its calibration to show_2d (it sends frames as plain arrays and was losing it).

pad_px was not in pixels; width_px was truncated

  • pad_px was passed to AnchoredSizeBar(pad=...), which matplotlib reads as a multiple of the font size. It is now the gap between the bar (or its box) and the plot edge in image pixels, as ShowParams.Scalebar already documented, and stays correct after resizing or tight_layout. Default changes 0.5 → None, which keeps matplotlib's existing spacing, so plots that never set pad_px are unchanged.
  • width_px was passed through int(), so fractional widths were truncated (widths < 1 drew nothing). Fractions are now kept. Default changes 1 → None so that an explicit width_px=1 on scan maps is no longer replaced by the map-scaled default (1/40 of the map height).

Cluster pole figures were rotated 90° relative to plot_pole_figure

  • plot_pole_figure draws in the scan frame (c rightward, r downward); plot_cluster_pole_figure drew lab x across and lab y upward. It now uses the same frame and the same scan-axes glyph, so the two can be compared or overlaid directly.

Behaviour changes worth noting for users

  • Code that set pad_px explicitly will see different spacing (now image pixels, previously font-size multiples).
  • Existing cluster pole figures will appear rotated 90° when regenerated (to match plot_pole_figure).
  • Default scale bar padding on orientation/phase maps is now matplotlib's standard spacing rather than rows/80 font sizes, which gave very large margins on big scans.

What should the reviewer(s) do

Review and merge. Points that would benefit from a second opinion:

  • The pad_px semantics change (font-size multiples → image pixels), and None defaults for pad_px/width_px in ScalebarConfig and ShowParams.Scalebar.
  • Whether warning (rather than raising) on display_units for uncalibrated data is the preferred behaviour.

Testing: the full tests/core and tests/diffraction suites pass (289 passed) on this branch rebased onto current dev. The new behaviour was checked with standalone scripts (scale bar fields and calibration fill-in, warnings and the line they're reported at, pad_px measured on the rendered figure across image sizes, figure sizes, box on/off and corners, cluster pole positions against plot_pole_figure), but these have not yet been added to the test suite.

  • This PR introduces a public-facing change (e.g., figures, CLI input/output, API).
    • For functional and algorithmic changes, tests are written or updated.
    • Documentation (e.g., tutorials, examples, README) has been updated.
    • A tracking issue or plan to update documentation exists.

🤖 Generated with Claude Code

maclariz and others added 6 commits November 16, 2026 16:29
plot_orientation_map and plot_cluster_map read only sampling, units,
length and color from a scalebar dict, ignored every other field, and
failed on a ScalebarConfig or True. A user dict also replaced the scan
calibration entirely, so the bar fell back to pixels.

Resolve the scalebar through _resolve_scalebar so every ScalebarConfig
field is honoured, and have the OrientationMap wrappers fill only the
missing sampling and units from the scan calibration via
_fill_scalebar_calibration. Bar width and padding left at the
ScalebarConfig defaults still scale with the map size.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01TKw4bfYfoAEq86paxTeAox
A scale bar passed to plot_phase, plot_dynamical or plot_correlation
still replaced the scan calibration outright, so a config such as
{"display_units": "nm"} arrived with units "pixels" and failed with
"Cannot convert scale bar units 'pixels' to 'nm'". PhaseMap.plot_phase
also read only four fields of the config.

Add with_scan_calibration(), which fills sampling and units from the
scan unless the scale bar sets its own, and use it for every scan-map
plot: OrientationMap.plot_orientation and plot_cluster_map,
CrystalMap.plot_dynamical and plot_correlation, and PhaseMap.plot_phase,
which now also draws through _draw_map_scalebar so every ScalebarConfig
field is honoured. On an uncalibrated scan, asking for display_units now
raises an error that says the calibration is missing and how to set it.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01TKw4bfYfoAEq86paxTeAox
Asking for display_units on an uncalibrated image (a plain array, or a
scan never given a step size) raised "Cannot convert scale bar units
'pixels' to 'nm'", and asking show_2d for a scale bar on a plain array
silently drew it in pixels.

- add_scalebar_to_ax: display_units on a bar whose units are not a
  length now warns and draws the bar unconverted; a real-space to
  reciprocal mismatch still raises.
- show_2d: a scale bar requested for a plain array without sampling and
  units warns that it is drawn in pixels and says how to calibrate it.
- with_scan_calibration: on an uncalibrated scan, warns and drops
  display_units instead of raising.
- Dataset3d.show passes its calibration to show_2d, which receives the
  frames as plain arrays and so would otherwise warn and lose it.

Warnings are attributed to the first frame outside quantem, so they
appear at each call site in a notebook instead of only once.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01TKw4bfYfoAEq86paxTeAox
pad_px was passed to AnchoredSizeBar as `pad`, which matplotlib reads as
a multiple of the label font size, so the gap did not follow the image
at all; scan maps that set it to rows/80 got very large margins on big
scans. width_px was also truncated with int(), so 0.5 drew no bar.

pad_px is now the gap between the bar (or its box) and the plot edge in
image pixels, as ShowParams.Scalebar already documented. A small
AnchoredSizeBar subclass converts it to matplotlib's font-size units
each time the bar is placed, so it holds after resizing or
tight_layout. The default becomes None, which keeps matplotlib's
spacing, so plots that never set pad_px look the same; strain and
orientation maps use that default too. width_px is passed as a float.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01TKw4bfYfoAEq86paxTeAox
Scan maps scale an unset bar width to 1/40 of the map height, and told
"unset" from "set" by comparing with the default of 1, so an explicit
width_px=1 was silently replaced. The default is now None: show_2d
draws None as 1 image pixel as before, scan maps scale it, and every
width given, including 1, is used as it is. Documented that fractional
widths are kept.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01TKw4bfYfoAEq86paxTeAox
plot_pole_figure shows poles in the scan (image) frame of the
orientation maps, column axis c rightward and row axis r downward, but
plot_cluster_pole_figure put lab x (r) across and lab y (c) upward. The
swap plus flip left the two figures rotated 90 degrees from each other.

Plot the cluster means and the overlay as (c, r) with the y axis
inverted, and add the same scan-axes glyph, now shared as
_draw_scan_axes_glyph. Checked that a single orientation's cluster
marker lands on plot_pole_figure's density peak and its overlay marker.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01TKw4bfYfoAEq86paxTeAox
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