​

Geometry extraction

​

0. TL;DR

• YES, PyMOL keeps a complete, CPU-resident, GL-free description of every representation’s geometry. It lives in two forms: (a) plain std::vector<float> triangle soup for surfaces (packages/engine/layer2/RepSurface.cpp:71-83), and (b) CGO buffers — a flat float* bytecode with a documented opcode set — for every other rep (packages/engine/layer1/CGO.h:82-270, packages/engine/layer1/CGO.h:765-773).
• NO, none of that is exposed to Python today for molecular reps. The only Python-visible geometry exports are cmd.get_vrml / get_collada / get_idtf / get_povray / get_mtl_obj / get_gltf (packages/engine/modules/pymol/exporting.py:1012-1019), and all six of them route through the ray tracer (packages/engine/layer1/SceneRay.cpp:336-491), not through the GL/CGO buffers. They are ASCII, per-primitive, camera-space, lossy, and multi-second. None is usable as an interactive feed.
• The exception is surfaces: cache_mode >= 2 already serializes the surface triangle mesh (N, V, VN, NT, T, S) into a Python tuple that lands in pymol._cache (packages/engine/layer2/RepSurface.cpp:3217-3229, packages/engine/layer2/RepSurface.cpp:4559-4574, packages/engine/modules/pymol/internal.py:101). That is a real, existing, zero-new-C++ path to a surface mesh — but Python lists of boxed floats, and no colors.
• The answer that shipped is a new CPython accessor that walks CoordSet::Rep[cRepCnt] (packages/engine/layer2/CoordSet.h:107), runs the existing CPU tessellators CGOSimplify() (packages/engine/layer1/CGO.cpp:4444) + CGOCombineBeginEnd() (packages/engine/layer1/CGO.cpp:1539), and hands back the resulting CGO_DRAW_ARRAYS float blocks as raw PyBytes using the primitive that already exists for pse_binary_dump: PConvFloatArrayToPyList(f, l, dump_binary=true) → PyBytes_FromStringAndSize (packages/engine/layer1/PConv.cpp:971-977). That block is literally a three.js BufferGeometry.
• Visual parity is achievable for the interactive (GL) viewport and NOT for ray tracing. See §8.

​

1. The two geometry pipelines inside PyMOL

​

Where the CPU copy is lost

​

The point in the pipeline where CPU geometry is complete

​

2. Per-Rep geometry inventory (what each Rep actually produces)

​

cRepSurface (2) — packages/engine/layer2/RepSurface.cpp:59-101

​

cRepSphere (1) — packages/engine/layer2/RepSphere.h:29-40

• mode 9 (default) → GLSL impostor quads, CGOOptimizeSpheresToVBONonIndexed (packages/engine/layer1/CGO.cpp:4357)
• mode 0 / cube / tetrahedron → real triangles via CGOSimplify(primitiveCGO, 0, sphere_quality) (packages/engine/layer2/RepSphereGenerate.cpp:36)
• modes 1,2,3,6,7,8 → point sprites, CGOConvertSpheresToPoints (packages/engine/layer2/RepSphereGenerate.cpp:75)

​

cRepCyl (0, sticks) — packages/engine/layer2/RepCylBond.cpp:39-49

​

cRepCartoon (5) — packages/engine/layer2/RepCartoon.cpp:65-92

​

cRepRibbon (6) — packages/engine/layer2/RepRibbon.cpp:37-50: primitiveCGO (:48), CPU.

​

cRepLine (7, wire) — packages/engine/layer2/RepWireBond.cpp:34-45: primitiveCGO (:43), CPU. CGO_LINE/CGO_SPLITLINE.

​

cRepNonbonded (11) — packages/engine/layer2/RepNonbonded.cpp:33-44: primitiveCGO (:41), CPU.

​

cRepNonbondedSphere (4) — packages/engine/layer2/RepNonbondedSphere.cpp:35-44: primitiveCGO (:43), CPU.

​

cRepEllipsoid (19) — packages/engine/layer2/RepEllipsoid.cpp:33-44: ray (:41) and std (:42) CGOs. CGO_ELLIPSOID → CGOSimpleEllipsoid in CGOSimplify (packages/engine/layer1/CGO.cpp:4535).

​

cRepMesh (8) — packages/engine/layer2/RepMesh.cpp:39-63: raw pymol::vla<float> V (:51), N strip lengths (:49), NTot (:50), VC colors (:52), Dot/NDot (:53-54). CPU, permanent.

