Visualization

The public visualization API contains normalized data, prepared view data, Plotly renderers, selection parsing, and typed tables. Preparation and plot functions accept either ResultSet or VisualizationDataset.

See Visualization data for workflows, coordinate conventions, and examples.

Data and selection

class lauelab.visualization.DataScope(patterns='best', min_indexed=3, min_detected=None)

Selection shared by maps, pole figures, and tables.

Parameters:

• patterns (Literal['best', 'all', 'all_frames'] | tuple[int, ...]) – "best" selects the lowest pattern rank in each frame, "all" selects every pattern, "all_frames" additionally retains frames with no patterns in frame-based tables, and a tuple selects explicit pattern ranks. Pattern filters apply only where patterns exist.

• min_indexed (int) – Minimum number of indexed assignments required for a selected pattern.

• min_detected (int | None) – Optional minimum number of detected peaks required for its frame.

pattern_mask(dataset)

Return a mask selecting pattern rows from a dataset.

class lauelab.visualization.ResultSet(results, frame_ids=None, crystal=None, geometry=None)

Ordered indexing results with shared crystal and geometry context.

Parameters:

• results (tuple[lauelab.indexing.indexer.FrameResult, ...]) – Frame results in acquisition or application order.

• frame_ids (tuple[str | int, ...] | None) – Optional unique string or integer identifier for each result. By default, identifiers are zero-based positions in results.

• crystal (lauelab.indexing.crystal.Crystal | None) – Crystal context used for pole figures, orientation colors, and reflection simulation.

• geometry (lauelab.indexing._liblaue.Geometry | None) – Detector geometry used for detector views and back-projection.

classmethod from_indexer(indexer, results, *, frame_ids=None)

Construct a result set using an indexer’s shared context.

to_visualization()

Normalize this collection for visualization and tabular use.

class lauelab.visualization.VisualizationDataset(frame_ids, sample_positions, depths, frame_n_peaks, scan_numbers, energies_kev, detector_ids, image_shapes, starts, groups, input_images, images, peak_frame_indices, peak_indices, peaks, pattern_frame_indices, pattern_indices, pattern_rotations, pattern_reciprocals, pattern_goodness, pattern_rms_error_deg, pattern_n_indexed, assignment_pattern_rows, assignment_peak_indices, assignment_hkl, assignment_error_deg, assignment_energy_kev, assignment_predicted_intensity, crystal=None, geometry=None)

Immutable columnar snapshot of indexing results for visualization.

property n_frames: int

Number of frames in the dataset.

property n_patterns: int

Number of indexed patterns in the dataset.

property n_assignments: int

Number of pattern-to-peak assignments in the dataset.

pattern_ids(scope=None)

Return stable pattern identities selected by a data scope.

lauelab.visualization.load_visualization_xml(path, *, geometry=None, frame_ids=None)

Load a LaueGo AllSteps indexing XML document.

Geometry is optional. An explicit geometry object or path takes precedence; otherwise readable paths embedded in the XML are tried. Failure to resolve embedded geometry does not prevent loading non-detector visualizations.

Prepared views

class lauelab.visualization.Axis(values, label, unit=None, alignment='frame')

Custom map coordinate values and display metadata.

class lauelab.visualization.ScalarColor(values, label=None, palette='Viridis', limits=None, alignment='pattern')

Scalar values and rendering metadata for a spatial map.

class lauelab.visualization.MapData(coordinates, axis_labels, frame_ids, pattern_indices, colors, color_kind, color_label, palette=None, color_limits=None, indexed=None, spatial_axes=True)

Prepared records for a two- or three-dimensional spatial map.

class lauelab.visualization.PoleFigureData(points, frame_ids, pattern_indices, colors, hkl, color_kind, color_radius=None, center=(0.0, 0.0))

Prepared stereographic pole positions and pattern identities.

class lauelab.visualization.DetectorPatternData(pattern_index, hkl, predicted_xy, measured_peak_indices)

Prepared indexed reflections for one pattern.

class lauelab.visualization.DetectorSimulationData(pattern_index, hkl, predicted_xy, energy_kev, relative_intensity)

Prepared missing simulated reflections for one indexed pattern.

Parameters:

• pattern_index (int) – Nonnegative frame-local pattern rank.

