unit-cell-gui 0.1.0__py3-none-any.whl

unit_cell_gui/__init__.py

@@ -0,0 +1,39 @@
+"""A Qt widget that renders complete, caller-supplied unit-cell scenes."""
+
+from .hatching import (
+    face_hatch_segments,
+    hatch_division_count,
+    occupancy_fractions,
+    propagated_hatch_directions,
+    quadrilateral_hatch_line_count,
+)
+from .models import Atom, AtomComponent, DisplayOptions, Polyhedron, Scene, StyleOverrides
+__version__ = "0.1.0"
+
+
+def __getattr__(name):
+    if name in {"CrystalCanvas", "UnitCellViewer", "screen_drag_orientation"}:
+        from .viewer import CrystalCanvas, UnitCellViewer, screen_drag_orientation
+        return {
+            "CrystalCanvas": CrystalCanvas,
+            "UnitCellViewer": UnitCellViewer,
+            "screen_drag_orientation": screen_drag_orientation,
+        }[name]
+    raise AttributeError(name)
+
+__all__ = [
+    "Atom",
+    "AtomComponent",
+    "CrystalCanvas",
+    "DisplayOptions",
+    "Polyhedron",
+    "Scene",
+    "StyleOverrides",
+    "UnitCellViewer",
+    "face_hatch_segments",
+    "hatch_division_count",
+    "occupancy_fractions",
+    "propagated_hatch_directions",
+    "quadrilateral_hatch_line_count",
+    "screen_drag_orientation",
+]

unit_cell_gui/hatching.py