​

cRepDot (9) — packages/engine/layer2/RepDot.h:26-45: V, VC, A (area), VN, T, F, Atom raw float/int arrays (:34-42). CPU, permanent.

​

cRepDash (10) — packages/engine/layer2/RepDistDash.cpp:40-55: raw float* V (:48), N (:49). CPU.

​

cRepAngle (17) — packages/engine/layer2/RepAngle.cpp:36-50: pymol::vla<float> V (:44). CPU.

​

cRepDihedral (18) — packages/engine/layer2/RepDihedral.cpp:35-48: float* V (:43). CPU.

​

cRepLabel (3) — packages/engine/layer2/RepLabel.cpp:90-104: labelV vector + lexer indices L (:98-99).

​

cRepDistLabel — packages/engine/layer2/RepDistLabel.cpp:41-56: same texture-quad story.

​

cRepCGO (13) — user CGOs. ObjectCGOState::origCGO (packages/engine/layer2/ObjectCGO.h:25) is CPU and

​

cRepCallback (14) — arbitrary Python glDraw* callbacks. Not extractable, by definition.

​

cRepVolume (20) / cRepSlice (16) — 3D-texture ray-marching (packages/engine/data/shaders/volume.fs),

​

cRepCell (12) / cRepExtent (15) — trivial line boxes.

​

3. CGO — the existing serialization format (this is the wire format, already)

​

CGO_DRAW_ARRAYS payload layout — the money shot

[ vertex   : 3 * nverts floats ]                     always (CGO_VERTEX_ARRAY 0x01)
[ normal   : 3 * nverts floats ]                     if CGO_NORMAL_ARRAY 0x02
[ color    : 4 * nverts floats ]  (rgb + alpha)      if CGO_COLOR_ARRAY 0x04
[ pickcolor: 3 * nverts floats ]  (1 rgba + 2 idx)   if CGO_PICK_COLOR_ARRAY 0x08
[ access   : 1 * nverts floats ]                     if CGO_ACCESSIBILITY_ARRAY 0x10

​

The two CPU tessellators (no GL required)

• CGOSimplify(const CGO*, est, sphere_quality, stick_round_nub) — packages/engine/layer1/CGO.cpp:4444. Converts every analytic primitive into triangles: CGO_SPHERE → CGOSimpleSphere (:4533) using G->Sphere->Sphere[sphere_quality]; CGO_SHADER_CYLINDER / CGO_CYLINDER / CGO_SAUSAGE / CGO_CUSTOM_CYLINDER / CGO_CUSTOM_CYLINDER_ALPHA → CGOSimpleCylinder (:4474-4530); CGO_CONE → CGOSimpleCone (:4511); CGO_ELLIPSOID → CGOSimpleEllipsoid (:4536); CGO_QUADRIC → CGOSimpleQuadric (:4539). It also folds BEGIN/…/END blocks into CGO_DRAW_ARRAYS (:4550-4620).
• CGOCombineBeginEnd(const CGO*, est, do_not_split_lines) — packages/engine/layer1/CGO.cpp:1539. BEGIN/VERTEX/END → CGO_DRAW_ARRAYS only (no primitive tessellation).

​

CGO ↔ Python already exists (for ObjectCGO only)

• CGOAsPyList(CGO*) (packages/engine/layer1/CGO.cpp:289-297) → [len, flat_float_list], built by CGOArrayAsPyList (packages/engine/layer1/CGO.cpp:241-287). It explicitly handles CGO_DRAW_ARRAYS (:255-265), flattening {mode, arraybits, narrays, nverts} + the data block. So the serializer for the exact format we want already exists in the tree.
• CGONewFromPyList() (packages/engine/layer1/CGO.cpp:392) is the inverse.
• Reached from Python only via session save of ObjectCGO (packages/engine/layer2/ObjectCGO.cpp:43, 151, packages/engine/layer3/Executive.cpp:5407), GadgetSet (packages/engine/layer2/GadgetSet.cpp:191, 197), and CoordSet::SculptCGO (packages/engine/layer2/CoordSet.cpp:392-394).
• Import side: cmd.load_cgo(list_of_floats, name, state) (packages/engine/modules/pymol/importing.py:307-324) → ObjectCGOFromFloatArray (packages/engine/layer2/ObjectCGO.h:47) / CGOFromFloatArray (packages/engine/layer1/CGO.h:1109).

