Programming

• This page summarizes ISETcam programming conventions; these are also followed in the related projects (ISETbio, ISETlens, ISET3d,ISETcloud). Writing scripts that adhere to these conventions makes the code and analyses much easier to understand.
• Our work flow treats ISETcam as a library (toolbox). Specific projects rely on ISETcam functions. During the course of these projects we sometimes make changes to ISETcam itself.

---

Data and function organization

ISETcam is designed around a few Matlab structures that represent important data within the image acquisition pipeline: the scene, optical image, sensor, image processor and display. The ISETcam programming style uses

• create to initiate the main structures (e.g., sensorCreate)
• set/get to read and edit structure properties (e.g., sensorGet)
• compute to combine the structure with other parts of the pipeline (e.g. sensorCompute)
• plot to visualize parameters (e.g., sensorPlot)
• window functions to bring up a graphical user interface (e.g. sensorWindow)

Function browser

This link browses through the ISETcam functions

Names and documentation

• Function names: nounVerb, say sceneCreate. That way scene produces all the functions that are relevant to the scene object. The other way, createScene, would mean we find all the create functions. Less desirable.
• Name space: most utilities are prepended by ie<>, which has its roots in image evaluation (imageval). There are some functions that prepend 'vc'; which arises from an even earlier time when the project was called 'virtual camera'.
• Documentation: we are evolving towards the function documentation standards in isetbio. At present doc functionName generates useful help.
• Validation: we aim for a validation function to test each basic feature. We execute ieRunValidateAll before a git push. We are aiming to automate continuous integration.

Data management

We often create multiple versions of a structure, say two types of sensors, so that we can compare them. We maintain a very simple database in the global environment where you can store these objects. You can add, get, or replace an object in the data base using the ieAddObject(), ieGetObject, ieReplaceObject functions.

Visualization

There is a graphical user interface for visualizing the key structures. We find these GUIs to be particularly helpful for debugging. A quick look at a structure in the GUI can reveal many important details.

This simple example illustrates how the code feels

scene = sceneCreate('macbeth');    % Create a scene spectral radiance
scene = sceneSet(scene,'fov',1);   % Give it a small field of view
oi    = oiCreate('diffraction');   % Create some diffraction limited optics
oi    = oiCompute(oi,scene);       % Compute the spectral irradiance
ieAddObject(scene); sceneWindow;   % Add the scene and oi to the data management system
ieAddObject(oi); oiWindow;         % and visualize

In this case the scene is very small (1 deg fov), so the sharp scene spectral radiance (left) is blurred by the lens into an optical image spectral irradiance (right).

Plotting

In addition to viewing the image, there are many ways to plot values indicating true units. For example, to plot the spectral radiance along a horizontal line in the scene, you can use this code.

scene = sceneCreate('macbeth');     % Create a Macbeth color checker scene structure
ieAddObject(scene);  sceneWindow;   % Visualize the scene in a window
rows  = sceneGet(scene,'rows');     % Plot the middle row  
scenePlot(scene,'hline radiance',[1,round(rows/2)]);   

One axis in the mesh (right) shows the spatial position (mm) and the second axis shows the wavelength (nm). The height of the mesh shows the radiance (q/s/sr/nm/m^2).

Scripts, Tutorials, and Validation functions

• Tutorials (t_) teach about the code (ieRunTutorialsAll)
• Scripts (s_) illustrate basic operations (ieRunScriptsAll)
• Validations (v_) perform unit and regression tests (ieRunValidationAll)

Historical note - Matlab classes

The isetcam programming style was set in 2003, before Matlab had a set of tools for building and maintaining classes. Despite being based on structures, the style emulates object-based programming. The newer code in isetbio and isetlens and iset3d was written later and uses Matlab classes. Someone may convert the isetcam structures into Matlab classes - it wouldn't be hard, but it would take time and testing.