Core Crates

5.1 Backbone (core/backbone/src/lib.rs)

  • Defines newtype identifiers (AtomId, BondId, FrameId, PropertyId) and element metadata (periodic module) used across the workspace.
  • SceneBuilder constructs snapshots with atoms, bonds, metadata, and derived data (electronic structure, vibrational modes, thermochemistry). SceneGraph wraps the snapshot with provenance hashing (SceneDigest) for change detection.
  • PropertyRegistry stores globally registered per-atom or per-scene properties, enabling dynamic queries and render overlays.
  • Exports helpers such as infer_covalent_bonds, AtomPopulation, FrequencyData, Trajectory, and UnitCell. Loader and renderer crates consume these types.

5.2 Query & Selection (core/query, core/selection-engine)

  • core/query provides the selection expression enum, parser, and evaluator. Supported primitives include element filters (element O, bare symbols, atomic_number == Z), distance shells, angle windows, nearest-neighbour queries, and property comparisons.
  • Primitives combine through the And / Or / Not AST variants, plus WithinSelection (the within <R> of <selection> operator, evaluated as the set of atoms within the radius of any anchor matched by the sub-selection). parse_expression (core/query/src/query/parsing.rs) is a two-layer parser: a lexer keeps function-call parens and quoted property names inside one primitive token, and a recursive-descent layer handles the boolean operators, the within … of prefix, and grouping (not > and > or). Element symbols resolve to AtomicNumber via orbitron_backbone::atomic_number_for_symbol, so evaluation and formatting reuse the existing atomic-number path. PropertyCompare carries a CompareOp (>, >=, <, <=, ==, !=).
  • parse_expression returns SelectionExpr ASTs; the UI’s command palette and CLI subcommands rely on it to turn input strings into programs.
  • evaluate_selection resolves expressions against a SceneGraph. Errors are surfaced via QueryError (UnknownProperty, NonNumericProperty, Evaluation).
  • core/selection-engine::SelectionProgram wraps expressions with digest-aware caching and optional scoring metadata (SelectionScore). This crate is responsible for keeping UI selection interactions performant.

5.3 Rendering Core (core/render)

  • Renderer::new initialises a WGPU surface for a winit::window::Window. Headless rendering (headless module) enables CLI exports without a window.
  • RenderSceneData aggregates instanced atoms, bonds, and labels ready for GPU upload. Helper functions (pick_atom, distance_between) are used by the viewer for hit-testing.
  • Lighting presets live in lighting.rs; set_colorblind_safe (in core/render/src/lib.rs) toggles the Okabe–Ito palette globally.
  • Bonds are rendered as instanced quads with per-instance thickness, dash, and glossiness. BondInstance::order plus orbitron_viewer_core::render_styles::apply_theme_styles (shared by desktop + CLI; ui/shell/src/util/render_styles.rs is a re-export shim) expand double/triple/quad bonds into multiple lanes using theme-provided spacing and highlight scaling.
  • Mesh pipelines (mesh::MeshRenderPipeline) handle GPU buffer management; renderer crates are the only place WGPU appears, keeping other crates backend-agnostic.

5.3.1 Embedding Orbitron Renderer (EmbeddedRenderer)

You can host Orbitron’s GPU renderer inside your own application window without using the egui UI shell. This is useful for Rust hosts (Tauri, winit, native desktop apps) that want to reuse Orbitron’s rendering pipeline.

Prerequisites

  • Rust toolchain from rust-toolchain.toml (or newer).
  • Access to a SceneGraph (load via orbitron-io-pipelines::load_scene, or via OrbitronServices, or construct using SceneBuilder).

Minimal integration

orbitron_render::EmbeddedRenderer wraps the renderer with a synchronous API. For a full runnable reference see examples/sdk/ (Rust SDK integration) and examples/web-embedding/ (WASM viewer); a minimal sketch follows:

use anyhow::Result;
use orbitron_io_pipelines as io;
use orbitron_render::{Camera, EmbeddedRenderer};
use std::sync::Arc;
use winit::{
    event::{Event, WindowEvent},
    event_loop::{ControlFlow, EventLoop},
    window::WindowBuilder,
};

fn main() -> Result<()> {
    let scene = Arc::new(io::load_scene("fixtures/benzene.xyz")?);

    let event_loop = EventLoop::new()?;
    let window = WindowBuilder::new()
        .with_title("Orbitron Embedded Viewer")
        .build(&event_loop)?;

    let mut engine = EmbeddedRenderer::new(&window)?;
    engine.prepare_scene(scene.as_ref(), None, None);

    let mut camera = Camera::new(
        [0.0, 0.0, 40.0],
        [0.0, 0.0, 0.0],
        [0.0, 1.0, 0.0],
        engine.renderer().aspect_ratio(),
    );

    event_loop.run(move |event, elwt| {
        elwt.set_control_flow(ControlFlow::Poll);
        match event {
            Event::WindowEvent { event, .. } => match event {
                WindowEvent::CloseRequested => elwt.exit(),
                WindowEvent::Resized(size) => {
                    engine.resize(size);
                    camera.set_aspect(size.width as f32 / size.height.max(1) as f32);
                }
                _ => {}
            },
            Event::RedrawRequested(_) => {
                if let Err(err) = engine.render_prepared(&camera, None) {
                    tracing::error!("Render failed: {err:?}");
                }
            }
            Event::AboutToWait => window.request_redraw(),
            _ => {}
        }
    })?;

    #[allow(unreachable_code)]
    Ok(())
}

Key steps:

  1. Create an EmbeddedRenderer from your winit::window::Window.
  2. Call prepare_scene whenever the scene or highlight selection changes.
  3. Call render_prepared in your redraw loop with your Camera.

5.4 Editing Engine (core/edit)

  • Provides the edit-mode foundation: EditableScene, EditCommand implementations, ID helpers, and geometry utilities.
  • command.rs enumerates high-level actions (add atom, delete bond, translate selection).
  • ops.rs executes mutations against editable scenes, ensuring invariants such as bond symmetry and selection history updates.
  • The viewer’s Edit Mode panels (ui/shell/src/edit) invoke these commands via run_edit_command_with_feedback, emitting undo/redo stacks and error toasts.

5.5 Scheduler (core/scheduler)

  • Scheduler wraps a Tokio runtime for background jobs. It assigns JobIds, tracks handles, and supports graceful shutdown (see core/scheduler/src/lib.rs).