​

Binary blob primitive already exists

​

4. Complete inventory of existing Python-exposed export paths

1. SceneUpdate(G, false) (:152) — rebuild all reps if dirty,
2. allocates a fresh CRay (:213) and re-runs obj->render(&info) for every object with info.ray set (:284-323), re-emitting every primitive from scratch,
3. RayExpandPrimitives() (packages/engine/layer1/Ray.cpp:561) — allocates vertex/normal/radius VLAs sized to the full primitive count,
4. RayTransformFirst() (packages/engine/layer1/Ray.cpp:822) — transforms all vertices by ModelView (skipped only when geometry_export_mode == 1, packages/engine/layer1/Ray.cpp:876-881),
5. sprintf everything into a char* VLA,
6. RayFree(ray) (:492) — throws the whole thing away.

​

5. Which existing path is closest to usable, and what it costs

​

5a. Winner for surfaces (today, no C++ changes): the surface cache

(N, V, VN, NT, T, S)   # V,VN: flat lists of floats; T,S: flat lists of ints

import pymol
for entry in pymol._pymol._cache:
    N, V, VN, NT, T, S = entry[3]

​

5b. Winner for everything else (today): cmd.get_vrml(2)

​

5c. Per-frame cost verdict

​

6. The new C++/Python accessor

​

6a. Design

ExecutiveFindObject<ObjectMolecule>(G, name)   packages/engine/layer3/Executive.h:338-343
  → ObjectMolecule::CSet[state]                (CoordSet*)
    → cs->Rep[cRepSurface] / cs->Active[...]   packages/engine/layer2/CoordSet.h:107-108

​

6b. Return payload

{
  "object": "1ubq", "state": 0, "rep": 2,             # cRepSurface
  "kind": "indexed-mesh",
  "counts": {"verts": 512331, "tris": 1023114},
  "position":  <bytes>,   # float32 x 3N   memcpy from RepSurface::V
  "normal":    <bytes>,   # float32 x 3N   memcpy from RepSurface::VN
  "color":     <bytes>,   # float32 x 3N   memcpy from RepSurface::VC
  "alpha":     <bytes>,   # float32 x  N   memcpy from RepSurface::VA
  "ao":        <bytes>,   # float32 x  N   memcpy from RepSurface::VAO
  "index":     <bytes>,   # int32   x 3NT  memcpy from RepSurface::T
  "atom":      <bytes>,   # int32   x  N   memcpy from RepSurface::AT
  "vis":       <bytes>,   # int32   x  N   memcpy from RepSurface::Vis
  "proximity": True,                        # RepSurface::proximity
  "one_color": None,
}

{
  "object": "1ubq", "state": 0, "rep": 5,             # cRepCartoon
  "kind": "cgo-draw-arrays",
  "blocks": [
     {"mode": 5,                                       # GL_TRIANGLE_STRIP
      "arraybits": 0x0F, "nverts": 41230,
      "data": <bytes>},                                # the raw cgo::draw::arrays heap block
     ...
  ],
  "spheres":   <bytes>,   # float32 x 8N: cx,cy,cz,r,rr,gg,bb,aa
  "cylinders": <bytes>,   # float32 x N*M for CGO_SHADER_CYLINDER(+2nd color)
}

​

6c. Implementation, entirely from existing functions

// pseudo-code, all callees verified to exist
CGO* src = /* rep-specific: primitiveCGO | preshader | ray | std | shaderCGO-source */;

// 1. tessellate analytic primitives on the CPU (no GL)
CGO* simple = CGOSimplify(src, 0, sphere_quality, stick_round_nub);   // packages/engine/layer1/CGO.cpp:4444
// 2. fold BEGIN/END into interleaved arrays (idempotent if already folded)
if (simple->has_begin_end) CGOCombineBeginEnd(&simple);              // packages/engine/layer1/CGO.cpp:1539

// 3. walk with the public iterator and emit PyBytes per CGO_DRAW_ARRAYS
for (auto it = simple->begin(); !it.is_stop(); ++it) {               // packages/engine/layer1/CGO.h:800-830
  if (it.op_code() == CGO_DRAW_ARRAYS) {
    auto* sp = it.cast<cgo::draw::arrays>();                         // packages/engine/layer1/CGO.h:338
    PyObject* blob = PConvFloatArrayToPyList(                        // packages/engine/layer1/PConv.cpp:971
        sp->get_data(), sp->get_data_length(), /*dump_binary=*/true);
    // + sp->mode, sp->arraybits, sp->nverts
  }
}

