Scalar fields, difference density, and isosurfaces

Density loading is opt-in. Standard FCF or observed-intensity/IAM maps use the green/red colours; explicitly configured or self-described custom coefficient columns are treated as deformation density and use light blue/orange. The periodic Fourier grid is retained when display or symmetry-growth settings change.

The options split into four groups by responsibility:

• differenceDensity — source-specific calculation settings (input mode, reflection reading, IAM, corrections, FFT grids).
• scalarField — the shared worker policy.
• isosurface — 3D mesh presentation (contour level, colours, resolution, progressive steps, symmetry reuse).
• contourLines — planar line sections.

Narrative documentation: General → Density concepts and Library → Density maps (which also covers custom coefficient columns and anomalous correction layouts in detail).

Option	Type	Default	Description
differenceDensity.autoLoad	Boolean	false	After installing the structure, automatically start density work from the loaded CIF.
differenceDensity.inputMode	String	"auto"	auto, fcf, or cif-iam. Auto prefers explicit Fourier coefficients and otherwise uses observed intensities plus IAM phases.
differenceDensity.reflections	Object	{}	Reflection-reader configuration; see the rows below.
differenceDensity.reflections.source	String	"auto"	auto, refln, diffrn_refln, or shelx_hkl_file.
differenceDensity.reflections.mergeFriedel	Boolean	automatic	Merges Friedel pairs for normal-scattering IAM maps; anomalous IAM defaults to keeping them separate.
differenceDensity.reflections.removeSystematicAbsences	Boolean	true	Removes absent unmerged reflections before symmetry merging.
differenceDensity.reflections.absenceTolerance	Number	1e-8	Complex general-position phase-sum tolerance used for absence detection.
differenceDensity.iam	Object	{}	Independent-atom structure-factor configuration; see the rows below.
differenceDensity.iam.includeAnomalous	Boolean	false	Includes f′ and f″ in IAM factors. Difference maps use normal scattering unless explicitly enabled.
differenceDensity.iam.wavelength	Number		Fallback wavelength in Å; a wavelength reported by the CIF takes precedence.
differenceDensity.iam.cromerMann	Object		Fallback nine-coefficient Cromer–Mann arrays keyed by atom type or element; complete CIF rows take precedence.
differenceDensity.iam.dispersionValues	Object		Fallback f′/f″ values keyed by atom type or element; site and type CIF values take precedence.
differenceDensity.iam.anomalous.table	String	automatic	Forces the internal Cu or Mo dispersion table.
differenceDensity.iam.anomalous.wavelengthTolerance	Number	0.005 Å	Controls automatic wavelength matching against the internal tables.
differenceDensity.intensityScale	Number|null	null	Explicit observed-to-IAM intensity scale; null fits a positive scale from the reflections.
differenceDensity.extinctionCorrection	String|Boolean|Number|Object	"auto"	Corrects observed amplitudes for a reported SHELXL isotropic EXTI model. Accepts auto, true/false, a coefficient, or a configuration object.
differenceDensity.extinctionCorrection.coefficient	Number		Overrides the CIF extinction coefficient when the option is an object.
differenceDensity.extinctionCorrection.wavelength	Number		Overrides the extinction-model wavelength when the option is an object.
differenceDensity.coefficientColumns	Object|null	null	Custom loop/index columns and either amplitude/phase or direct A/B columns. Any custom definition is displayed as deformation density.
differenceDensity.coefficientColumns.loop	String	"_refln"	Custom loop category name.
differenceDensity.coefficientColumns.h / .k / .l	String		Miller-index column names; default to the standard index columns of the loop.
differenceDensity.coefficientColumns.amplitudes / .phases	String or String[]		One or two amplitude columns with one common phase or matching split phases.
differenceDensity.coefficientColumns.a / .b	String or String[]		One or two direct real/imaginary crystallographic coefficient columns; use instead of amplitudes/phases.
differenceDensity.coefficientColumns.phaseUnit	String	"degrees"	degrees or radians.
differenceDensity.coefficientColumns.omitF000	Boolean	false	Omits the mean term. Custom/deformation coefficients retain it by default.
differenceDensity.anomalousDispersion	Boolean|Object	false	Optional anomalous-contribution correction and phase/Friedel detection.
differenceDensity.anomalousDispersion.target	String	source-dependent	first, second, both, or result. Custom coefficients default to first; FCF4 to both.
differenceDensity.anomalousDispersion.phaseDetection	Boolean	true	Enables exact inversion/Friedel phase tests. Set false for deliberate deformation coefficients.
differenceDensity.anomalousDispersion.phaseToleranceDegrees	Number	0.05°	Phase tolerance of the inversion/Friedel tests.
differenceDensity.anomalousDispersion.friedelAmplitudeToleranceRelative	Number	1e-4	Relative amplitude tolerance of the Friedel tests.
differenceDensity.anomalousDispersion.generator	String	"auto"	auto, olex, or shelxl; normally inferred from CIF metadata.
differenceDensity.anomalousDispersion.wavelength / .table / .wavelengthTolerance	Number / String / Number		Fallback wavelength, optional forced Cu/Mo table, and automatic table-matching tolerance (default 0.005 Å). The CIF wavelength wins.
differenceDensity.anomalousDispersion.values	Object		Fallback f′/f″ values keyed by atom type or element; site/type CIF values take precedence.
differenceDensity.reciprocalResolution	Number	1	Fraction of the available reciprocal resolution included in the Fourier map, in (0, 1].
differenceDensity.initialGridOversampling	Number	1	FFT-grid oversampling used for the first progressive display.
differenceDensity.gridOversampling	Number	2	Final real-space FFT-grid oversampling factor.
scalarField.useWorker	Boolean	true	Parse and calculate scalar fields in a Web Worker when available. Applies to reflection and Cube sources; in planar-line mode the worker also performs plane sampling and Marching Squares before transferring packed endpoints.
isosurface.useSymmetry	Boolean	true	Reuses meshes for exactly symmetry-equivalent disconnected regions; intersecting masks remain one field to avoid seams.
isosurface.progressiveSteps	Array	[0.5, 0.75, 1]	Ordered surface-resolution fractions emitted after the map is available; 1 is always included.
isosurface.visible	Boolean	true	Initial density-surface visibility. Changing only this option toggles the retained meshes without recalculation.
isosurface.sigmaLevel	Number	3	Positive and negative contour magnitude in map standard deviations.
isosurface.radius	Number	1.5	Cartesian clipping radius around displayed atoms, in Å.
isosurface.resolution	Number	64	Minimum marching-cubes resolution.
isosurface.gridSpacing	Number	0.15	Target Cartesian surface-grid spacing in Å used to increase resolution for larger displayed regions.
isosurface.maxResolution	Number	96	Upper bound for draw-size-dependent marching-cubes resolution.
isosurface.stitchTolerance	Number	0.0001	Cartesian tolerance used while welding reused surface patches.
isosurface.positiveColor	Color	"#267e47"	Positive standard difference-density colour.
isosurface.negativeColor	Color	"#992a3e"	Negative standard difference-density colour.
isosurface.deformationPositiveColor	Color	"#4FC3F7"	Positive custom/deformation-density colour.
isosurface.deformationNegativeColor	Color	"#FF9800"	Negative custom/deformation-density colour.
isosurface.opacity	Number	0.55	Surface opacity.
isosurface.wireframe	Boolean	true	Draws density surfaces as wireframes.
isosurface.maxPolyCount	Number	100000	Maximum marching-cubes polygon allocation per generated field.
contourLines.enabled	Boolean	false	Replaces the 3D isosurface with line-only contours on a plane. It creates no plane fill/background, preserving the viewer or widget background.
contourLines.plane	Object	{mode: "best-fit"}	Plane definition. Use {mode: "best-fit"}, {atoms: ["C1","C2","O1"]}, the string "best-fit", an atom-label array, or an explicit coordinateSystem/origin/normal definition (see below). Explicit atom lists require three non-collinear atoms; best-fit mode uses a stable crystallographic fallback for one- or two-atom structures.
contourLines.plane.coordinateSystem / .origin / .normal	String / Number[] / Number[]		Explicit cartesian (Å) or fractional plane. Origin and normal are three-value vectors; a fractional normal is transformed as a reciprocal/covector normal.
contourLines.plane.bounds	Object		Optional in-plane {u:[min,max], v:[min,max]} bounds in Å; otherwise automatic padding around all displayed atoms is used.
contourLines.padding	Number	1.5	Automatic in-plane padding around all displayed atoms, in Å.
contourLines.maxAtomDistance	Number|null	2.5	Discards samples farther than this distance from any displayed atom, in Å, keeping the drawn contours from spanning empty space. Null or a negative value keeps the unclipped padded rectangle.
contourLines.resolution	Number	256	Minimum samples per in-plane axis.
contourLines.gridSpacing	Number	0.04	Target Cartesian sample spacing in Å.
contourLines.maxResolution	Number	512	Per-axis sample cap.
contourLines.interpolation	String	"tricubic"	tricubic uses smooth slope-limited monotone sampling of the retained scalar grid without introducing local overshoot; linear uses its original trilinear sampler.
contourLines.contourCount	Number	20	Number of regularly spaced contour lines.
contourLines.contourStep	Number|null	null	Optional absolute contour step; takes precedence over contourCount.
contourLines.levelSubdivisions	Number	4	Line intervals fitted within the ordinary field/isosurface level. A 3σ field level starts at 0.75σ by default.
contourLines.levels	Number[]|null	null	Explicit positive contour magnitudes; takes precedence over count and step.
contourLines.sign	String|null	null	positive, negative, or both; null follows the scalar-field source metadata.
contourLines.zeroLine	Boolean	false	Draws an optional zero contour.
contourLines.zeroColor	Color	"#666666"	Colour of the zero contour.
contourLines.lineColor	Color|null	null	Overrides both signed line colours. Null inherits the standard/deformation positive and negative colours from isosurface.
contourLines.lineWidth	Number	1.5	Screen-space line width in pixels.
contourLines.haloColor	Color	"#ffffff"	Colour of the outline drawn behind each contour line for legibility over the structure.
contourLines.haloWidth	Number	1	Additional screen-space width in pixels on each side of a contour line for its halo outline. Zero or a negative value disables the halo.
contourLines.opacity	Number	1	Contour line opacity.
contourLines.depthOffset	Number	0.02	Offset along the plane normal in Å to reduce overlap artefacts.

