From 6a62a4698b00c1dfb50aa7f8161cc77ce62a8a74 Mon Sep 17 00:00:00 2001 From: zachcp Date: Sat, 20 Jul 2024 11:12:46 -0400 Subject: [PATCH] Update Docs (#11) * update docs * docs * update nodes * add links to the soruce code --- src/lib.rs | 24 +++++++++++++++-- src/molviewspec/nodes.rs | 50 ++++++++++++++++++++++++++++++++-- src/pymolparsing/parsing.rs | 22 +++++++++++++-- src/pymolparsing/psedata.rs | 54 +++++++++++++++++++------------------ 4 files changed, 118 insertions(+), 32 deletions(-) diff --git a/src/lib.rs b/src/lib.rs index 1ac1da7..98bc8a3 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -1,6 +1,26 @@ -//! This crate is for loading and serializing pymol's PSE filetype +//! # PyMOL PSE Parser //! -//! it is currently a work in progress. +//! A Rust crate for working with PyMOL PSE (PyMOL Session) files. +//! +//! ## Features +//! +//! - Load and parse PSE files +//! - Serialize PSE data +//! - Access molecular structures and visualization settings +//! +//! ## Usage +//! +//! ```rust +//! use pymolparsing::psedata::PSEData; +//! let pse_data = PSEData::load("path/to/file.pse"); +//! // Work with the loaded PSE data +//! psedata.to_disk_full("my_output_directory"); +//! ``` +//! +//! ## Modules +//! +//! - `molviewspec`: Handles molecular viewing specifications +//! - `pymolparsing`: Core parsing functionality for PSE files //! pub mod molviewspec; pub mod pymolparsing; diff --git a/src/molviewspec/nodes.rs b/src/molviewspec/nodes.rs index b506962..e36be04 100644 --- a/src/molviewspec/nodes.rs +++ b/src/molviewspec/nodes.rs @@ -1,9 +1,31 @@ +//! This module has functionality to build up MolViewSpec. +//! +//! MolViewSpec (MVS) is a lightweight, JSON-based specification for describing molecular structures and their visual representation. +//! It is designed to be human-readable, easily shareable, and compatible with various molecular visualization tools. +//! +//! - MolViewSpec GitHub repository: https://github.com/molstar/mol-view-spec +//! - MolViewSpec documentation: https://molstar.org/viewer/molviewspec/ +//! - MolStar Viewer (which supports MVS): https://molstar.org/viewer/ +//! +//! We try to adhere very closely to the python library API. Almost all of the action happens +//! on the `Nodes`. Because we are building a nested tree of data, we need most of the parts to +//! be mutable and you can see almost all of the function calls: +//! +//! 1. check the type and the params and act only on correct parent nodes +//! 2. beacuse of 1, we return `Option<>` +//! 3. If a node is returned is it `&mut Node` +//! +//! use chrono::Utc; use serde::{Deserialize, Serialize}; use serde_json; use urlencoding; use validator::Validate; +// KindT +// +// Enum of node types corresponding to the MolViewSpec Nodes +// #[derive(PartialEq, Serialize, Deserialize, Debug, Default, Clone)] #[serde(rename_all = "snake_case")] pub enum KindT { @@ -34,6 +56,10 @@ pub enum KindT { Transform, } +// NodeParams +// +// Enum of params per node type. Each of the variants are typed. +// #[derive(Serialize, Deserialize, Debug, Clone)] #[serde(untagged)] pub enum NodeParams { @@ -68,6 +94,7 @@ pub enum NodeParams { /// This is the core datastructure for generating MSVJ files. Each node type can have a type, params, and children. /// /// Methods derived from the Python API found [here](https://github.com/molstar/mol-view-spec/blob/master/molviewspec/molviewspec/builder.py) +/// #[derive(Serialize, Deserialize, Debug, Default, Clone)] pub struct Node { pub kind: KindT, @@ -317,6 +344,11 @@ pub enum DescriptionFormatT { Plaintext, } +/// Metadata +/// +/// The molviewspec metadata. High level info unrelated to +/// structure visualization. +/// #[derive(Serialize, Deserialize, Debug, Default)] pub struct Metadata { pub version: String, @@ -329,6 +361,11 @@ pub struct Metadata { pub timestamp: String, } +/// This is the base MolViewSpec object containing +/// the root node and the metadata +/// +/// Holds methods that modify the root node. +/// #[derive(Serialize, Deserialize, Debug)] pub struct State { pub root: Node, @@ -370,7 +407,6 @@ impl State { pub fn generic_visuals() { unimplemented!() } - pub fn to_url(&self) -> String { let json = serde_json::to_string(&self).expect("Json conversion"); let encoded = urlencoding::encode(&json); @@ -382,6 +418,7 @@ impl State { } } +/// Types of coumpounds: for pse I am only using PDB #[derive(Serialize, Deserialize, Debug, Clone)] #[serde(rename_all = "lowercase")] pub enum ParseFormatT { @@ -396,6 +433,7 @@ pub struct ParseParams { pub format: ParseFormatT, } +/// StructureType. Useful for specifying more complicated sets of structures #[derive(Serialize, Deserialize, Debug, Clone)] #[serde(rename_all = "snake_case")] pub enum StructureTypeT { @@ -410,6 +448,7 @@ impl Default for StructureTypeT { } } +/// Structure Params #[derive(Serialize, Deserialize, Debug, Clone, Default)] pub struct StructureParams { #[serde(rename = "type")] @@ -432,6 +471,10 @@ pub struct StructureParams { pub ijk_max: Option<(i32, i32, i32)>, } +/// Component Selector Type +/// +/// Useful for specifying broad groups like 'all', +/// 'protein', etc. #[derive(Serialize, Deserialize, Debug, Clone)] #[serde(rename_all = "snake_case")] pub enum ComponentSelectorT { @@ -444,7 +487,7 @@ pub enum ComponentSelectorT { Ion, Water, } - +/// Component Expresssion #[derive(Serialize, Deserialize, Debug, Clone, Default)] pub struct ComponentExpression { #[serde(skip_serializing_if = "Option::is_none")] @@ -481,6 +524,7 @@ pub struct ComponentExpression { pub atom_index: Option, } +/// Representation Type #[derive(Serialize, Deserialize, Debug, Clone)] #[serde(rename_all = "snake_case")] pub enum RepresentationTypeT { @@ -489,6 +533,7 @@ pub enum RepresentationTypeT { Surface, } +/// Color Names #[derive(Serialize, Deserialize, Debug, Clone)] #[serde(rename_all = "lowercase")] pub enum ColorNamesT { @@ -641,6 +686,7 @@ pub enum ColorNamesT { Yellowgreen, } +/// Color Type: Named or Hex #[derive(Serialize, Deserialize, Debug, Clone)] #[serde(untagged)] pub enum ColorT { diff --git a/src/pymolparsing/parsing.rs b/src/pymolparsing/parsing.rs index c102804..2222726 100644 --- a/src/pymolparsing/parsing.rs +++ b/src/pymolparsing/parsing.rs @@ -15,7 +15,8 @@ //! //! ## Links //! -//! - [Molecule Experter](https://github.com/schrodinger/pymol-open-source/blob/master/layer3/MoleculeExporter.cpp#L1627) +//! - [pymol-open-source](https://github.com/schrodinger/pymol-open-source). Pymol Source code. +//! - [Molecule Exporter](https://github.com/schrodinger/pymol-open-source/blob/master/layer3/MoleculeExporter.cpp#L1627) //! - [PymolMoleculeExporter](https://github.com/schrodinger/pymol-open-source/blob/03d7a7fcf0bd95cd93d710a1268dbace2ed77765/layer4/Cmd.cpp#L3877) //! - [PDB Exporter](https://github.com/schrodinger/pymol-open-source/blob/master/layer3/MoleculeExporter.cpp#L1627) //! - [MoleculeExporterPDB](https://github.com/schrodinger/pymol-open-source/blob/master/layer3/MoleculeExporter.cpp#L439) @@ -477,6 +478,10 @@ impl PyObjectMolecule { } } +/// PymolSessionObjectData +/// +/// Differentiate between serializing an object or a selection +/// They have different `shapes` and require custom deserialization. #[derive(Debug, Serialize)] #[serde(untagged)] pub enum PymolSessionObjectData { @@ -623,7 +628,11 @@ impl<'de> Deserialize<'de> for SceneView { } } } - +/// SessionName +/// +/// High level info about a session obeject. +/// Can be an object/molecule or a selection +/// #[derive(Debug, Deserialize, Serialize)] pub struct SessionName { pub name: String, @@ -635,6 +644,10 @@ pub struct SessionName { pub group: String, } +/// Session Selector +/// +/// Defines a pymole seleciton in terms of names and +/// atom indices. #[derive(Debug, Serialize)] pub struct SessionSelector { // SelectorAsPyList @@ -686,6 +699,11 @@ impl SessionSelectorList { } } +/// Global Pymol Settings +/// +/// This enum is derived from [SettingInfo.h](https://github.com/schrodinger/pymol-open-source/blob/master/layer1/SettingInfo.h), +/// pymol's setting specification +/// #[derive(Serialize_repr, Deserialize_repr, PartialEq, Debug, Clone)] #[repr(u32)] pub enum SettingsEnum { diff --git a/src/pymolparsing/psedata.rs b/src/pymolparsing/psedata.rs index 6d14e0a..94b9a5a 100644 --- a/src/pymolparsing/psedata.rs +++ b/src/pymolparsing/psedata.rs @@ -5,28 +5,6 @@ //! Currently the parsers are working for small test cases of molecules and selections. Additional parser structs would be required for //! other PSE data types which include the folloing: //! -//! ## PyObject Serialization -//! -//! Code: -//! -[pyobject](https://github.com/schrodinger/pymol-open-source/blob/03d7a7fcf0bd95cd93d710a1268dbace2ed77765/layer1/PyMOLObject.cpp#L681) -//! -//! Python Obects: -//! - Object -//! - Gadget -//! - Molecule ---> WIP. -//! - Dist -//! - Map -//! - Mesh -//! - Slice -//! - Surface -//! - CGO -//! - Alignment -//! - Group -//! - Volume -//! - Callback -//! - Curve -//! - Selection ---> WIP. -//! use crate::molviewspec::nodes::{self as mvsnodes, CameraParams, ColorNamesT, State}; use crate::pymolparsing::parsing::{ @@ -44,7 +22,11 @@ use std::path::Path; /// PSEData represents the structure of a PyMOL Session File (PSE). /// -/// This struct contains various components of a PyMOL session, including: +/// We lean heavily on `serde_pickle` to deserialize the PSE binary +/// file into named structs, of which `PSEData` is the highlest level object containing +/// most of the required methods for operating on PSE files. +/// +/// This struct contains various components of a PyMOL session, including: /// - Version information /// - Color settings /// - View settings @@ -53,8 +35,28 @@ use std::path::Path; /// - Cached data /// - Session names and associated objects /// -/// It provides methods for loading PSE files, converting to JSON, -/// extracting molecule and selection data, and creating PDB files. +/// To be implemented in time: +/// +/// PyObject : +/// -[pyobject](https://github.com/schrodinger/pymol-open-source/blob/03d7a7fcf0bd95cd93d710a1268dbace2ed77765/layer1/PyMOLObject.cpp#L681) +/// +/// Python Obects: +/// - Object +/// - Gadget +/// - Molecule ---> WIP. +/// - Dist +/// - Map +/// - Mesh +/// - Slice +/// - Surface +/// - CGO +/// - Alignment +/// - Group +/// - Volume +/// - Callback +/// - Curve +/// - Selection ---> WIP. +/// #[derive(Debug, Deserialize, Serialize)] pub struct PSEData { pub version: i32, @@ -72,7 +74,7 @@ pub struct PSEData { moviescenes: Vec>, // High level state settings: we need to prpogate these.. pub settings: Vec, - movie: ( + pub movie: ( i32, i32, Vec,