​

6d. Bulk / streaming variant

​

6e. Invalidation events

​

6f. What it cost

• Surface accessor: memcpy of 8 existing vectors.
• CGO accessor: CGOSimplify + iterate + PyBytes, a variant of the existing CGOArrayAsPyList (packages/engine/layer1/CGO.cpp:241-287).
• Invalidation: no callback was added. Rep::update() runs on worker threads when async_builds is on (packages/engine/layer1/Scene.cpp:4740-4757), so a callback would have had to avoid touching Python from a non-GIL thread. Instead the four change counters of _cmd.web_get_versions are polled — see docs/cmd-api-rpc.md §8.5 and packages/bridge/tenmol_bridge/state/repversions.py.

​

7. Shader parity assets already in the repo

​

8. Verdict

​

Where it will definitively NOT match

1. Ray tracing (cmd.ray) — irreproducible in three.js. RayRender (packages/engine/layer1/Ray.cpp, 7827 lines) is a CPU ray tracer with real shadows, multi-light specular, interior colors, and ray_trace_mode cel-shading/outlines (packages/engine/layer1/Ray.cpp:5570-5607, 6472-6474). ray_trace_mode exists only in the ray tracer — grep of packages/engine/layer1/SceneRay.cpp and packages/engine/layer1/SceneRender.cpp found zero references to it in the GL path. There is no path to parity here. The web client must call cmd.ray() + cmd.png() server-side and display the resulting bitmap. This is a mode switch, not a rendering feature — and the UX must make that explicit.
2. Order-independent transparency (transparency_mode 3). PyMOL binds an OIT accumulation framebuffer with multiple draw buffers and a dedicated oit shader (packages/engine/layer1/SceneRender.cpp:939-995, packages/engine/data/shaders/oit.vs/.fs, packages/engine/layer0/PostProcess.cpp:60, 86, TM3_IS_ONEBUF handling at packages/engine/layer1/SceneRender.cpp:979, 1101, 1466). WebGL2 has no GL_EXT_draw_buffers-style MRT parity issues but does lack per-sample control PyMOL relies on; an approximate WBOIT is achievable but will not be pixel-identical.
3. CPU depth-sorted alpha triangles (transparency_mode != 3). The other transparency path sorts triangles on the CPU per frame: CGOOptimizeToVBOIndexedWithColorEmbedTransparentInfo embeds z_value, ix, and sort_mem arrays into the CGO (packages/engine/layer1/CGO.cpp:3395-3405), and RepSurface::render allocates t_buf/z_value/ix sized NT and re-sorts every frame (packages/engine/layer2/RepSurface.cpp:1969-1984). Reproducing this in JS means per-frame triangle sorting of up to 10^6 triangles in the browser — that will not hold 60 fps. Either accept sort artifacts or ship the sorted index buffer from Python each frame (which reintroduces per-frame cost).
4. Stereo. PyMOL implements 9 stereo modes: quadbuffer, crosseye, walleye, geowall, sidebyside, stencil-by-row/column/checkerboard/custom, anaglyph, openvr (packages/engine/layer1/SceneRay.cpp:154-175, 515-713). Quad-buffer stereo and stencil-parity stereo are impossible in a browser. Anaglyph and side-by-side are reproducible. OpenVR is out.
5. Post-process antialiasing. antialias_shader selects FXAA (1 stage) or SMAA (3 stages) (packages/engine/layer1/SceneRender.cpp:613-627, 1791). Reproducible with effort, but PyMOL’s exact SMAA parameters must be ported or edges will differ visibly at high zoom.
6. Labels. cRepLabel is texture-atlas quads driven by CGO_DRAW_LABEL / CGO_DRAW_LABELS (packages/engine/layer1/CGO.h:224-228) and a texture-size heuristic (InvalidateShaderCGOIfTextureNeedsUpdate, packages/engine/layer2/RepLabel.cpp:117, MAX_LABEL_TEXTURE_SIZE 256, :114). Glyphs are CPU-reachable (packages/engine/layer1/Character.cpp:122) but the atlas must be rebuilt client-side. Font rasterization will differ from PyMOL’s FreeType output at the pixel level. Expect near-miss, not match.
7. cRepCallback (14). Objects created by cmd.load_callback execute arbitrary Python that issues raw OpenGL. packages/engine/layer2/ObjectCallback.cpp exists for exactly this. There is no geometry to extract — by construction. Any plugin using it is unsupported in the web client.
8. cRepVolume (20) and cRepSlice (16). 3D-texture ray marching (packages/engine/data/shaders/volume.fs, 47 lines). Not mesh geometry. Requires a separate 3D-texture upload path (cmd.get_volume_field exists, packages/engine/layer4/Cmd.cpp:6510, packages/engine/layer4/Cmd.cpp:727 → FieldAsNumPyArray) and a hand-ported volume shader. Treat as a separate epic.
9. Ambient occlusion. VAO per-vertex occlusion is computed on the surface (packages/engine/layer2/RepSurface.cpp:2780-2800) and shipped as a vertex attribute — that part transfers fine. But ambient_occlusion_mode also has a smoothing pass with its own map (ambient_occlusion_map, packages/engine/layer2/RepSurface.cpp:2368) whose result is baked into VAO, so as long as the client reads VAO after rebuild, this one actually matches.
10. Grid mode. GridMode::ByObject / ByObjectStates / ByObjectByState (packages/engine/layer1/SceneRay.cpp:179-211, 306-320) splits the viewport into N sub-viewports with adjusted aspect ratios. Reproducible with N three.js viewports, but the layout math (GridUpdate, grid.asp_adjust) must be ported exactly or panels will misalign.
11. Precision. All PyMOL geometry is float32 and all colors are float32 RGB in [0,1] (CLIP_COLOR_VALUE / CONVERT_COLOR_VALUE, packages/engine/layer1/CGO.h:54-55). Optional byte-packed normals/colors are gated on cgo_shader_ub_color / cgo_shader_ub_normal (packages/engine/layer1/CGO.cpp:2939-2961, CLIP_NORMAL_VALUE at packages/engine/layer1/CGO.h:58-61). If the accessor emits float32 and the client uses float32, this is exact.
12. Picking. PyMOL picks by rendering a pick-color buffer (CGORenderPicking, packages/engine/layer2/RepSphere.cpp:120, packages/engine/layer1/ScenePicking.cpp). The CGO_PICK_COLOR payload (atom index, bond index, packages/engine/layer1/CGO.h:141-142) is in the extracted arrays, so client-side GPU picking is achievable — but the encoding (Picking.h, cPickableAtom = -1 … cPickableThrough = -5, packages/engine/modules/pymol/cgo.py:73-77) must be replicated bit-for-bit or selections will land on the wrong atoms.

