unit-cell-gui 0.1.0__tar.gz

unit_cell_gui-0.1.0/CHANGELOG.md

@@ -0,0 +1,14 @@
+# Changelog
+
+## 0.1.0
+
+- Added immutable input models for caller-supplied atoms, bonds, unit cells,
+  basis vectors and ready polyhedra.
+- Added native PySide6 rendering with depth ordering, colour and monochrome
+  atoms, mixed occupancies, bonds, cell edges and basis arrows.
+- Added polyhedron hatching, including intact quadrilateral faces with
+  `2x + 1` strokes and direction transport through real shared edges.
+- Added left-button rotation with complete orientation-matrix events,
+  right-button panning, wheel zoom and a switch for disabling rotation.
+- Added global display options and copied per-site style overrides.
+- Set polyhedra to hidden by default.

unit_cell_gui-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mikhail Mirushchenko
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

unit_cell_gui-0.1.0/MANIFEST.in

@@ -0,0 +1,4 @@
+include CHANGELOG.md
+include LICENSE
+include README.md
+recursive-include tests *.py

unit_cell_gui-0.1.0/PKG-INFO

@@ -0,0 +1,117 @@
+Metadata-Version: 2.4
+Name: unit-cell-gui
+Version: 0.1.0
+Summary: PySide6 widget for rendering caller-supplied unit-cell scenes
+Author-email: Mikhail Mirushchenko <miruschenko98@gmail.com>
+License-Expression: MIT
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: X11 Applications :: Qt
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.24
+Requires-Dist: PySide6-Essentials<7,>=6.8
+Dynamic: license-file
+
+# unit-cell-gui
+
+`unit-cell-gui` is a reusable PySide6 widget that draws complete unit-cell
+scenes supplied by another program. It does not read CIF files, expand
+symmetry, resolve atomic positions, infer bonds, construct polyhedra or
+calculate diffraction.
+
+The caller supplies ready Cartesian coordinates and presentation data:
+
+- atoms and their styled occupancy components;
+- bond indices;
+- unit-cell vertices and edges;
+- three basis vectors;
+- optional polyhedron vertices, polygon faces and centres.
+
+The package owns only display behaviour: camera projection, depth sorting,
+left-button rotation, right-button panning, wheel zoom, occupancy sectors,
+colour and black-and-white drawing, and polyhedron hatching. Quadrilateral
+hatching uses one intact polygon with `2x + 1` full parallel strokes. Hatch
+directions on farther faces are refolded through real shared edges.
+
+## Installation
+
+```bash
+python -m pip install unit-cell-gui
+```
+
+Python 3.10 or newer, NumPy and PySide6 Essentials are required.
+
+## Basic use
+
+```python
+import numpy as np
+from PySide6.QtWidgets import QApplication
+from unit_cell_gui import Atom, AtomComponent, DisplayOptions, Scene, UnitCellViewer
+
+silicon = AtomComponent(
+    key="Si:Si1", label="Si1", element="Si",
+    occupancy=1.0, colour="#f0c8a0", radius=0.30,
+)
+scene = Scene(
+    atoms=(Atom("Si:Si1", "Si1", (silicon,)),),
+    atom_centers=np.array([[0.0, 0.0, 0.0]]),
+    bonds=np.empty((0, 2), dtype=int),
+    cell_vertices=np.array([
+        [x, y, z]
+        for x in (-1.0, 1.0)
+        for y in (-1.0, 1.0)
+        for z in (-1.0, 1.0)
+    ]),
+    cell_edges=np.array([
+        [0, 1], [0, 2], [0, 4], [1, 3], [1, 5], [2, 3],
+        [2, 6], [3, 7], [4, 5], [4, 6], [5, 7], [6, 7],
+    ]),
+    basis_vectors=np.eye(3),
+    base_radius=2.0,
+)
+
+app = QApplication([])
+viewer = UnitCellViewer()
+viewer.set_scene(scene)
+viewer.set_display_options(DisplayOptions(show_polyhedra=False))
+viewer.show()
+app.exec()
+```
+
+`Scene` copies its arrays and makes them read-only. Later changes in the caller
+therefore cannot alter an already submitted scene.
+
+## Orientation synchronization
+
+`orientation` is a 3 by 3 world-to-camera matrix. For column vectors the
+camera coordinate is `orientation @ world`; the renderer's row arrays use the
+equivalent `world @ orientation.T`.
+
+Programmatic changes are silent by default:
+
+```python
+viewer.set_orientation(matrix, emit=False)
+```
+
+Interactive rotation emits the complete new matrix through
+`orientation_changed`. Connect that signal to a pole figure or another view,
+then send changes from the other view back with silent `set_orientation` calls.
+This supports bidirectional synchronization without a signal loop.
+
+```python
+viewer.orientation_changed.connect(update_other_view)
+other_view.orientation_changed.connect(
+    lambda matrix: viewer.set_orientation(matrix, emit=False)
+)
+```
+
+Set `rotation_enabled=False` when an application temporarily forbids left-button
+rotation. Panning and zoom remain available. Polyhedra are hidden by default
+and must be enabled with `show_polyhedra=True`.
+
+Per-position colours, visibility and opaque-polyhedron selections are replaced
+atomically with `viewer.set_style_overrides(StyleOverrides(...))`. The widget
+copies these mappings, so the host can keep its own independent UI state.

