Visualization

The visualization API provides maps, pole figures, detector views, and tables, along with Plotly selection handling. Pass a ResultSet or VisualizationDataset to preparation and plotting functions.

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

Data and selection

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

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.

• unindexed_frames (bool) – Also select frames left with no selected pattern, as frame-only records: maps place them as gray points and frame-based tables keep their peaks. patterns="all_frames" implies this. These records retain their frame IDs and have no associated pattern ID.

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, sources=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_results(path, *, geometry=None, frame_ids=None)

Eagerly load a lauelab indexing-results HDF5 file.

lauelab.visualization.convert_xml(xml_path, output_path=None, *, geometry=None, overwrite=False)

Convert a LaueGo AllSteps XML document to a results HDF5 file.

Parameters:

• xml_path – The AllSteps document.

• output_path – Destination results file. Defaults to xml_path with the .h5 suffix.

• geometry – Geometry to record instead of the one named in the XML.

• overwrite – Replace an existing destination. The default refuses.

Returns:

pathlib.Path – The published destination.

Raises:

• FileNotFoundError – If the XML document does not exist.

• xml.etree.ElementTree.ParseError – If the document is not well-formed XML.

• ValueError – If steps record conflicting run parameters, or the document’s content cannot be normalized.

• FileExistsError – If the destination exists and overwrite is False, checked before conversion and again at publication.

• InvalidResultsFile – If the written file fails validate_results_file().

Return type:

pathlib.Path

Notes

The results file is written under a unique <name>.partial-* file in the destination’s directory, closed, validated, and only then renamed to output_path. A failure removes the partial file and preserves any existing destination. If two conversions target the same path, the second to finish raises FileExistsError unless overwrite is set. Documents with missing geometry or crystal context can be converted; validate_results_file reports which context is present.

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, symmetry=None)

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

Parameters:

• coordinates (numpy.ndarray) – Record positions with shape (n, 2) or (n, 3).

• axis_labels (tuple[str, ...]) – One label per coordinate column.

• frame_ids (tuple[str | int, ...]) – Frame identity of each record.

• pattern_indices (numpy.ndarray) – Frame-local pattern rank of each record, or NO_PATTERN for a frame-only record produced by a scope with unindexed_frames. Such a record has a real frame identity and no pattern identity.

• colors (numpy.ndarray) – Scalar values with shape (n,) or RGB rows with shape (n, 3). A frame-only record has NaN for pattern-based colors; renderers draw it gray and exclude it from scalar color ranges.

• color_kind (Literal['scalar', 'rgb']) – Color metadata for renderers.

• color_label (str) – Color metadata for renderers.

• palette (str | None) – Color metadata for renderers.

• color_limits (tuple[float, float] | None) – Color metadata for renderers.

• indexed (numpy.ndarray | None) – True where the record is a pattern with a finite orientation. It is False both for frame-only records and for patterns whose orientation could not be derived; has_pattern tells the two apart.

• spatial_axes (bool) – Whether every axis is a built-in spatial axis, so renderers may lock the aspect ratio.

• symmetry (str | None) – Symmetry reduction applied to orientation colors: "cubic", "hexagonal", or "none"; None for colors that use none.

property has_pattern: numpy.ndarray

True where a record is a pattern rather than a frame-only record.

lauelab.visualization.NO_PATTERN = -1

int([x]) -> integer int(x, base=10) -> integer

Convert a number or string to an integer, or return 0 if no arguments are given. If x is a number, return x.__int__(). For floating-point numbers, this truncates towards zero.

If x is not a number or if base is given, then x must be a string, bytes, or bytearray instance representing an integer literal in the given base. The literal can be preceded by ‘+’ or ‘-’ and be surrounded by whitespace. The base defaults to 10. Valid bases are 0 and 2-36. Base 0 means to interpret the base from the string as an integer literal. >>> int(‘0b100’, base=0) 4

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, orientation_symmetry='auto', rodrigues_reference=None, rodrigues_reference_reciprocal=None)

Prepare a two- or three-dimensional spatial map.

Parameters:

• source – A ResultSet or VisualizationDataset.

• axes – Two or three built-in axis names or Axis objects.

• color – A named scalar, a ScalarColor, an aligned array, or one of the orientation colors "cubic_ipf", "rodrigues", "misorientation", and "pole_hsv".

• scope – Pattern selection. None uses DataScope(patterns="best", min_indexed=3), which differs from detector-view preparation, whose patterns argument defaults to "all". A scope with unindexed_frames (or patterns="all_frames") appends one frame-only record for every frame left without a selected pattern, after the pattern records. Its pattern_indices entry is NO_PATTERN, its indexed flag is False, pattern-based colors are NaN, and frame-based values (built-in axes, "n_patterns", frame-aligned custom values) are real. A pattern-aligned Axis cannot place such a record and raises.

• surface – Sample surface frame for IPF and pole coloring.

• misorientation_reference – (frame_id, pattern_index) of the reference pattern for "misorientation" coloring. The pattern must exist and have a finite orientation.

• pole_hkl – Pole HSV coloring settings.

• pole_center – Pole HSV coloring settings.

• pole_color_radius_deg – Pole HSV coloring settings.

• orientation_symmetry (Literal['auto', 'cubic', 'hexagonal', 'none']) – Symmetry reduction for "rodrigues" and "misorientation" colors. "auto" uses the crystal’s proper rotations when its system is cubic or hexagonal and otherwise applies no reduction; the applied setting is reported in MapData.symmetry. "cubic" and "hexagonal" force those operations; "none" applies no reduction.

• rodrigues_reference – (frame_id, pattern_index) of an existing pattern whose orientation is the reference for "rodrigues" colors, so that pattern maps to the zero vector. Without a reference the laboratory frame is the reference.