@@ -0,0 +1,229 @@
+"""View-dependent hatching used by the unit-cell renderer."""
+
+from __future__ import annotations
+
+import itertools
+from typing import Iterable
+
+import numpy as np
+
+
+def occupancy_fractions(components: Iterable[object]) -> tuple[float, ...]:
+    """Return drawable site fractions while preserving partial occupancy."""
+    occupancies = tuple(max(0.0, float(component.occupancy)) for component in components)
+    total = sum(occupancies)
+    scale = 1.0 if total <= 1.0 else 1.0 / total
+    return tuple(occupancy * scale for occupancy in occupancies)
+
+
+def quadrilateral_hatch_line_count(triangle_count: int) -> int:
+    """Return the number of full, parallel strokes on a quadrilateral."""
+    return 2 * max(0, int(triangle_count)) + 1
+
+
+def _hatch_face_normal(points: np.ndarray) -> np.ndarray:
+    normal = np.cross(points[1] - points[0], points[2] - points[0])
+    return normal / np.linalg.norm(normal)
+
+
+def _initial_hatch_direction(face: tuple[int, ...], vertices: np.ndarray) -> np.ndarray:
+    apex = max(face, key=lambda vertex: float(vertices[vertex, 2]))
+    if len(face) == 4:
+        # Virtual triangles choose a diagonal direction only. They never
+        # become visible boundaries or separately rendered subfaces.
+        position = face.index(apex)
+        first, second = face[(position - 1) % 4], face[(position + 1) % 4]
+    else:
+        candidates = [
+            (first, face[(position + 1) % len(face)])
+            for position, first in enumerate(face)
+            if apex not in (first, face[(position + 1) % len(face)])
+        ]
+        first, second = max(
+            candidates,
+            key=lambda edge: float(np.linalg.norm(
+                0.5 * (vertices[edge[0], :2] + vertices[edge[1], :2])
+                - vertices[apex, :2]
+            )),
+        )
+    direction = vertices[second] - vertices[first]
+    return direction / np.linalg.norm(direction)
+
+
+def _transport_hatch_direction(
+    direction: np.ndarray,
+    edge: np.ndarray,
+    source_normal: np.ndarray,
+    target_normal: np.ndarray,
+) -> np.ndarray:
+    """Unfold and refold a tangent vector about the actual shared edge."""
+    along = edge / np.linalg.norm(edge)
+    source_across = np.cross(source_normal, along)
+    target_across = np.cross(target_normal, along)
+    transported = (
+        float(np.dot(direction, along)) * along
+        + float(np.dot(direction, source_across)) * target_across
+    )
+    return transported / np.linalg.norm(transported)
+
+
+def propagated_hatch_directions(
+    faces: Iterable[Iterable[int]],
+    vertices_camera: np.ndarray,
+    visible_faces: Iterable[int],
+    blank_faces: Iterable[int] = (),
+) -> dict[int, np.ndarray]:
+    """Choose seed directions, then transport them in each receiving plane."""
+    faces = tuple(tuple(int(vertex) for vertex in face) for face in faces)
+    vertices = np.asarray(vertices_camera, dtype=float).reshape(-1, 3)
+    visible = {int(face_index) for face_index in visible_faces}
+    blank = visible.intersection(int(face_index) for face_index in blank_faces)
+    if not visible:
+        return {}
+
+    edge_faces: dict[tuple[int, int], list[int]] = {}
+    for face_index, face in enumerate(faces):
+        edges = tuple(
+            tuple(sorted((face[position], face[(position + 1) % len(face)])))
+            for position in range(len(face))
+        )
+        for edge in edges:
+            edge_faces.setdefault(edge, []).append(face_index)
+
+    adjacency = {face_index: set() for face_index in visible}
+    shared_edges: dict[tuple[int, int], tuple[int, int]] = {}
+    for edge, owners in edge_faces.items():
+        visible_owners = [face_index for face_index in owners if face_index in visible]
+        for first in visible_owners:
+            for second in visible_owners:
+                if first == second:
+                    continue
+                adjacency[first].add(second)
+                shared_edges[(first, second)] = edge
+
+    depths = {
+        face_index: float(vertices[list(faces[face_index]), 2].mean())
+        for face_index in visible
+    }
+    order = sorted(visible, key=lambda face_index: (-depths[face_index], face_index))
+    visible_vertices = {vertex for index in visible for vertex in faces[index]}
+    nearest_depth = max(float(vertices[index, 2]) for index in visible_vertices)
+    depth_tolerance = max(1e-12, float(np.ptp(vertices[:, 2])) * 1e-9)
+    nearest_vertices = {
+        index for index in visible_vertices
+        if nearest_depth - float(vertices[index, 2]) <= depth_tolerance
+    }
+    normals = {
+        face_index: _hatch_face_normal(vertices[list(faces[face_index])])
+        for face_index in visible
+    }
+    directions: dict[int, np.ndarray] = {}
+    for face_index in order:
+        if face_index in blank:
+            continue
+        blank_neighbours = adjacency[face_index].intersection(blank)
+        if blank_neighbours:
+            parent = min(blank_neighbours)
+            first, second = shared_edges[(face_index, parent)]
+            direction = vertices[second] - vertices[first]
+            directions[face_index] = direction / np.linalg.norm(direction)
+            continue
+        if nearest_vertices.intersection(faces[face_index]):
+            directions[face_index] = _initial_hatch_direction(faces[face_index], vertices)
+            continue
+        processed_neighbours = [
+            neighbour
+            for neighbour in adjacency[face_index]
+            if neighbour in directions
+            and depths[neighbour] > depths[face_index] + depth_tolerance
+        ]
+        if processed_neighbours:
+            parent = max(
+                processed_neighbours,
+                key=lambda neighbour: (depths[neighbour], -neighbour),
+            )
+            first, second = shared_edges[(face_index, parent)]
+            directions[face_index] = _transport_hatch_direction(
+                directions[parent],
+                vertices[second] - vertices[first],
+                normals[parent],
+                normals[face_index],
+            )
+            continue
+        directions[face_index] = _initial_hatch_direction(faces[face_index], vertices)
+    return directions
+
+
+def face_hatch_segments(
+    face_vertices: np.ndarray,
+    direction: np.ndarray,
+    line_count: int,
+) -> list[tuple[np.ndarray, np.ndarray]]:
+    """Clip full parallel strokes to a convex face in its own 3-D plane."""
+    points = np.asarray(face_vertices, dtype=float)
+    if len(points) < 3 or line_count <= 0:
+        return []
+    origin = points[0]
+    normal = _hatch_face_normal(points)
+    across = np.cross(normal, np.asarray(direction, dtype=float))
+    length = float(np.linalg.norm(across))
+    if length < 1e-12:
+        return []
+    across /= length
+    values = (points - origin) @ across
+    lower, upper = float(values.min()), float(values.max())
+    extent = float(np.max(np.linalg.norm(points - origin, axis=1)))
+    tolerance = max(1e-12, extent * 1e-10)
+    if upper - lower <= tolerance:
+        return []
+    segments = []
+    for step in range(1, int(line_count) + 1):
+        constant = lower + step * (upper - lower) / (line_count + 1.0)
+        crossings = []
+        for index, first in enumerate(points):
+            next_index = (index + 1) % len(points)
+            first_side = values[index] - constant
+            second_side = values[next_index] - constant
+            if abs(first_side) <= tolerance:
+                crossings.append(first.copy())
+            if first_side * second_side < 0.0:
+                fraction = first_side / (first_side - second_side)
+                crossings.append(first + fraction * (points[next_index] - first))
+        unique = []
+        for crossing in crossings:
+            if not any(np.linalg.norm(crossing - other) <= tolerance for other in unique):
+                unique.append(crossing)
+        if len(unique) >= 2:
+            first, second = max(
+                itertools.combinations(unique, 2),
+                key=lambda pair: float(np.linalg.norm(pair[1] - pair[0])),
+            )
+            if np.linalg.norm(second - first) > tolerance:
+                segments.append((first, second))
+    return segments
+
+
+def hatch_division_count(
+    far_factor: float,
+    density_setting: int,
+    depth_setting: int,
+) -> int:
+    """Return the original density with a separate GRIP depth coefficient."""
+    density_norm = (float(density_setting) - 4.0) / (42.0 - 4.0)
+    density_norm = max(0.0, min(1.0, density_norm))
+    near_count = 4.0 + 8.0 * density_norm
+    base_difference = 4.0 + 10.0 * density_norm
+    far_count = near_count + base_difference * (float(depth_setting) / 50.0)
+    depth = max(0.0, min(1.0, float(far_factor)))
+    smooth_depth = depth * depth * (3.0 - 2.0 * depth)
+    count = near_count + (far_count - near_count) * smooth_depth
+    return max(1, int(round(count)))
+
+
+__all__ = [
+    "face_hatch_segments",
+    "hatch_division_count",
+    "occupancy_fractions",
+    "propagated_hatch_directions",
+    "quadrilateral_hatch_line_count",
+]