• hkl (numpy.ndarray) – Integer Miller indices with shape (n, 3).

• predicted_xy (numpy.ndarray) – Zero-based frame pixel (x, y) coordinates with shape (n, 2). The coordinates include the frame ROI and detector-pixel grouping.

• energy_kev (numpy.ndarray) – Photon energies in keV with shape (n,).

• relative_intensity (numpy.ndarray) – Uncalibrated relative intensities with shape (n,).

Notes

Construction copies, validates, and marks every array read-only. A row at the same index across all arrays describes one simulated reflection.

class lauelab.visualization.DetectorViewData(frame_id, detector_id, extent, measured_xy, measured_peak_indices, measured_intensity, measured_indexed, patterns, image=None, simulations=())

Prepared detector image, peaks, and indexed-reflection overlays.

lauelab.visualization.prepare_map(source, *, axes=('X', 'Y'), color='n_indexed', scope=None, surface=None, misorientation_reference=None, pole_hkl=(1, 0, 0), pole_center=(0.0, 0.0), pole_color_radius_deg=22.5)

Prepare a two- or three-dimensional spatial map.

scope=None uses DataScope(patterns="best", min_indexed=3). This differs from detector-view preparation, whose patterns argument defaults to "all".

lauelab.visualization.prepare_pole_figure(source, *, hkl=(1, 0, 0), scope=None, surface=None, color='hsv_position', pole_center=(0.0, 0.0), pole_color_radius_deg=22.5)

Prepare stereographic pole positions for selected patterns.

scope=None uses DataScope(patterns="best", min_indexed=3). This differs from detector-view preparation, whose patterns argument defaults to "all".

lauelab.visualization.prepare_detector_view(source, *, frame_id, patterns='all', image=None, detector_index=None, simulation_energy_range_kev=None)

Prepare measured, indexed, and optional simulated detector overlays.

patterns="all" includes every indexed pattern in the selected frame. Map and pole-figure preparation instead use the default DataScope, which selects the best pattern with at least three assignments.

Prepared models copy their arrays and mark them read-only. Their frame and pattern identity fields remain aligned with the prepared rows.

Plotly rendering

lauelab.visualization.plot_map(source, *, axes=('X', 'Y'), color='n_indexed', scope=None, surface=None, misorientation_reference=None, pole_hkl=(1, 0, 0), pole_center=(0.0, 0.0), pole_color_radius_deg=22.5, marker_size=10, layout_update=None, trace_update=None)

Render a two- or three-dimensional spatial map with Plotly.

source can be a MapData, ResultSet, or VisualizationDataset. Semantic trace roles are "data" and, for orientation-color maps only, "unindexed"; scalar colors render as a single "data" trace.

lauelab.visualization.plot_pole_figure(source, *, hkl=(1, 0, 0), scope=None, surface=None, color='hsv_position', pole_center=(0.0, 0.0), pole_color_radius_deg=22.5, marker_size=7, hover_point_limit=100000, layout_update=None, trace_update=None)

Render an upper-hemisphere stereographic pole figure with Plotly.

Semantic trace roles are "data", "boundary", and "reference".

lauelab.visualization.plot_detector_view(source, *, frame_id=None, patterns='all', image=None, detector_index=None, simulation_energy_range_kev=None, show_detected=True, show_indexed=True, show_simulated=True, show_hkl_labels=False, marker_size=8, image_colorscale='Gray', image_limits=None, image_opacity=1.0, layout_update=None, trace_update=None)

Render a detector image and reflection overlays with Plotly.

Semantic trace roles are "image", "boundary", "detected", "indexed", and "simulated".

Each renderer accepts a prepared model or normalized input. trace_update changes traces by the roles documented in the visualization guide. layout_update applies after package defaults.

Plotly selection

class lauelab.visualization.PlotlySelection(frame_ids=(), pattern_ids=(), peak_ids=(), reflection_ids=())

Stable identities extracted from a Plotly click or selection event.

lauelab.visualization.selection_from_plotly(event_data)

Extract stable identities from Plotly clickData or selectedData.

The first three customdata values must be frame_id, pattern_index, and peak_index. A missing pattern or peak value is represented by None. Duplicate identities are removed in event order.

Tables

class lauelab.visualization.Table(columns)

Immutable named columns with direct pandas conversion.

