Getting Started

Getting Started with ISETCam

ISETCam models a camera in physical units, from scene radiance through optics, sensor capture, image processing, and display. This page guides you from downloading the software to running your first complete camera simulation.

What you need

• MATLAB: A current desktop installation of MATLAB. ISETCam's interactive App Designer windows (sceneWindow, oiWindow, sensorWindow, ipWindow) require MATLAB R2020b or later; the instructions on this page were verified in MATLAB R2025b.
• MathWorks Toolboxes:
  • Image Processing Toolbox (used frequently for core filtering, interpolation, and color space conversions)
  • Signal Processing Toolbox (used frequently for signal and frequency analyses)
  • Statistics and Machine Learning Toolbox and Deep Learning Toolbox (used occasionally by specialized scripts and machine learning tutorials)

For core ISETCam, you do not need ISET3D, ISETBio, Docker, or external validation repositories.

Download and install

There are three convenient ways to obtain ISETCam from its GitHub repository at https://github.com/ISET/isetcam:

1. Git command line (recommended): Clone the repository to your local machine. This makes it easy to stay up-to-date with git pull:

   git clone https://github.com/ISET/isetcam.git

2. GitHub Desktop: Use the GitHub Desktop application to clone and manage the repository visually.

3. ZIP archive: Download the repository archive from the green Code -> Download ZIP button on the GitHub page and extract it to a local folder.

Add to MATLAB path and initialize

Start MATLAB and add the ISETCam directory and its subdirectories to your MATLAB path for the current session. Replace the example path below with your actual checkout location:

isetcamRoot = fullfile(getenv('HOME'), 'Documents', 'MATLAB', 'isetcam');
addpath(genpath(isetcamRoot));
which ieInit
ieInit

• which ieInit should confirm a path inside your ISETCam installation.
• ieInit initializes the ISETCam environment, sets default preferences, and closes any windows open from previous sessions.

Check the installation

Run a quick tutorial check using the built-in tutorial test runner:

run = ieTutorialTest('selection', 't_oiIntroduction');
ieTestReport(run, 'List', 'all');

This verifies that the optical image tutorial runs without errors and displays the test summary. You can also view the tutorial source directly in t_oiIntroduction.m.

Run a first camera calculation

This compact 5-line script creates a default test scene, computes the optical image formed by diffraction-limited optics, simulates capture by an image sensor array, processes the sensor data into an sRGB image, and displays the result:

ieInit

scene  = sceneCreate;
oi     = oiCompute(oiCreate, scene);
sensor = sensorCompute(sensorCreate, oi);
ip     = ipCompute(ipCreate, sensor);

ipWindow(ip);

What happened in each step:

1. sceneCreate constructs a default Macbeth ColorChecker scene with calibrated spectral radiance.
2. oiCompute(oiCreate, scene) computes the optical image irradiance arriving at the focal plane after passing through diffraction-limited optics.
3. sensorCompute(sensorCreate, oi) simulates photon capture, color filter array (CFA) sampling, pixel electron conversion, and noise on a sensor mosaic.
4. ipCompute(ipCreate, sensor) demosaics the sensor voltages, balances color, and applies sensor-to-display transforms.
5. ipWindow(ip) opens the interactive App Designer Image Processing window to examine the rendered image, color values, and line profiles.

For a tutorial on using the combined camera object (cameraCreate, cameraCompute), see t_cameraIntroduction.m.

Where to go next

• Tutorials and Examples: Explore the Tutorials index to learn core operations step-by-step, or the Examples index for longer, adaptable workflows.
• Core Pipeline: Understand the physics and calculations at each stage in the Core Pipeline overview: scene radiance, optics and optical images, sensors, image processing, and displays.
• Spectral Scene Data: Learn how to download and use multispectral, hyperspectral, and HDR scene datasets with ieWebGet in Spectral Scene Data.
• Foundations of Image Systems Engineering (FISE): Read the online textbook FISE by Brian Wandell and Joyce Farrell for the underlying physics, color science, and camera engineering concepts.

Extend the system

• ISET3D: Simulates complex 3D scenes, computer graphics assets, and physically based ray tracing (PBRT).
• ISETBio: Models human optics, cone mosaic sampling, retinal eye movements, photopigment kinetics, and retinal ganglion cell computations.

Both ISET3D and ISETBio require ISETCam on the MATLAB path. ISETCam itself is completely self-contained and does not require either extension.