​

9. Questions this map left open, and how they were closed

• No Python hook fires on Rep rebuild/invalidation. Confirmed by grep over packages/engine/layer1/P.cpp, packages/engine/layer4/Cmd.cpp and packages/engine/modules/pymol/*.py. None was added; §6f explains what replaced it.
• Is RepSurface::AT populated in all surface modes, or only with pick_surface? AT is declared at packages/engine/layer2/RepSurface.cpp:83; not every write site was traced here. docs/spikes/picking.md answered the practical question instead — surface picking runs on the backend against a real GL pick pass (15/15 clicks resolved), so client-side reliance on AT never became load-bearing.
• The byte layout of the pick-color sub-block inside CGO_DRAW_ARRAYS (VERTEX_PICKCOLOR_RGBA_SIZE = 1 float holding 4 packed bytes, plus 2 index floats, packages/engine/layer1/CGO.cpp:60-63). The offset arithmetic at packages/engine/layer1/CGO.cpp:1665 (pickColorVals = nxtVals + VERTEX_PICKCOLOR_RGBA_SIZE * nverts) implies the RGBA sub-array precedes the index sub-array in the same block. Verified at runtime by docs/spikes/geometry-accessor.md, which is what packages/bridge/tenmol_bridge/render/modeg.py::_deinterleave_i32 depends on.
• _PYMOL_NO_RAY guards SceneRay entirely (packages/engine/layer1/SceneRay.cpp:94-96). No setup.py flag sets it, so ray export is compiled in for this fork’s builds.
• Whether pymol._cache surface entries survive cmd.delete/rebuild cycles cleanly enough to be a reliable feed — _cache_purge (packages/engine/modules/pymol/internal.py:49-78) evicts by size and access time. Moot: §6’s accessor reads Rep[] directly rather than the cache.