sesmesh 1.3.2
Learn · five walkthroughs

Tutorials

Five short, complete walkthroughs with real inputs from the PDB and the output they produce. Commands assume sesmesh 1.1 on your PATH (cargo install sesmesh-cli), plus curl and jq.

01

PDB ID → picture

CLI · 10 minutes · haemoglobin (4HHB)

  1. Download a structure

    Any entry from the PDB works; mmCIF is the archive's native format. sesmesh reads it gzipped.

    Shell
    $ curl -LO https://files.rcsb.org/download/4HHB.cif.gz
  2. Look before you mesh

    info shows models, chains, composition and whether the radius set covers every atom.

    Shell
    $ sesmesh info 4HHB.cif.gz
    chains: 4 (A:1168 B:1224 C:1171 D:1216)
    elements: C:2954 O:1027 N:780 S:12 Fe:4 P:2
    hetero atoms: 395  hydrogens: 0  water atoms: 221  alt-loc atoms: 0
    selected: 4558 atoms
    radii (bondi): 4554 of 4558 atoms covered, 4 fallback (1.80 Å)
  3. Mesh it

    A fine grid for detail, internal cavities removed, colours by chain, then decimated to 30 % of the triangles — the kept vertices are still exactly on the surface.

    Shell
    $ sesmesh 4HHB.cif.gz -q high --cavities remove \
        --vertex-colors chain --decimate 0.3 -o 4hhb.ply
  4. Open it

    Binary PLY keeps positions, normals and colours compactly. Blender: File ▸ Import ▸ Stanford PLY, then in the material feed a Color Attribute node into Base Color. MeshLab and ParaView open it directly. For tools that prefer OBJ, write -o 4hhb.obj (colours as v x y z r g b).

  5. Try other colourings

    Shell
    # chemistry: the nearest atom's element (bundled palette, or --palette file.json)
    $ sesmesh 4HHB.cif.gz -q high --vertex-colors element -o 4hhb-el.ply
    # geometry: convex (contact), saddle (toroidal) and concave (re-entrant) patches
    $ sesmesh 4HHB.cif.gz -q high --vertex-colors patch -o 4hhb-patch.ply
02

Cavities & areas

CLI + jq + Python · 15 minutes · GroEL–GroES (1AON), haemoglobin (4HHB)

  1. Keep only the cavities

    The exact SES contains closed internal cavities with negative signed volume. Keep just them, drop the tiny ones, and record the numbers.

    Shell
    $ sesmesh 1AON.cif.gz -q high --cavities only --min-cavity-volume 5 \
        --group-components --stats cavities.json -o cavities.obj
    $ jq '[.components[] | select(.cavity)] | length' cavities.json
    285
    $ jq -c '.components[] | select(.cavity) | {index, volume, area}' cavities.json | head -3
    {"index":0,"volume":-13.174403395890868,"area":27.0622199529793}
    {"index":1,"volume":-11.614457386530887,"area":24.868030910443903}
    {"index":2,"volume":-86.08582206107998,"area":128.0659578151871}
  2. Per-atom surface area

    --atom-areas writes the SES area of every selected atom: index, serial, chain, residue, atom name, element, radius, area.

    Shell
    $ sesmesh 4HHB.cif.gz -q high --atom-areas areas.csv -o /dev/null
    $ head -3 areas.csv
    atom,serial,chain,res_name,res_seq,ins_code,atom_name,element,radius,area
    0,1,A,VAL,1,,N,N,1.550,16.8767

    Save as residues.py and sum per residue with nothing but the standard library:

    Python
    import csv
    from collections import defaultdict
    
    area = defaultdict(float)
    with open("areas.csv") as f:
        for row in csv.DictReader(f):
            area[(row["chain"], row["res_name"], int(row["res_seq"]))] += float(row["area"])
    
    for (chain, name, seq), a in sorted(area.items(), key=lambda kv: -kv[1])[:10]:
        print(f"{chain} {name}{seq}: {a:.1f} Ų")
    Shell
    $ python3 residues.py
    C HEM142: 217.9 Ų
    D HEM148: 214.8 Ų
    B HEM148: 211.8 Ų
    ...
  3. Buried interface area

    The surface two chains lose when they meet: mesh each chain alone and together, then subtract.

    Shell
    $ for c in A B A,B; do
      sesmesh 4HHB.cif.gz -q high --chains $c --no-hetatm --cavities remove \
        --stats - -o /dev/null --quiet | jq .mesh.area
    done
    7197.0    # A
    7493.8    # B
    13651.5   # A,B   → buried: 7197.0 + 7493.8 − 13651.5 = 1039.3 Ų
