repository·master·Indexed 20 days ago
https://github.com/nglviewer/nglA high-performance WebGL-based molecular visualization tool for web applications. NGL allows developers to render complex molecular structures, density volumes, and coordinate trajectories in a browser. It supports a wide range of formats including mmCIF, PDB, and MMTF, and provides a JavaScript API for programmatic control, as well as integrations for Python (NGLView) and R (NGLViewR).
NGL Viewer is a WebGL-powered molecular visualization application. Key capabilities include:
NGL supports a wide variety of representations to visualize molecular structures. These can be combined to create complex views.
spacefill: Atoms as space-filling spheres.ball+stick: Atoms as spheres and bonds as cylinders.licorice: A variant of ball+stick where aspectRatio is fixed to 1.0.cartoon: Smooth trace representing secondary structure.backbone: Cylinders connecting successive residues via main backbone atoms (.CA for proteins, .C4'/.C3' for RNA/DNA) and spheres for the atoms themselves.line: Simple lines for bonds.ribbon: A thin ribbon along the backbone.tube: Similar to cartoon but with aspectRatio fixed at 1.0.surface: Molecular surfaces (vws, sas, ms, ses, av).base: Simplified RNA/DNA nucleotide display (best used with cartoon).rope: A tube following local axes, useful for coarse-grained structures.point: Atoms as textured points.trace: A flat, unshaded line along the backbone.distance: Displays distances between atom pairs.label: Displays text labels near atoms.unitcell: Draws crystallographic unitcell edges and corners.validation: Draws clashes from wwPDB validation reports.The NGL viewer follows a hierarchical model:
Stage: The main entry point and container for the viewer. It manages the viewport and the lifecycle of loaded data.Component: Created via stage.loadFile(). A component contains the actual structural or volume data (e.g., a PDB structure).Representation: Added to a Component to define how the data is visually rendered (e.g., "cartoon", "surface", or "ball+stick").Example workflow:
Stage.Component (returned as a Promise).Representation to that component.component.autoView() to center the camera on the data.// create a `stage` object
var stage = new NGL.Stage("viewport");
// load a PDB structure and consume the returned `Promise`
stage.loadFile("rcsb://1CRN").then(function (component) {
// add a "cartoon" representation to the structure component
component.addRepresentation("cartoon");
// provide a "good" view of the structure
component.autoView();
});Structure class. You can navigate this hierarchy to access specific components of a molecular system.Topology files contain connectivity information but no coordinate data. Supported formats:
.prmtop, .parm7): Amber.psf): Charmm.top): GromacsTrajectory files can be loaded alongside structure files. If a structure file (mmCIF, PDB, GRO, SDF, MOL2, or MMTF) is loaded with the asTrajectory flag, it can be combined with these binary trajectory formats:
.dcd): Charmm.trr): Gromacs.nctraj, .ncdf, .nc): Amber.xtc): GromacsWhen releasing a new version, follow semantic versioning and ensure CHANGELOG.md is updated.
npm version [level] (e.g., patch, minor, major, prerelease) to update the version number and create a dist build. This also tags and pushes to GitHub.npm publishnpm publish --tag next (this prevents prereleases from being installed by default by users).README.md and CHANGELOG.md, and create a GitHub release containing the relevant changelog information.# Update version and tag (e.g., patch)
npm version patch
# Publish standard release
npm publish
# Publish prerelease
npm publish --tag nextFor high-performance or large-scale rendering (e.g., thousands of spheres), use the low-level Buffer approach. This involves creating a NGL.SphereBuffer object with typed arrays for positions, colors, and radii, then adding that buffer to an NGL.Shape object.
This method is more scalable than the convenience addSphere method because it uses contiguous memory via Float32Array to define many objects at once.
var shape = new NGL.Shape( "shape" );
var sphereBuffer = new NGL.SphereBuffer( {
position: new Float32Array( [ 0, 0, 0, 4, 0, 0 ] ),
color: new Float32Array( [ 1, 0, 0, 1, 1, 0 ] ),
radius: new Float32Array( [ 1, 1.2 ] )
} );
shape.addBuffer( sphereBuffer );
var shapeComp = stage.addComponentFromObject( shape );
shapeComp.addRepresentation( "buffer" );
shapeComp.autoView();SurfaceRepresentation allows you to show a triangulation of volume data at a specific isolevel or to directly display a surface mesh. This is useful for visualizing the boundary of a volume or rendering existing mesh geometries.The project uses npm for build management. You can generate different builds depending on your needs:
build/js/ngl.dev.js.dist/ngl.js.Ensure you have run npm install to install necessary dependencies before building.
# Install dependencies
npm install
# Build non-minified development version
npm run-script build
# Build minified distribution version
npm run-script build-min
# Watch for changes and rebuild automatically
npm run-script watch
# Build documentation
npm run-script docThe files in the examples/ directory must be served via a webserver to function correctly. You can use any of the following simple development servers:
python -m http.serverpython -m SimpleHTTPServerhttp-server (requires installation via npm)# Python 3
python -m http.server
# Python 2
python -m SimpleHTTPServer