The CLI
One binary, sesmesh. Give it structures, get meshes. This page
walks through the option groups with working examples; the
CLI manual
lists every option, and sesmesh surface --help prints them.
Install
With a Rust toolchain (1.89 or newer):
$ cargo install sesmesh-cliOr download a prebuilt binary for macOS arm64 or Linux x86-64 (up to 1.1.2 also Linux
arm64 and Windows x86-64) from the GitHub releases and check
it against SHA256SUMS. Each archive also holds the manual page and shell
completions; with cargo install, generate them:
$ sesmesh completions zsh > ~/.zfunc/_sesmesh # bash, zsh, fish, powershell, elvish
$ sesmesh man > ~/.local/share/man/man1/sesmesh.1First mesh
$ sesmesh 1crn.cif
sesmesh: 1crn.cif: 327 atoms (model 1), ses surface, probe 1.40 Å, grid 0.500 Å
sesmesh: 13812 vertices, 27616 triangles, 2 component(s) (1 cavity), area 2301.63 Ų, volume 4655.90 ų
sesmesh: wrote 1crn.obj in 0.02 sThe default is the SES with a 1.4 Å probe on a 0.5 Å grid, written as OBJ with
normals next to the input (1crn.obj). sesmesh 1crn.cif is short for
sesmesh surface 1crn.cif; the other commands are info (models,
chains, element counts, assemblies, radius coverage) and radii (print a radius
table).
Inputs & selection
PDB (fixed columns, hybrid-36), PDBx/mmCIF, XYZ / extended XYZ and PQR, optionally
gzip-compressed; the format comes from the file name, then the content
(--format overrides). By default the first model is used, waters and
hydrogens are dropped, and for alternate locations the highest-occupancy conformer is kept.
# chains A and B only, ligands removed
$ sesmesh 4hhb.cif.gz --chains A,B --no-hetatm
# model 3 of an NMR ensemble; frame 120 of an XYZ trajectory
$ sesmesh ensemble.pdb --model 3
$ sesmesh traj.xyz --frame 120
# the biological assembly instead of the deposited chains
$ sesmesh info 1k4r.cif.gz # lists assemblies and their copy counts
$ sesmesh 1k4r.cif.gz --assembly 1 -q draft # 60-copy capsid, 545 040 atoms| Option | Effect |
|---|---|
--model N / --frame I | Model number, or 0-based model position (trajectories) |
--block NAME | mmCIF data block |
--assembly ID | Expand a biological assembly (mmCIF pdbx_struct_*, PDB REMARK 350) |
--altloc highest|first|all|A | Alternate locations |
--hydrogens, --waters, --no-hetatm | Keep hydrogens, keep waters, drop hetero atoms |
--chains A,B + --chain-ids auth|label | Keep chains, by author or label IDs |
--exclude-resn SO4,GOL | Drop residues by name |
Surface & radii
Three surfaces from the same machinery: the SES (where a probe sphere cannot reach), the SAS (traced by the probe centre) and the vdW surface (union of the atom spheres).
$ sesmesh 1crn.cif --surface sas -o 1crn-sas.obj
$ sesmesh 1crn.cif --surface vdw -o 1crn-vdw.obj
$ sesmesh ligand.xyz --probe 1.2 --radii alvarez
$ sesmesh model.pqr # PQR radii are used as given
$ sesmesh 1crn.cif --radii file:my-radii.toml --strict-radiiRadius sets: bondi (default, with Mantina's extension), alvarez,
protor (united-atom protein radii), uniform:<r>, or rules from a
TOML file. Atoms a set does not cover get --unknown-radius (1.8 Å) and a
warning; --strict-radii makes that an error. sesmesh radii --set protor
prints a table.
Resolution
The grid spacing h sets the detail. Errors fall as h², triangle counts grow as 1/h². Mean errors below are measured on 53 PDB entries against each entry's h → 0 limit (validation report).
Preset -q | Spacing | Area error | Volume error | Triangles per Ų |
|---|---|---|---|---|
draft | 1.0 Å | −2.7 % | −0.34 % | 3 |
low | 0.7 Å | −1.5 % | −0.16 % | 6 |
medium (default) | 0.5 Å | −0.82 % | −0.08 % | 12 |
high | 0.25 Å | −0.20 % | −0.02 % | 48 |
ultra | 0.1 Å | ≈ −0.03 % (h² law) | — | 300 |
$ sesmesh 4hhb.cif.gz -q high # preset
$ sesmesh 4hhb.cif.gz -s 0.3 # any spacing in Å
$ sesmesh 4hhb.cif.gz --density 10 # ≈ 10 vertices per Ų, MSMS-like--refine linear interpolates vertices instead of solving them onto the
surface: faster, less exact.
Smoothing & decimation
--smooth N runs N rounds of Taubin smoothing for better-shaped triangles, then
projects every vertex back onto the exact surface. Decimation collapses edges by quadric
error; it only ever removes vertices, so the ones that stay keep their exact positions,
analytic normals and atoms, and the mesh stays closed and manifold.
# fine grid, then keep a quarter of the triangles
$ sesmesh 1aon.cif.gz -q high --decimate 0.25 -o groel.ply
# at most 200 000 triangles, never moving the surface by more than 0.05 Å
$ sesmesh 1aon.cif.gz -q high --max-triangles 200000 --decimate-error 0.05
# smoother triangles on a coarse grid
$ sesmesh 1crn.cif -q low --smooth 3Output
The format follows the -o extension: .obj (default),
.ply (binary PLY), .vert/.face (MSMS). A
.gz suffix compresses any of them; -o - writes to standard output.
$ sesmesh 4hhb.cif.gz -o hb.ply.gz --vertex-colors chain
$ sesmesh 4hhb.cif.gz -o hb.vert # writes hb.vert and hb.face
$ sesmesh 1crn.cif --vertex-colors element --palette atom-colors.json
$ sesmesh 1crn.cif --group-components --vertex-colors patch
$ sesmesh 1crn.cif --atom-areas areas.csv --vertex-data verts.csv --stats stats.json
$ sesmesh 1crn.cif --stats - -o /dev/null | jq .mesh # numbers only| Option | Effect |
|---|---|
--vertex-colors element|chain|patch|component | Per-vertex RGB (OBJ v x y z r g b, PLY uchar) |
--palette FILE | Element colours (JSON, atom-colors.json format) |
--group-components | OBJ groups component_N / cavity_N |
--no-normals, --face-normals | Omit normals, or area-weighted face normals instead of analytic ones |
--precision N | OBJ decimals (default 4) |
--atom-areas, --vertex-data | CSV: SES area per atom; nearest atom, patch, component per vertex |
--stats FILE|- | JSON: input, parameters, mesh, components, timings |
Layouts of every file: output formats.
Cavities
The exact SES includes closed internal cavities (negative signed volume). Keep them (default), remove them together with anything inside them (what MSMS reports), or keep only them to study packing defects and pockets.
$ sesmesh 1aon.cif.gz --cavities remove
$ sesmesh 1aon.cif.gz --cavities only --min-cavity-volume 10 -o pockets.obj
$ sesmesh 2ptn.pdb --min-component-area 5
$ sesmesh 4hhb.cif.gz -q high --drop-fragments # since 1.1--drop-fragments removes sub-grid fragments: tiny solid components without a
convex atom patch that the grid cuts off from re-entrant sheets thinner than the spacing
(4HHB at 0.25 Å: 32 components instead of 33). It is off by default, so default output
is unchanged.
Large structures
Memory grows with surface area. Before any mesh exists, sesmesh estimates the peak
memory of the whole run; --max-memory refuses inputs whose estimate exceeds the
limit, and --auto-coarsen coarsens the grid until it fits instead. The estimate
is deliberately conservative and is printed in the summary.
$ sesmesh 3j3q.cif.gz -q draft --progress --timings # 2.44 M atoms
$ sesmesh 3j3q.cif.gz -q high --max-memory 8G # exit code 4 if too big
$ sesmesh 3j3q.cif.gz -q high --max-memory 8G --auto-coarsen
$ sesmesh 4v6x.cif.gz -j 4 --simd scalar # threads, kernelCtrl-C stops a run within about 100 ms (exit code 130). -j sets the worker
threads; --simd forces a kernel (auto picks the best the CPU
supports).
GPU
A binary built with the feature hip (ROCm's hipcc at build time)
or cuda (CUDA's nvcc) runs the mesh stage on an AMD or NVIDIA GPU:
the device samples the field while the CPU threads mesh.
The default --refine exact writes the same files as the CPU;
--refine fast also refines the vertices on the GPU, in f32, for previews (same
triangles, vertices as close to the surface, last bits different).
$ cargo install sesmesh-cli --features hip # or cuda
$ sesmesh 1aon.cif.gz -q high --backend hip # same files as the CPU
$ sesmesh 1aon.cif.gz -q high --backend hip --refine fast # preview
$ sesmesh 1aon.cif.gz -q high --backend auto --timings # GPU if one works| Input | CPU, 16 Zen 5 cores | GPU exact | GPU fast |
|---|---|---|---|
| 4HHB, 0.25 Å | 0.24 s | 0.19 s | 0.12 s |
| 1AON, 0.5 Å | 1.38 s | 1.02 s | 0.56 s |
| 1AON, 0.25 Å | 3.40 s | 2.37 s | 1.41 s |
| 3J3Q, 1 Å (2.4 M atoms) | 28.9 s | 23.6 s | 12.3 s |
Complete runs on a Ryzen AI Max+ 395 with its integrated Radeon 8060S (SES, OBJ written;
on the 10-core M4's CPU the same runs take 0.38, 2.14, 5.62 and 47.6 s).
On a laptop GeForce RTX 2070 Max-Q, whose 6-core i7 bounds both modes, 1AON at 0.5 Å takes
5.48 s on the CPU, 3.04 s exact and 1.70 s fast with --backend cuda.
--backend hip and cuda fail if the GPU cannot be used;
--backend auto tries HIP, then CUDA, then falls back to the CPU. --gpu-device N picks a GPU; --timings names the
device used.
Batch mode
Several inputs write <stem>.<ext> into --output-dir;
side files go to directories of the same name.
$ sesmesh pdb/*.cif.gz --output-dir meshes --output-format ply \
--keep-going --stats stats --atom-areas areas-o is a usage error; use
--output-dir and --output-format instead. Missing directories are
created. Without --keep-going the batch stops at the first failure.Exit codes
| Code | Meaning |
|---|---|
| 0 | Success (also when a reader closes standard output early) |
| 1 | Runtime error: I/O, empty selection, invalid input data, batch failure |
| 2 | Usage error: unknown option, invalid value, conflicting options |
| 3 | Parse error: malformed file, unknown format, invalid palette |
| 4 | Resource limit: --max-memory, decompression or assembly size |
| 130 | Interrupted (Ctrl-C) |