Molecule Viewer

A small C++/OpenGL hobby project for visualizing molecular structures. The current build displays atoms from a PDB file. Volumetric rendering from an OpenDX grid is experimental and may not render correctly. Molecule paths, window and camera settings, atom colors, rendering quality, and lighting can be configured in molecule-viewer/config/config.json.

Requirements

• Windows
• Visual Studio 2022 with the Desktop development with C++ workload
• A graphics card and driver supporting OpenGL 3.3 or later

The project uses the Visual Studio solution and includes its header dependencies under resources/include.

Build

1. Open molecule-viewer.sln in Visual Studio.
2. Select the Release configuration and x64 platform.
3. Build the solution.

Linux (x86_64)

Install g++, GLFW, and OpenGL development packages (for Debian or Ubuntu: g++ libglfw3-dev libgl1-mesa-dev). From the repository root, compile with:

g++ -std=c++17 -O2 -DNDEBUG -Iresources/include \
	molecule-viewer/main.cpp resources/src/glad.c \
	-lglfw -lGL -ldl -pthread -o molecule-viewer-linux

Run the executable from the molecule-viewer/ directory so the relative config/, models/, and shaders/ paths resolve:

cd molecule-viewer
../molecule-viewer-linux

The application loads shaders and model data using paths relative to its working directory. Run it from a directory containing the shaders/ and models/ folders described below.

Configuration

Settings are loaded from config/config.json at startup. Keep the config/ folder beside the executable in a Release package, and run the application with the extracted folder as its working directory. The checked-in example config is at molecule-viewer/config/config.json.

Edit the JSON file before starting the application; settings are not reloaded while it is running. Missing settings use built-in defaults, and invalid values cause the application to report a configuration error.

Section	Settings
molecule	Relative paths to the atom PDB and optional volume DX files
window	Window width, height, and vsync
camera	fovDegrees and positionOffset, which places the camera relative to the loaded molecule's center
rendering	Initial showAtoms and showVolume states, volume volumeStepSize and volumeMaxSteps, plus sphereSegments, sphereRings, and sphereRadius
atomStyles	Per-element RGB colors in the range 0 to 1; elements not listed use built-in colors
graphics	Background and lighting colors, directional-light direction, Blinn-Phong specularColor, specularStrength, and shininess, and msaaSamples

Increasing sphereSegments or sphereRings makes atom spheres smoother but increases geometry and rendering cost. sphereRadius scales the sphere mesh and therefore also affects the visible atom sizes. volumeStepSize and volumeMaxSteps trade volume quality against performance.

Run a Release

Download and extract the latest Release archive, then run molecule-viewer.exe from the extracted directory. The archive must retain this layout:

release/
	molecule-viewer.exe
	config/
		config.json
	models/
		2RT4.pdb
		volmap_7.dx
	shaders/
		model_frag.fs
		model_vert.vs
		volume_frag.fs
		volume_vert.vs

The PDB and DX model files are not included in the source repository; they are required at runtime and are distributed in the Release archive.

Linux releases use the same directory layout, with the executable named molecule-viewer instead of molecule-viewer.exe. Extract the Linux archive and run ./molecule-viewer from its top-level directory. The Linux binary dynamically links to GLFW and requires an OpenGL 3.3-capable driver.

Controls

Input	Action
W, A, S, D	Move the camera
Mouse	Look around
Mouse wheel	Adjust camera zoom
E	Toggle atom rendering
V	Toggle volumetric rendering (experimental)
R	Reload shaders
Esc	Exit

Model Data

The included structure is PDB entry 2RT4 (citation). The bundled volmap_7.dx is a volumetric grid for the same molecule.

To generate a volumetric map from PDB data, VMD can be used.

Pictures:

Atom colours:

Hydrogen - white

Carbon - grey

Nitrogen - blue

Oxygen - red

Fluorine - green

Phosphorous - orange

sulfur - yellow

(Colours might change in future updates)