03

A virus on a laptop

CLI · 10 minutes · dengue virus capsid (1K4R, assembly 1)

  1. Find the assembly

    Deposited coordinates are often one asymmetric unit. The biological assembly is built from the file's operators.

    Shell
    $ curl -LO https://files.rcsb.org/download/1K4R.cif.gz
    $ sesmesh info 1K4R.cif.gz
    chains: 3 (A:3028 B:3028 C:3028)
    assemblies: 1 (60 copies), 2 (1 copy), 3 (5 copies), 4 (6 copies), 5 (1 copy)
  2. Mesh 545 040 atoms

    The full dengue virus capsid at 1 Å: about 10 s and 9.9 million triangles on a 10-core laptop (about 6 s on an AMD Zen 5 16-core system), in under 2 GB of memory.

    Shell
    $ sesmesh 1K4R.cif.gz --assembly 1 -q draft --progress --timings -o capsid.ply
    sesmesh: 4937664 vertices, 9883296 triangles, 1123 component(s) (1098 cavities), ...
  3. Make it viewer-friendly

    Cap the triangle count and colour by chain; decimation keeps the surface exact where it keeps vertices.

    Shell
    $ sesmesh 1K4R.cif.gz --assembly 1 -q draft --max-triangles 1500000 \
        --vertex-colors chain -o capsid-1.5M.ply
  4. Set a memory budget

    Before any mesh exists, sesmesh estimates the peak memory of the whole run. With --max-memory alone, inputs whose estimate exceeds the limit stop with exit code 4. Add --auto-coarsen to grow the spacing until the estimate fits; the spacing used and the estimate are printed, and the statistics JSON records them (engine.estimated_memory, engine.estimated_triangles).

    Shell
    $ sesmesh 1K4R.cif.gz --assembly 1 -q high --max-memory 1G --auto-coarsen \
        --max-triangles 1500000 -o capsid.ply
    sesmesh: ... 545040 atoms (model 1), ses surface, probe 1.40 Å, grid 2.402 Å
    sesmesh: estimated peak memory 1008.2 MiB (limit 1024.0 MiB, about 1837964 triangles before decimation)
    sesmesh: 745560 vertices, 1500000 triangles, 979 component(s) (810 cavities), ...
    The estimate is deliberately conservative: this run peaked at about 0.65 GB against an estimate of 1008 MiB. The grid chosen and the estimate are the same on every run and for any thread count.
  5. Stop any time

    Ctrl-C cancels within about 100 ms and exits with code 130.

04

Ambient occlusion

