Programming Conventions

Programming Conventions

This page summarizes the core coding standards, API patterns, and naming conventions used across ISETCam and related toolboxes (ISETBio, ISET3D). Following these conventions ensures that code is maintainable, self-documenting, and interoperable across the ISET ecosystem.

---

1. The Noun-Verb Method Architecture

ISETCam organizes functions using a nounVerb naming scheme. The first word identifies the object type (scene, oi, sensor, ip, display, camera, optics, pixel), and the second word specifies the operation.

% Discover all scene functions in the MATLAB Command Window:
scene<TAB>

The six primary verbs are:

• *Create: Instantiates a new structure with calibrated defaults or predefined configurations.

  scene  = sceneCreate('macbeth d65');
  oi     = oiCreate('diffraction');
  sensor = sensorCreate('bayer (rggb)');

• *Get: Queries object properties, spectra, physical dimensions, or calculated quantities.

  fov     = sceneGet(scene, 'fov');               % Field of view (deg)
  fnumber = oiGet(oi, 'optics fnumber');          % Optics f-number
  volts   = sensorGet(sensor, 'volts');           % Pixel voltage matrix

• *Set: Modifies object properties, geometry, illuminants, or parameters.

  scene  = sceneSet(scene, 'fov', 15);            % Set field of view to 15 degrees
  oi     = oiSet(oi, 'optics fnumber', 4.0);      % Set lens f-number
  sensor = sensorSet(sensor, 'auto exposure', 1); % Enable auto-exposure

• *Compute: Executes the mathematical or physical transformation between pipeline stages.

  oi     = oiCompute(oi, scene);                  % Scene radiance -> Optical irradiance
  sensor = sensorCompute(sensor, oi);             % Optical irradiance -> Sensor voltages
  ip     = ipCompute(ip, sensor);                 % Sensor voltages -> Processed RGB

• *Plot: Generates calibrated plots with accurate physical axes, labels, and color mappings.

  scenePlot(scene, 'illuminant photons');          % Plot spectral power distribution
  oiPlot(oi, 'illuminance mesh');                 % 3D mesh of retinal/sensor illuminance
  sensorPlot(sensor, 'pixel snr');                % Pixel SNR vs illuminance

• *Window: Opens or refreshes the interactive graphical user interface.

  sceneWindow(scene);
  oiWindow(oi);
  sensorWindow(sensor);

---

2. The Get/Set Philosophy & Data Encapsulation

Why are there more Gets than Sets?

In physical imaging systems, many parameters depend on one another. For example:

• A scene's spatial sample spacing ($m/\text{pixel}$) depends on its distance ($m$) and field of view ($\text{degrees}$).
• A sensor's conversion gain ($V / e^-$) depends on its voltage swing ($V$) and well capacity ($e^-$).

To prevent internal inconsistencies, ISETCam strictly regulates which parameters can be set directly. When you set fundamental parameters (such as distance and field of view), all dependent parameters are calculated on the fly during a *Get call.

Encapsulation Rule

% Recommended: Always use *Get and *Set
hFOV = sceneGet(scene, 'fov');
scene = sceneSet(scene, 'fov', 10);

% Strongly Discouraged: Do not access internal structure fields directly
hFOV = scene.wAngular;         % Fragile: internal representation may change!

Accessing internal structure fields directly bypasses validation, breaks unit conversions, and leaves dependent properties out of sync.

Parameter String Normalization

Accessor functions normalize parameter strings by converting them to lowercase and removing spaces and punctuation. Consequently, variations like 'fov', 'FOV', 'field of view', and 'fieldOfView' are equivalent:

fov1 = sceneGet(scene, 'fov');
fov2 = sceneGet(scene, 'field of view');
fov3 = sceneGet(scene, 'FieldOfView');
% fov1, fov2, and fov3 are identical

---

3. Namespaces & Function Prefixes

