ISETCam provides a computational framework for simulating how scenes, optical systems, sensors, image processors, and displays interact to create digital images. It serves as the foundational imaging layer for the broader ISET ecosystem:

• ISETBio extends ISETCam to model human vision, ocular optics, cone mosaics, eye movements, and retinal ganglion cells.
• ISET3D integrates physics-based 3D ray tracing (PBRT) to render complex 3D scenes into spectral radiance and irradiance distributions.

This overview describes how ISETCam code is structured, the primary data objects, and the patterns used to interact with them.

graph LR
    Scene[Scene<br/><i>Spectral Radiance</i>] -->|oiCompute| OI[Optical Image<br/><i>Spectral Irradiance</i>]
    OI -->|sensorCompute| Sensor[Sensor<br/><i>Electrons / Volts</i>]
    Sensor -->|ipCompute| IP[Image Processor<br/><i>Display RGB</i>]
    IP --> Display[Display<br/><i>Visual Output</i>]

ISETCam simulations are organized around five principal image systems structures, plus an integrated camera model:

1. Scene (scene): Represents the physical world as a spectral radiance distribution (photons or energy per second, steradian, nanometer, and square meter).
2. Optical Image (oi): Represents the retinal or sensor irradiance distribution after light passes through an optical system (lenses, apertures, diffusers).
3. Sensor (sensor): Simulates the photodetector array, color filter array (CFA), pixel geometry, charge accumulation, noise mechanisms (shot noise, read noise, DSNU, PRNU), and analog-to-digital conversion (ADC).
4. Image Processor (ip): Performs digital processing on raw sensor voltages, including demosaicking, color correction, illuminant estimation, and tone mapping.
5. Display (display): Models the spectral power distribution, subpixel layout, and gamma curves of output monitors or presentation devices.
6. Camera (camera): A convenience structure combining the optical image, sensor, and image processor into a single object for end-to-end calculations.

ISETCam was originally designed in 2003, before MATLAB introduced its modern object-oriented class system. To achieve modularity and data protection, ISETCam uses MATLAB structures managed by accessor and compute functions:

• Data fields inside each structure are managed by dedicated functions (*Get, *Set).
• Users interact with objects through public APIs rather than directly manipulating raw struct fields.
• This encapsulation ensures that dependent parameters (such as sample spacing, field of view, and pixel dimensions) remain synchronized and physically consistent.

Functions operating on ISETCam structures follow a consistent nounVerb naming convention:

Because functions use the nounVerb pattern (sceneCreate rather than createScene), typing scene<TAB> in the MATLAB Command Window immediately reveals all functions relevant to the scene object.

ISETCam provides two complementary modes of operation:

1. Interactive Exploration via Windows: Each main object has an associated GUI window (sceneWindow, oiWindow, sensorWindow, ipWindow). These windows allow users to inspect images, zoom in on pixel mosaics, measure regions of interest (ROIs), adjust display gamma, and run diagnostic plots from pulldown menus.
2. Programmatic Scripting: All GUI operations are thin wrappers around the core MATLAB API. Everything that can be done in the GUI can be automated in batch scripts, parallel loops, or optimization routines without displaying windows.

% A minimal programmatic simulation
scene  = sceneCreate('macbeth d65');    % Create scene
oi     = oiCreate('diffraction');       % Create diffraction-limited optics
oi     = oiCompute(oi, scene);          % Compute optical irradiance
sensor = sensorCreate('bayer (rggb)');  % Create Bayer sensor
sensor = sensorCompute(sensor, oi);     % Compute sensor voltage
ip     = ipCreate;                      % Create default image processor
ip     = ipCompute(ip, sensor);         % Compute processed image

To support both the interactive GUIs and programmatic scripting, ISETCam maintains an object database in the global environment:

• ieAddObject(obj): Adds a scene, optical image, sensor, or image processor to the global list.
• ieGetObject(objType): Retrieves the currently selected object of that type.
• ieReplaceObject(obj): Replaces an existing object in the database after modifying its parameters.
• Calling a window function with an argument, such as sceneWindow(scene);, adds the object to the database and displays it. Calling sceneWindow; without arguments displays the currently active scene.

At the beginning of scripts or tutorials, calling ieInit initializes the environment, closes open windows, and resets preferences.

ISETCam includes an automated testing framework to verify numerical accuracy, script runnability, and regression stability:

• Unit tests (ieUnitTest) in colocated _tests_ directories.
• Tutorial smoke tests (ieTutorialTest) executing tutorial scripts (tutorials/t_*.m).
• Example validations (ieExampleTest) verifying example scripts (examples/s_*.m).
• Test reporting (ieTestReport) summarizing results and execution times.

For a contributor-facing workflow, including focused runners, smoke-test selections, skipped scripts, and reports, see Testing. Detailed operational guidance remains in the ISETCam source repository's testing-workflow skill.

• Programming Conventions — Detailed style guide covering accessor methods, get/set philosophy, physical units, parameter normalization, and documentation standards.
• Programming Examples — Code walkthroughs based on core tutorials (t_introduction2ISET, t_sceneIntroduction, t_SystemSimulate) illustrating complete system simulations and published HTML reports.
• Testing — Focused and repository-wide checks for contributors.