+++
title = "3D sample view"
weight = 35
+++

# 3D sample view

`ba.showSample3D` opens an interactive VTK window that 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.

The 3D viewer is optional and requires `vtk` (`pip install vtk`).

### Basic usage

```python
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:

```python
ba.showSample3D(
    sample=sample,             # required argument
    sample_size=120*nm,        # required argument
    seed=0,                    # optional argument
    window_size=[1330, 1075],  # optional argument
    background="white",        # optional argument
    zoom=1.2,                  # optional argument
    beams=True,                # optional argument
    roughness=True,            # optional argument
    roughness_resolution=256,  # optional argument
    blocking=False,            # optional argument; alias: block
)
```

`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`:

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

### 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:

```python
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.
- `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.
- `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.