unit_cell_gui/models.py

@@ -0,0 +1,193 @@
+"""Toolkit-neutral input types for the unit-cell renderer."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from types import MappingProxyType
+from typing import Mapping
+
+import numpy as np
+
+
+def _array(value, shape, dtype=float) -> np.ndarray:
+    result = np.asarray(value, dtype=dtype).reshape(shape).copy()
+    if not np.all(np.isfinite(result)):
+        raise ValueError("Scene coordinates must be finite.")
+    result.setflags(write=False)
+    return result
+
+
+@dataclass(frozen=True)
+class AtomComponent:
+    """One coloured component of an already resolved atomic position."""
+
+    key: str
+    label: str
+    element: str
+    occupancy: float
+    colour: str
+    radius: float
+
+    def __post_init__(self) -> None:
+        occupancy, radius = float(self.occupancy), float(self.radius)
+        if not np.isfinite(occupancy) or not np.isfinite(radius) or radius <= 0:
+            raise ValueError("Component occupancy and radius must be finite; radius must be positive.")
+        object.__setattr__(self, "occupancy", occupancy)
+        object.__setattr__(self, "radius", radius)
+
+
+@dataclass(frozen=True)
+class Atom:
+    """One displayed site image, possibly with mixed occupancy."""
+
+    site_key: str
+    site_label: str
+    components: tuple[AtomComponent, ...]
+    external: bool = False
+
+    def __post_init__(self) -> None:
+        object.__setattr__(self, "components", tuple(self.components))
+        if not self.components:
+            raise ValueError("An atom must contain at least one component.")
+
+
+@dataclass(frozen=True)
+class Polyhedron:
+    """Ready world-space vertices and polygon faces around one site."""
+
+    center: np.ndarray
+    vertices: np.ndarray
+    faces: tuple[tuple[int, ...], ...]
+    site_key: str
+    site_label: str
+    components: tuple[AtomComponent, ...]
+
+    def __post_init__(self) -> None:
+        center = _array(self.center, (3,))
+        vertices = _array(self.vertices, (-1, 3))
+        faces = tuple(tuple(int(index) for index in face) for face in self.faces)
+        if any(len(face) < 3 or any(index < 0 or index >= len(vertices) for index in face)
+               for face in faces):
+            raise ValueError("Every polyhedron face must contain valid vertex indices.")
+        object.__setattr__(self, "center", center)
+        object.__setattr__(self, "vertices", vertices)
+        object.__setattr__(self, "faces", faces)
+        object.__setattr__(self, "components", tuple(self.components))
+
+    @property
+    def elements(self) -> tuple[str, ...]:
+        return tuple(component.element for component in self.components)
+
+    @property
+    def coordination_number(self) -> int:
+        return len(self.vertices)
+
+
+@dataclass(frozen=True)
+class Scene:
+    """Complete render input; no file or crystallographic object is required."""
+
+    atoms: tuple[Atom, ...]
+    atom_centers: np.ndarray
+    bonds: np.ndarray
+    cell_vertices: np.ndarray
+    cell_edges: np.ndarray
+    basis_vectors: np.ndarray
+    polyhedra: tuple[Polyhedron, ...] = ()
+    base_radius: float = 1.0
+    elements: tuple[str, ...] = ()
+
+    def __post_init__(self) -> None:
+        atoms, polyhedra = tuple(self.atoms), tuple(self.polyhedra)
+        atom_centers = _array(self.atom_centers, (-1, 3))
+        bonds = np.asarray(self.bonds, dtype=int).reshape(-1, 2).copy()
+        cell_vertices = _array(self.cell_vertices, (-1, 3))
+        cell_edges = np.asarray(self.cell_edges, dtype=int).reshape(-1, 2).copy()
+        basis_vectors = _array(self.basis_vectors, (3, 3))
+        if len(atoms) != len(atom_centers):
+            raise ValueError("atoms and atom_centers must have the same length.")
+        if len(bonds) and (bonds.min() < 0 or bonds.max() >= len(atoms)):
+            raise ValueError("Bond indices must refer to atoms in the scene.")
+        if len(cell_edges) and (cell_edges.min() < 0 or cell_edges.max() >= len(cell_vertices)):
+            raise ValueError("Cell-edge indices must refer to cell vertices.")
+        if np.any(np.linalg.norm(basis_vectors, axis=0) <= 1e-12):
+            raise ValueError("Every basis vector must be non-zero.")
+        radius = float(self.base_radius)
+        if not np.isfinite(radius) or radius <= 0:
+            raise ValueError("base_radius must be finite and positive.")
+        bonds.setflags(write=False)
+        cell_edges.setflags(write=False)
+        elements = tuple(self.elements) or tuple(sorted({
+            component.element for atom in atoms for component in atom.components
+        }))
+        object.__setattr__(self, "atoms", atoms)
+        object.__setattr__(self, "atom_centers", atom_centers)
+        object.__setattr__(self, "bonds", bonds)
+        object.__setattr__(self, "cell_vertices", cell_vertices)
+        object.__setattr__(self, "cell_edges", cell_edges)
+        object.__setattr__(self, "basis_vectors", basis_vectors)
+        object.__setattr__(self, "polyhedra", polyhedra)
+        object.__setattr__(self, "base_radius", radius)
+        object.__setattr__(self, "elements", elements)
+
+
+@dataclass(frozen=True)
+class DisplayOptions:
+    """All caller-controlled presentation switches and numeric settings."""
+
+    show_atoms: bool = True
+    show_external_atoms: bool = True
+    show_bonds: bool = True
+    show_cell: bool = True
+    show_basis: bool = True
+    show_polyhedra: bool = False
+    engraving: bool = False
+    hatching: bool = True
+    hatch_density: int = 22
+    hatch_grip: int = 50
+    atom_scale: float = 1.0
+    rotation_enabled: bool = True
+
+    def __post_init__(self) -> None:
+        density = int(self.hatch_density)
+        grip = int(self.hatch_grip)
+        scale = float(self.atom_scale)
+        if density < 0 or grip < 0:
+            raise ValueError("Hatching density and GRIP must be non-negative.")
+        if not np.isfinite(scale) or scale <= 0:
+            raise ValueError("atom_scale must be finite and positive.")
+        object.__setattr__(self, "hatch_density", density)
+        object.__setattr__(self, "hatch_grip", grip)
+        object.__setattr__(self, "atom_scale", scale)
+
+
+@dataclass(frozen=True)
+class StyleOverrides:
+    """Per-site presentation changes supplied by the host application."""
+
+    atom_component_visibility: Mapping[str, bool] = field(default_factory=dict)
+    atom_component_colours: Mapping[str, str] = field(default_factory=dict)
+    polyhedron_site_visibility: Mapping[str, bool] = field(default_factory=dict)
+    polyhedron_site_colours: Mapping[str, str] = field(default_factory=dict)
+    polyhedron_opaque_sites: frozenset[str] = frozenset()
+
+    def __post_init__(self) -> None:
+        visibility = self.atom_component_visibility or {}
+        colours = self.atom_component_colours or {}
+        poly_visibility = self.polyhedron_site_visibility or {}
+        poly_colours = self.polyhedron_site_colours or {}
+        object.__setattr__(self, "atom_component_visibility", MappingProxyType({
+            str(key): bool(value) for key, value in visibility.items()
+        }))
+        object.__setattr__(self, "atom_component_colours", MappingProxyType({
+            str(key): str(value) for key, value in colours.items()
+        }))
+        object.__setattr__(self, "polyhedron_site_visibility", MappingProxyType({
+            str(key): bool(value) for key, value in poly_visibility.items()
+        }))
+        object.__setattr__(self, "polyhedron_site_colours", MappingProxyType({
+            str(key): str(value) for key, value in poly_colours.items()
+        }))
+        object.__setattr__(self, "polyhedron_opaque_sites", frozenset(
+            str(key) for key in self.polyhedron_opaque_sites
+        ))

unit_cell_gui/py.typed

@@ -0,0 +1 @@
+