+++
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 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
    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.

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