CLI + Python · 10 minutes · haemoglobin (4HHB)

  1. Get aomesh and the script

    Ambient occlusion darkens what little light reaches: pockets, clefts, the seams between chains. sesmesh does not compute it; aomesh, a separate program, bakes it into any OBJ afterwards, and ses_ao.py (Python standard library only) runs the two in a row.

    Shell
    $ cargo install aomesh-cli          # 0.4.0 or later
    $ curl -LO https://raw.githubusercontent.com/uvar-apps/sesmesh/main/tools/ao/ses_ao.py
  2. Mesh and bake

    Options after -- go to sesmesh unchanged. --bake-colors also writes a PLY whose vertex colours are the chain colours times the AO.

    Shell
    $ python3 ses_ao.py 4HHB.cif.gz -o out --bake-colors \
        -- -q high --vertex-colors chain --decimate 0.5
    sesmesh: 320764 vertices, 641472 triangles, 33 component(s) (31 cavities), ...
    visibility  min 0.000  mean 0.445  max 1.000
    ses_ao: 4HHB.cif.gz: wrote 4HHB_ao.obj, 4HHB_ao.mtl, 4HHB_ao.png, 4HHB_ao.ply in out
            (sesmesh 1.19 s, aomesh 3.34 s, colours 1.42 s)
  3. What is in the files

    4HHB_ao.obj is the sesmesh surface unchanged (colours, normals, header) plus one texture coordinate per vertex, its AO value; 4HHB_ao.mtl names 4HHB_ao.png, a 256 × 1 grey ramp from black (occluded) to white (open), as the diffuse map. Any renderer that draws textured OBJ shows the occlusion with no special support. The value is the cosine-weighted share of 256 viewpoints around the molecule that see the vertex: ao = (256·u − 0.5)/255 from the coordinate u.

  4. Open it

    three.js: MTLLoader and OBJLoader load the texture; turn on vertex colours to multiply the chain colours by the AO.

    JavaScript
    import { OBJLoader } from "three/addons/loaders/OBJLoader.js";
    import { MTLLoader } from "three/addons/loaders/MTLLoader.js";
    
    const materials = await new MTLLoader().loadAsync("out/4HHB_ao.mtl");
    materials.preload();
    const surface = await new OBJLoader().setMaterials(materials).loadAsync("out/4HHB_ao.obj");
    surface.traverse((o) => { if (o.isMesh) o.material.vertexColors = true; });
    scene.add(surface);

    Blender: File ▸ Import ▸ Wavefront (.obj) wires the ramp into Base Color; for colours × AO put a Mix node set to Multiply between the Color Attribute and the image texture, or import 4HHB_ao.ply and feed its Color Attribute to Base Color. MeshLab and ParaView: open the PLY.

  5. Scale it up

    aomesh's time and memory grow with the vertex count: GroEL–GroES at 0.5 Å has 2.2 million vertices and took 32 s and 3.1 GB. Cap the triangles first, and drop the cavities, which no outside viewpoint sees and which therefore come out black.

    Shell
    $ python3 ses_ao.py 1AON.cif.gz -o out --bake-colors \
        -- -s 0.5 --cavities remove --vertex-colors chain --max-triangles 1000000
    All options, more examples and the viewer notes: tools/ao/README.md. A surface you already have is baked as is: python3 ses_ao.py surface.obj --samples 1024.
05

Trajectories in Rust

Rust · 15 minutes · Trp-cage NMR ensemble (1L2Y)

  1. Create a project

    Shell
    $ cargo new ensemble && cd ensemble
    $ cargo add sesmesh
    $ curl -LO https://files.rcsb.org/download/1L2Y.cif.gz
    Cargo.toml
    [package]
    name = "ensemble"
    version = "0.1.0"
    edition = "2024"
    
    [dependencies]
    sesmesh = "1"
  2. Mesh every model

    One SurfaceEngine for all frames: parameters are validated once and per-thread buffers are reused. Each model is selected with ModelChoice::Index.

    src/main.rs
    use sesmesh::io::{ReadOptions, read_path};
    use sesmesh::radii::{RadiusOptions, assign};
    use sesmesh::structure::ModelChoice;
    use sesmesh::{Diagnostics, Selection, Sphere, SurfaceEngine, SurfaceParams};
    
    fn main() -> sesmesh::Result<()> {
        let path = std::env::args().nth(1).unwrap_or_else(|| "ensemble.pdb".into());
        let structure = read_path(&path, &ReadOptions::default())?;
        let mut engine = SurfaceEngine::new(SurfaceParams::ses(1.4).with_spacing(0.4))?;
    
        println!("model,atoms,area_A2,volume_A3,components");
        for index in 0..structure.models.len() {
            let mut selection = Selection::default();
            selection.model = ModelChoice::Index(index);
            let mut diags = Diagnostics::new();
            let atoms = structure.select(&selection, &mut diags)?;
            let radii = assign(&atoms, &RadiusOptions::default(), &mut diags)?;
            let out = engine.compute(&Sphere::from_atoms(&atoms, &radii)?)?;
            println!(
                "{},{},{:.2},{:.2},{}",
                index + 1,
                atoms.len(),
                out.stats.area,
                out.stats.volume,
                out.stats.components
            );
        }
        Ok(())
    }
  3. Run it

    Shell
    $ cargo run --release -- 1L2Y.cif.gz > areas.csv
    $ head -4 areas.csv
    model,atoms,area_A2,volume_A3,components
    1,154,1271.87,2064.42,1
    2,154,1332.64,2037.91,1
    3,154,1342.58,2045.66,1

    The Trp-cage NMR ensemble has 38 models; over the first five the SES area varies by about 8 %, the enclosed volume by 3 %.

  4. Go further

    Add Control for progress bars and cancellation (engine.compute_with), write meshes per frame with export::ply::write_ply_path, or query the exact field with SesField — see the library guide.