to_dataframe()

Return a new pandas DataFrame containing the table columns.

lauelab.visualization.peak_table(source, *, scope=None)

Return one row per detected peak in frames selected by scope.

lauelab.visualization.pattern_table(source, *, scope=None)

Return one row per indexed pattern selected by scope.

lauelab.visualization.assignment_table(source, *, scope=None)

Return one row per selected pattern-to-peak assignment.

lauelab.visualization.indexed_peak_table(source, *, scope=None)

Return assignments joined with their detected peak and pattern values.

Built-in choices

AXIS_OPTIONS, COLOR_MODES, POLE_COLOR_MODES, SURFACE_PRESETS, and PALETTE_OPTIONS are immutable tuples of Choice objects. Their values match the corresponding Laue Portal controls.

class lauelab.visualization.Choice(value, label)

Stable option value and its human-readable label.

lauelab.visualization.AXIS_OPTIONS = (Choice(value='X', label='X motor (um)'), Choice(value='Y', label='Y motor (um)'), Choice(value='Z', label='Z motor (um)'), Choice(value='H', label='H (um)'), Choice(value='F', label='F (um)'), Choice(value='depth', label='Depth (um)'), Choice(value='Xlab', label='X lab (um)'), Choice(value='Ylab', label='Y lab (um)'), Choice(value='Zlab', label='Z lab (um)'), Choice(value='Hlab', label='H lab (um)'), Choice(value='Flab', label='F lab (um)'))

Built-in immutable sequence.

If no argument is given, the constructor returns an empty tuple. If iterable is specified the tuple is initialized from iterable’s items.

If the argument is a tuple, the return value is the same object.

lauelab.visualization.COLOR_MODES = (Choice(value='cubic_ipf', label='Cubic IPF'), Choice(value='rodrigues', label='Rodrigues RGB'), Choice(value='misorientation', label='Misorientation'), Choice(value='pole_hsv', label='Pole Figure HSV'), Choice(value='n_indexed', label='N Indexed'), Choice(value='goodness', label='Goodness'), Choice(value='rms_error', label='RMS Error'), Choice(value='n_patterns', label='N Patterns'))

Built-in immutable sequence.

If no argument is given, the constructor returns an empty tuple. If iterable is specified the tuple is initialized from iterable’s items.

If the argument is a tuple, the return value is the same object.

lauelab.visualization.POLE_COLOR_MODES = (Choice(value='hsv_position', label='Position HSV'), Choice(value='ipf', label='Cubic IPF'), Choice(value='uniform', label='Uniform'))

Built-in immutable sequence.

If no argument is given, the constructor returns an empty tuple. If iterable is specified the tuple is initialized from iterable’s items.

If the argument is a tuple, the return value is the same object.

lauelab.visualization.SURFACE_PRESETS = (Choice(value='normal', label='APS 34-ID-E sample normal'), Choice(value='X', label='APS 34-ID-E X'), Choice(value='H', label='APS 34-ID-E H'), Choice(value='Y', label='APS 34-ID-E Y'), Choice(value='Z', label='APS 34-ID-E Z'), Choice(value='F', label='APS 34-ID-E F'))

Built-in immutable sequence.

If no argument is given, the constructor returns an empty tuple. If iterable is specified the tuple is initialized from iterable’s items.

If the argument is a tuple, the return value is the same object.

lauelab.visualization.PALETTE_OPTIONS = (Choice(value='Viridis', label='Viridis'), Choice(value='Plasma', label='Plasma'), Choice(value='Inferno', label='Inferno'), Choice(value='Magma', label='Magma'), Choice(value='Jet', label='Jet'), Choice(value='Rainbow', label='Rainbow'), Choice(value='Earth', label='Terrain'))

Built-in immutable sequence.

If no argument is given, the constructor returns an empty tuple. If iterable is specified the tuple is initialized from iterable’s items.

If the argument is a tuple, the return value is the same object.

Surface frames

class lauelab.analysis.SurfaceFrame(tilt, roll, normal, name=None)

Right-handed orthonormal sample-surface coordinate frame.

classmethod from_vectors(*, tilt, roll, normal, name=None)

Construct and normalize a frame from three vectors.

classmethod aps_34ide(name='normal')

Return a named APS 34-ID-E surface frame.