Skip to content

Getting Started

Jump to bottom
Brian Wandell edited this page Aug 22, 2026 · 2 revisions

Getting Started with ISET3D

This page gets a new user from a fresh checkout to a first render in a few minutes, then points to where to go next. It stays short on purpose — the canonical, current setup instructions live in docs/setting-up-iset3d.md and docs/iset3d-introduction.md in the ISET3D repository; this page summarizes and links to them rather than duplicating their detail.

What You Need

  1. MATLAB, with the Image Processing, Signal Processing, and Parallel Computing toolboxes.
  2. ISETCam on your MATLAB path. ISETCam is a required dependency — ISET3D calls its scene/oi/sensor/ip utilities directly. Clone it with git clone http://github.com/ISET/isetcam.git. See the ISETCam wiki for details.
  3. Docker, installed and running: Docker Desktop on macOS/Windows, Docker Engine on Linux. Only the docker command-line client is needed — ISET3D drives it for you.

We have run ISET3D extensively on macOS and Linux. Windows works too, typically through the Windows Subsystem for Linux (WSL).

If your work is about human vision rather than cameras, ISETBio runs on top of ISETCam, and you can have ISETBio, ISETCam, and ISET3D on your path together.

Five-Minute Local Setup

The key thing to understand: MATLAB never renders anything itself. ISET3D writes a scene description (a recipe) out as PBRT files and asks PBRT, running inside a Docker container, to do the actual rendering. For a machine you control — your own laptop or desktop — that container runs locally. No Stanford VPN, account, or storage mount is required.

Pull the CPU rendering image:

docker pull digitalprodev/pbrt-v4-cpu

macOS note: always render with the CPU image. Docker Desktop on macOS cannot pass a GPU through to a container, so local GPU rendering isn't available on any Mac.

Then set the local Docker preferences in MATLAB:

setpref('ISETDocker','device','cpu');
setpref('ISETDocker','deviceID','');
setpref('ISETDocker','dockerImage','digitalprodev/pbrt-v4-cpu');
setpref('ISETDocker','remoteHost','');
setpref('ISETDocker','remoteUser','');
setpref('ISETDocker','renderContext','default');
setpref('ISETDocker','workDir',fullfile(piRootPath,'local'));

ieInit;
if ~piDockerExists
    piDockerConfig;
end
piDockerDiagnose('render',false);

piDockerDiagnose('render',false) checks that Docker is reachable and the preferences are well formed, without running a render. If it passes, you're ready to render.

For GPU setup on Linux or WSL2, and other machine-specific detail, see the full setting-up-iset3d.md guide.

Your First Render

Most scenes are downloaded on demand from the public Stanford Digital Repository, not stored in the GitHub repository. piRecipeDefault fetches and caches a scene the first time you ask for it, so this needs only an internet connection:

thisR = piRecipeDefault('scene name','chessset');
thisR.set('film resolution',[160 160]);
thisR.set('rays per pixel',32);
thisR.set('n bounces',2);
thisR.set('render type',{'radiance','depth'});

scene = piWRS(thisR,'render flag','hdr');
sceneWindow(scene);

piWRS writes the PBRT scene, renders it in the local container, and shows the result. Keep the film resolution and rays per pixel small while you're learning — the first CPU render should finish in well under a minute. If you see a chess-set image in the scene window, your local rendering setup works.

If the render fails before PBRT starts, go back to piDockerDiagnose('render',false) and confirm Docker is running and the image has been pulled.

Where To Go Next

Once the chess set renders, work through the first tutorial path in iset3d-introduction.md: five short scripts under tutorials/introduction/ covering the recipe object, the camera, lighting, materials, and textures. From there, the same guide links out to the asset, material, light, camera, and lens tutorial folders as you need them.

For the concepts behind the recipe — creating, editing, writing, and rendering it — see Recipe Workflow.

When You Outgrow Local Rendering

Local CPU rendering is enough for learning and for small scenes. Once you need a GPU, a much larger scene, or shared remote resources, move to Remote rendering — that's a later step, not a first one.

Optional Toolboxes

Another repository that is useful but not required, for lightfield work, is:

  • Lightfield Toolbox, written by Donald Dansereau, is used when organizing light-field data. We typically clone it into the external/ directory. Use Dansereau's repository rather than the fork on GitHub by Hazirbas.

Clone this wiki locally