unit_cell_gui-0.1.0/README.md

@@ -0,0 +1,100 @@
+# unit-cell-gui
+
+`unit-cell-gui` is a reusable PySide6 widget that draws complete unit-cell
+scenes supplied by another program. It does not read CIF files, expand
+symmetry, resolve atomic positions, infer bonds, construct polyhedra or
+calculate diffraction.
+
+The caller supplies ready Cartesian coordinates and presentation data:
+
+- atoms and their styled occupancy components;
+- bond indices;
+- unit-cell vertices and edges;
+- three basis vectors;
+- optional polyhedron vertices, polygon faces and centres.
+
+The package owns only display behaviour: camera projection, depth sorting,
+left-button rotation, right-button panning, wheel zoom, occupancy sectors,
+colour and black-and-white drawing, and polyhedron hatching. Quadrilateral
+hatching uses one intact polygon with `2x + 1` full parallel strokes. Hatch
+directions on farther faces are refolded through real shared edges.
+
+## Installation
+
+```bash
+python -m pip install unit-cell-gui
+```
+
+Python 3.10 or newer, NumPy and PySide6 Essentials are required.
+
+## Basic use
+
+```python
+import numpy as np
+from PySide6.QtWidgets import QApplication
+from unit_cell_gui import Atom, AtomComponent, DisplayOptions, Scene, UnitCellViewer
+
+silicon = AtomComponent(
+    key="Si:Si1", label="Si1", element="Si",
+    occupancy=1.0, colour="#f0c8a0", radius=0.30,
+)
+scene = Scene(
+    atoms=(Atom("Si:Si1", "Si1", (silicon,)),),
+    atom_centers=np.array([[0.0, 0.0, 0.0]]),
+    bonds=np.empty((0, 2), dtype=int),
+    cell_vertices=np.array([
+        [x, y, z]
+        for x in (-1.0, 1.0)
+        for y in (-1.0, 1.0)
+        for z in (-1.0, 1.0)
+    ]),
+    cell_edges=np.array([
+        [0, 1], [0, 2], [0, 4], [1, 3], [1, 5], [2, 3],
+        [2, 6], [3, 7], [4, 5], [4, 6], [5, 7], [6, 7],
+    ]),
+    basis_vectors=np.eye(3),
+    base_radius=2.0,
+)
+
+app = QApplication([])
+viewer = UnitCellViewer()
+viewer.set_scene(scene)
+viewer.set_display_options(DisplayOptions(show_polyhedra=False))
+viewer.show()
+app.exec()
+```
+
+`Scene` copies its arrays and makes them read-only. Later changes in the caller
+therefore cannot alter an already submitted scene.
+
+## Orientation synchronization
+
+`orientation` is a 3 by 3 world-to-camera matrix. For column vectors the
+camera coordinate is `orientation @ world`; the renderer's row arrays use the
+equivalent `world @ orientation.T`.
+
+Programmatic changes are silent by default:
+
+```python
+viewer.set_orientation(matrix, emit=False)
+```
+
+Interactive rotation emits the complete new matrix through
+`orientation_changed`. Connect that signal to a pole figure or another view,
+then send changes from the other view back with silent `set_orientation` calls.
+This supports bidirectional synchronization without a signal loop.
+
+```python
+viewer.orientation_changed.connect(update_other_view)
+other_view.orientation_changed.connect(
+    lambda matrix: viewer.set_orientation(matrix, emit=False)
+)
+```
+
+Set `rotation_enabled=False` when an application temporarily forbids left-button
+rotation. Panning and zoom remain available. Polyhedra are hidden by default
+and must be enabled with `show_polyhedra=True`.
+
+Per-position colours, visibility and opaque-polyhedron selections are replaced
+atomically with `viewer.set_style_overrides(StyleOverrides(...))`. The widget
+copies these mappings, so the host can keep its own independent UI state.

unit_cell_gui-0.1.0/pyproject.toml

@@ -0,0 +1,31 @@
+[build-system]
+requires = ["setuptools>=77", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "unit-cell-gui"
+version = "0.1.0"
+description = "PySide6 widget for rendering caller-supplied unit-cell scenes"
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [
+    {name = "Mikhail Mirushchenko", email = "miruschenko98@gmail.com"},
+]
+dependencies = [
+    "numpy>=1.24",
+    "PySide6-Essentials>=6.8,<7",
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Environment :: X11 Applications :: Qt",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+]
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+unit_cell_gui = ["py.typed"]

unit_cell_gui-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

unit_cell_gui-0.1.0/src/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-0.1.0/src/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",
+]