1. Object-Specific Functions: Functions operating on a specific structure begin with that object's name:
   • scene* — Scene spectral radiance
   • oi* — Optical image irradiance
   • optics* — Optical components and lens properties
   • sensor* — Image sensor array
   • pixel* — Individual photodetector properties
   • ip* — Image processing pipeline
   • display* — Output displays and calibration
   • camera* — Unified camera container
2. Toolbox Utilities (ie*): General utilities, file readers, color conversions, and session helpers are prefixed with ie (derived from Image Evaluation / ImageVal):
   • ieInit, ieSessionGet, ieAddObject, ieFigure, ieReadColorFilter, ieWebGet.
3. Legacy vc* Prefix: Early versions of ISETCam used vc (Virtual Camera). While most have been updated to ie or ip, some legacy aliases remain for backwards compatibility (e.g., vcNewGraphWin). New code should use ie equivalents.

---

4. Physical Units & Coordinate Systems

ISETCam performs all computations in calibrated physical units:

Radiometric & Photometric Units

• Spectral Radiance (Scene):
  • Quanta: $q / (s \cdot sr \cdot nm \cdot m^2)$ (photons per second per steradian per nanometer per square meter)
  • Energy: $W / (sr \cdot nm \cdot m^2)$
• Spectral Irradiance (Optical Image):
  • Quanta: $q / (s \cdot nm \cdot m^2)$
  • Energy: $W / (nm \cdot m^2)$
• Sensor Response:
  • Electrons accumulated ($e^-$)
  • Output voltages ($V$) after conversion gain and read/noise stages
  • Digital Numbers ($\text{DN}$) after quantization

Spatial Dimensions and Unit Specification

Internally, all spatial dimensions (focal length, pixel size, sensor dimensions, distance) are stored in SI meters. Accessor functions accept an optional unit string argument:

% Query sample spacing in different physical units
spacing_um = sceneGet(scene, 'sample spacing', 'um');  % Microns
spacing_mm = sceneGet(scene, 'sample spacing', 'mm');  % Millimeters
spacing_m  = sceneGet(scene, 'sample spacing', 'm');   % Meters

Coordinates: $(x, y)$ vs. $[row, col]$

• Plotting & Physical Space: Uses Cartesian coordinates $(x, y)$ in spatial units ($\mu m$ or $mm$), where $x$ is horizontal and $y$ is vertical.
• Matrix Data: Uses standard MATLAB matrix indexing $[row, col]$, where $row$ corresponds to vertical ($y$) and $col$ corresponds to horizontal ($x$).

---

5. Session Management & Preferences

At the beginning of tutorials, scripts, and analyses, initialize the workspace with ieInit:

ieInit;

ieInit closes existing ISET windows, refreshes the global session state, and optionally clears workspace variables based on user preferences:

% Check current ISET preferences
getpref('ISET')

% Clear workspace variables on ieInit
setpref('ISET', 'initclear', true);

% Preserve workspace variables on ieInit
setpref('ISET', 'initclear', false);

---

6. Function Documentation Standards

ISETCam functions include structured header documentation accessible via help or doc:

% FUNCTIONNAME - Short one-line description of purpose
%
% Syntax:
%   output = functionName(input1, input2, [param, value, ...])
%
% Description:
%   Detailed explanation of the algorithm, physical assumptions,
%   and intended use cases.
%
% Inputs:
%   input1 - Description of input parameter and expected type
%   input2 - Description of input parameter
%
% Optional key/value pairs:
%   'paramName' - Parameter description and default value
%
% Outputs:
%   output - Description of returned value or structure
%
% See also:
%   otherFunction, relatedTutorial

---

7. Testing & Quality Assurance

ISETCam incorporates an automated test suite:

• Unit Tests (ieUnitTest): Verify component functions and mathematical kernels.
• Tutorial Tests (ieTutorialTest): Ensure that all tutorials/t_*.m run to completion without errors.
• Example Tests (ieExampleTest): Validate applied examples/s_*.m scripts.
• Skipping Interactive Scripts: Scripts requiring user interaction or long execution use the % SkipFile marker.

See Testing for the contributor workflow and the ISETCam source repository's testing-workflow skill for current operational details.