drawing

Import: ad_hoc_diffractometer.drawing

Provides interactive Plotly figures for diffractometer geometry diagrams:

StageAxisFigure

3D interactive diagram for a single stage rotation axis.

GeometryAxisFigure

Composite diagram showing all stages of a geometry arranged in a directed-graph layout with parent-child relationships.

These are the preferred output for documentation; pre-generate them with tools/generate_geometry_drawings.py and embed the resulting HTML files as <iframe> elements in the Sphinx pages.

Plotly is an optional dependency. Both classes raise ImportError with a helpful message if it is not installed.

Classes

GeometryAxisFigure	Interactive Plotly figure showing all stages of a geometry.
StageAxisFigure	Interactive Plotly figure for a single stage rotation-axis diagram.

Functions

_physical_label(→ str)	Return a human-readable axis label with physical direction if possible.
_require_plotly()	Import and return plotly.graph_objects, or raise ImportError.
_scene_domain(col, row, n_cols, n_rows, title_frac)	Paper-coordinate domain for a scene at grid position (col, row).
_tree_layout(stages)	Compute bottom-to-top tree layout positions for a stage dict.

Module Contents

class ad_hoc_diffractometer.drawing.GeometryAxisFigure(geometry_name: str, axis_labels: bool = True, **kwargs)

Import: ad_hoc_diffractometer.drawing.GeometryAxisFigure

Interactive Plotly figure showing all stages of a geometry.

Stages are arranged as a directed graph following parent relationships. The graph flows bottom-to-top: root stages (parent=None) are at the bottom; each child is one row above its parent. Leaf nodes are assigned integer column slots; parents are centered over their children.

Role is indicated by scene background color:

• sample → aliceblue

• detector → seashell

• other → honeydew

Parent-child relationships are drawn as arrows on the figure.

Parameters:

• geometry_name (str) – Name of a preset geometry (e.g. 'zaxis', 'kappa6c').

• axis_labels (bool) – If True, label the basis vectors on each sub-plot.

• **kwargs – Forwarded to plotly.graph_objects.Figure.

Examples

>>> from ad_hoc_diffractometer.drawing import GeometryAxisFigure
>>> fig = GeometryAxisFigure("fourcv")
>>> fig.write_html("fourcv.html")

property data

Plotly traces (delegated to the internal Figure).

property layout

Plotly layout (delegated to the internal Figure).

show(**kwargs)

Display the figure (delegates to the internal Figure).

write_html(path, **kwargs)

Write the figure to an HTML file.

Parameters:

• path (str or pathlib.Path)

• **kwargs – Forwarded to plotly.graph_objects.Figure.write_html().

write_image(path, **kwargs)

Write the figure to a static image file (SVG, PNG, etc.).

Parameters:

• path (str or pathlib.Path)

• **kwargs – Forwarded to plotly.graph_objects.Figure.write_image().

class ad_hoc_diffractometer.drawing.StageAxisFigure(geometry_name: str, axis_name: str, axis_labels: bool = False, **kwargs)

Import: ad_hoc_diffractometer.drawing.StageAxisFigure

Interactive Plotly figure for a single stage rotation-axis diagram.

Draws the geometry’s basis vectors (grey, semi-transparent) and the stage’s rotation axis (red) with a direction arc, in a 3-D interactive Plotly scene.

Parameters:

• geometry_name (str) – Name of a preset geometry (e.g. 'kappa6c', 'zaxis').

• axis_name (str) – Name of a stage in that geometry (e.g. 'komega', 'Z').

• axis_labels (bool) – If True, label the basis vectors (V, L, T) in the figure.

• **kwargs – Forwarded to plotly.graph_objects.Figure.

Examples

>>> from ad_hoc_diffractometer.drawing import StageAxisFigure
>>> fig = StageAxisFigure("fourcv", "omega")
>>> fig.write_html("omega.html")

R = None

_draw_axis() → None

Draw the axis vector and rotation arc.

_draw_axis_arc(axis_norm: ndarray, direction: int = 1) → None

Draw the rotation arc and arrowhead.

_draw_axis_vector() → ndarray

Draw the rotation axis as a red line; return positive unit vector.

_draw_basis_vectors(axis_labels: bool = False) → None

Draw basis vectors as lines with cone tips.

_set_scene() → None

Configure the 3-D scene camera and axes.

_set_titles() → None

Add title and subtitle to the figure.

add_trace(trace)

Add a trace to the internal figure.

property data

Plotly traces (delegated to the internal Figure).

geometry

property layout

Plotly layout (delegated to the internal Figure).

show(**kwargs)

Display the figure (delegates to the internal Figure).

stage

update_layout(*args, **kwargs)

Update layout on the internal figure.

write_html(path, **kwargs)

Write the figure to an HTML file.

Parameters:

• path (str or pathlib.Path)

• **kwargs – Forwarded to plotly.graph_objects.Figure.write_html().

write_image(path, **kwargs)

Write the figure to a static image file (SVG, PNG, etc.).

Parameters:

• path (str or pathlib.Path)

• **kwargs – Forwarded to plotly.graph_objects.Figure.write_image().

ad_hoc_diffractometer.drawing._physical_label(axis_vec: ndarray, basis: dict | None) → str

Import: ad_hoc_diffractometer.drawing._physical_label

Return a human-readable axis label with physical direction if possible.

For standard signed basis vectors, returns e.g. "-transverse" or "+vertical". For tilted axes (kappa), returns the numeric label.

ad_hoc_diffractometer.drawing._require_plotly()

Import: ad_hoc_diffractometer.drawing._require_plotly

Import and return plotly.graph_objects, or raise ImportError.

ad_hoc_diffractometer.drawing._scene_domain(col, row, n_cols, n_rows, title_frac)

Import: ad_hoc_diffractometer.drawing._scene_domain

Paper-coordinate domain for a scene at grid position (col, row).

row=0 is the bottom (roots); row=n_rows-1 is the top (deepest leaves). title_frac is the fraction of each row height reserved for the title. Returns (x_domain, y_domain) as two [lo, hi] lists.

ad_hoc_diffractometer.drawing._tree_layout(stages)

Import: ad_hoc_diffractometer.drawing._tree_layout

Compute bottom-to-top tree layout positions for a stage dict.

Returns:

• depth (dict stage_name -> int) – 0 for roots (bottom), increasing toward leaves (top).

• x_pos (dict stage_name -> float) – Leaf nodes get integer slots 0, 1, 2, … Parent nodes are centered over their children (may be half-integer).

• children (dict stage_name -> list[str])

• roots (list[str])