BornAgain ≻ git-develop ≻ Documentation ≻ Reference ≻ 3D sample view

3D sample view

ba.showSample3D renders the sample geometry: layers with optional rough interfaces, lattice and disordered particle layouts, mesocrystals, and Mixture realizations. The bottom-left orientation marker shows the x, y, and z axes. The view also shows schematic incident and reflected beam arrows by default.

Basic usage

import bornagain as ba
from bornagain import nm

sample = ...  # construct a ba.Sample

ba.showSample3D(
    sample,      # required argument
    120*nm,      # required argument
    seed=0,      # optional argument
)

A full call can name every argument:

ba.showSample3D(
    sample=sample,             # required argument
    sample_size=120*nm,        # required argument
    seed=0,                    # optional argument
    filename=None,             # optional direct image export
    window_size=[1330, 1075],  # optional argument
    background="white",        # optional argument
    zoom=1.2,                  # optional argument
    azimuth=45,                # optional argument, degrees
    elevation=30,              # optional argument, degrees
    beams=True,                # optional argument
    roughness=True,            # optional argument
    roughness_resolution=256,  # optional argument
    blocking=False,            # optional argument; alias: block
)

Pass filename to render directly to an image without opening an interactive window. The call returns the path actually written and is suitable for scripts that generate documentation or other reproducible artifacts:

ba.showSample3D(
    sample,
    sample_size=120*nm,
    seed=0,
    filename="sample.png",
)

sample_size is the side length, in nm, of the visible square patch. Layout instances outside this patch are omitted, and particle geometry crossing the boundary is clipped for display.

The beam arrows are only visual orientation aids. They are not derived from a simulation instrument and do not affect camera framing. To hide them, pass beams=False:

ba.showSample3D(sample, sample_size=120*nm, beams=False)

Save views to files

Pass filename to render one view offscreen and write it before the call returns. azimuth and elevation are given in degrees:

ba.showSample3D(
    sample,
    sample_size=120*nm,
    filename="sample.png",
    azimuth=30,
    elevation=30,
)

The filename must end with .png, .jpg, .jpeg, .tif, .tiff, or .bmp.

No interactive window or viewer process remains open. To save several camera views, make one explicit call per filename:

ba.showSample3D(
    sample, sample_size=120*nm,
    filename="sample-front.png", azimuth=0, elevation=20)
ba.showSample3D(
    sample, sample_size=120*nm,
    filename="sample-side.png", azimuth=90, elevation=20)

The same azimuth, elevation, zoom, window_size, and other view options also configure interactive rendering.

Reproducibility and randomness

seed controls only the viewer-side realization of disordered layouts (Dilute2D, Dense2D, paracrystals) and Mixture choices. It does not affect scattering calculations. Fixing it gives a stable picture across runs. For a fresh layout every call, draw a random 32-bit seed:

import random
ba.showSample3D(sample, sample_size=120*nm, seed=random.randrange(2**32))

Keyword arguments

  • window_size (list, default [1330, 1075]): render-window [width, height] in pixels.
  • background (str, default "white"): background color name.
  • zoom (float, default 1.2): initial camera zoom; must be positive.
  • azimuth (float, default 45): camera azimuth in degrees.
  • elevation (float, default 30): camera elevation in degrees.
  • beams (bool, default True): show schematic incident and reflected beam arrows.
  • roughness (bool, default True): render rough interfaces.
  • roughness_resolution (int, default 256): points along each roughness-map axis. 0 disables rough maps. Values above 2048 are clamped with a warning.
  • filename (path-like, default None): write the view synchronously instead of opening an interactive window.
  • blocking (bool, default False; alias block): with the default, start a separate viewer process and return its process handle. If true, run the VTK event loop in the current process before returning.
  • filename (path-like, default None): render offscreen and write the image synchronously instead of opening a viewer.