Common per-source collection options

These accompany individual loads (loadDifferenceDensity, loadCube, addScalarField) and entries of loadScalarFieldSources; they are per-call options, not part of the defaults object above.

Option	Type	Description
fieldId	String	Stable collection identifier. Reusing it updates the existing entry instead of appending a duplicate. Default: generated.
fieldName	String	Human-readable source name exposed by collection metadata and events.
activate	Boolean	Whether to display the entry as it loads. Default: true for individual loads; last entry for loadScalarFieldSources.

loadCube options

Option	Type	Description
property	String	density, signed-density, orbital, potential, or generic. Controls unit conversion, label, default contour, and whether one or both signs are drawn. Default: "density".
level	Number	Absolute Cube contour level. Electron density defaults to 0.3 e/ų; signed density defaults to 0.05 e/ų; other properties default to three map standard deviations.
datasetIndex	Integer	Zero-based dataset/orbital selection for a multi-dataset Cube. Default: 0.
valueScale	Number	Explicit scalar-value multiplier. By default, Bohr-based density properties are converted from e/bohr³ to e/ų and other properties remain unscaled.
displayLabel, quantityName, valueUnit	String	Presentation metadata for generic, potential, and orbital fields. These values are emitted in density display events so the UI need not inspect the map.
periodic	Boolean	Controls cell wrapping. Default: true.
sign	String	positive, negative, or both surface signs. Default: property-dependent.