• rodrigues_reference_reciprocal – A (3, 3) reciprocal lattice, rows a*, b*, c* in 1/nm including the factor of two pi, whose orientation relative to the crystal’s native reference basis is the reference for "rodrigues" colors. It must be finite and nonsingular and describe a proper rotation of the crystal lattice. This requires crystal context and cannot be combined with rodrigues_reference.

Returns:

MapData – Pattern records in scope order followed by any frame-only records.

Raises:

ValueError – For unknown axes or colors, non-finite coordinates, missing crystal context, an invalid or unknown reference, an unknown symmetry choice, or mutually exclusive references.

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, orientation_symmetry='auto', rodrigues_reference=None, rodrigues_reference_reciprocal=None, 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 "unindexed". The "unindexed" trace draws, in gray, patterns without a finite orientation and frame-only records (frames with no selected pattern, see DataScope); for scalar colors it holds the records whose value is NaN, so they never enter the color range. A frame-only record’s customdata pattern identity is None, which selection_from_plotly() reports as a frame selection with no pattern.

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, or by NaN when the trace stored its identities as a numeric array. Integral floating-point identities from such an array are accepted as integers. 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.

Depth inspection

These builders render the prepared data of lauelab.reconstruct.inspection; see Inspect a reconstructed point. Trace roles are "image" and "roi" for the reference image, "trace" and "selected" for one depth trace, and "roi" for ROI traces.

class lauelab.visualization.RoiOverlay(name, bounds, color)

A named, coloured square to draw on a reference image.

name

Caller-chosen identity, shown in hover text and the legend.

Type:

str

bounds

Half-open (y0, y1, x0, x1) in stored-image pixels, as square_bounds() returns.

Type:

tuple of int

color

Any Plotly colour string. The caller keeps colours consistent between the overlay and the ROI’s trace.

Type:

str

lauelab.visualization.plot_reference_image(reference, rois=(), *, colorscale='Gray', limits=None, layout_update=None, trace_update=None)

Render a reference image with square ROI overlays.

The image is drawn in stored-image pixel coordinates with the origin at the upper left, x increasing to the right, y increasing downward, and equal pixel scales. Each square is drawn on its pixel edges, so a 1-pixel ROI encloses exactly one pixel. Semantic trace roles are "image" and "roi".

Parameters:

• reference (ReferenceImage) – A ReferenceImage.

• rois (Sequence[RoiOverlay]) – Squares to draw, in order. Every square must lie inside the image.

• colorscale (str) – Plotly colour scale for the image.

• limits (tuple of float or None) – (zmin, zmax) of the colour scale; the default spans the data.

• layout_update (Mapping | None) – Plotly layout update, and per-role trace updates keyed by role.

• trace_update (Mapping | None) – Plotly layout update, and per-role trace updates keyed by role.

lauelab.visualization.plot_depth_trace(trace, *, axis='depth', log=False, selected_index=None, color='rgb(40,40,40)', layout_update=None, trace_update=None)

Render one intensity trace through depth.

Semantic trace roles are "trace" and "selected".

Parameters:

• trace (DepthTrace) – A DepthTrace.

• axis (str) – "depth" for physical depth in µm or "index" for the zero-based depth index; see DEPTH_AXIS_OPTIONS.

• log (bool) – Logarithmic intensity axis. Samples that are zero or negative are omitted, leaving gaps in the plotted line. An annotation reports the number of omitted samples.

• selected_index (int or None) – Depth index to mark with a vertical line, for a depth browser.

• color (str) – Line colour.

lauelab.visualization.plot_roi_traces(traces, *, colors=None, axis='depth', normalized=False, log=False, layout_update=None, trace_update=None)

Render one trace per ROI through depth.

Semantic trace role is "roi". Every trace’s meta["name"] carries its ROI name and its uid is derived from that name. Selection and colour therefore remain associated with the ROI when traces are reordered. Any non-empty name is allowed, including spaces and punctuation.

Parameters:

• traces (Mapping[str, DepthTrace]) – ROI name to trace, in display order, as roi_traces() returns. An empty mapping renders an annotated empty figure.

• colors (Mapping[str, str] | None) – ROI name to colour. Unnamed ROIs cycle through DEFAULT_ROI_COLORS.

• axis (str) – "depth" or "index".

• normalized (bool) – Divide each trace by its own positive maximum. A trace whose maximum is not positive is left out, and an annotation says why.

• log (bool) – Logarithmic intensity axis; nonpositive samples are omitted and counted in an annotation.

lauelab.visualization.DEFAULT_ROI_COLORS = ('rgb(230,90,60)', 'rgb(60,140,230)', 'rgb(60,180,90)', 'rgb(220,160,40)', 'rgb(150,90,210)', 'rgb(40,180,190)', 'rgb(200,70,150)', 'rgb(120,120,120)')

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.

Built-in choices

AXIS_OPTIONS, COLOR_MODES, POLE_COLOR_MODES, SURFACE_PRESETS, PALETTE_OPTIONS, DEPTH_AXIS_OPTIONS, INTENSITY_OPTIONS, and REFERENCE_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.

lauelab.visualization.DEPTH_AXIS_OPTIONS = (Choice(value='depth', label='Depth (um)'), Choice(value='index', label='Depth index'))

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.INTENSITY_OPTIONS = (Choice(value='sum', label='Sum'), Choice(value='normalized', label='Normalized to maximum'))

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.REFERENCE_OPTIONS = (Choice(value='sum_reconstructed', label='Sum of reconstructed frames'), Choice(value='first_raw', label='First raw frame'), Choice(value='sum_raw', label='Sum of raw frames'))

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.