Programming - ISET/isetcam GitHub Wiki

• ISETCam serves as the main toolbox that others use.
• This page summarizes ISETCam programming conventions that are generally followed here and inin related toolboxes (ISETBio, ISETLens, ISET3d).

ISETCam is implemented using key Matlab structures that represent critical image systems components: 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)

We use these principles for variable and function names.

• Function names: nounVerb, say sceneCreate. That way scene<TAB> 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<function>, which has its roots in image evaluation (imageval). A few functions prepend 'vc'; which arises from an even earlier time when the project was called 'virtual camera'.
• Documentation: we are working towards the function documentation standards in ISETbio.
• Invoking doc functionName generates useful help
• Many functions have examples inserted as block comments near the top of the file. If you have ISETValidate toolbox and the ExamplesTestToolbox, you can print and run these examples using ieExamplePrint(theFunction) or ieExamplesOne(theFunction)

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 we store these objects. You can add, get, or replace an object in the data base using the ieAddObject(), ieGetObject(), ieReplaceObject() functions.

There is a graphical user interface (GUI) for visualizing many of the key structures. We find these GUIs to be particularly helpful for debugging. A quick look at a structure and the parameters as shown 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
sceneWindow(scene);                % Add the scene or oi to the data management system
oiWindow(oi);                      % and visualize
ieAddObject(scene); sceneWindow;   % Explicitly add and show; ieReplaceObject() 
ieAddObject(oi); oiWindow;         % is another option.  Just calling sceneWindow or oiWindow
                                   % shows the currently selected object.

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).

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
sceneWindow(scene);                 % Add scene to database and visualize the scene in a window
rows  = sceneGet(scene,'rows');     % Plot the middle row  
scenePlot(scene,'hline radiance',[1,round(rows/2)]);   

• Tutorials (t_) teach about the code (ieRunTutorialsAll)
• Scripts (s_) illustrate basic operations (ieRunScriptsAll)

Note: For many years, each repository included its own tutorials and scripts. As the number of tutorials and scripts grew, we become dissatisifed with the organization. As of September, 2024, we created a new ISETTutorials repository specifically for tutorials related to the main ISET repositories (ISETCam, ISETBio, ISET3d). By early 2025, we hope to improve the organization of scripts and tutorials using this new reepository. Repositories for specific projects, and associated with publications, will continue to have their own scripts and tutorials.

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 ISETCam style emulates object-based programming. The newer code in ISETBio, ISET3d, and other toolboxes were written later and use Matlab classes. Someone may convert the ISETCam structures into Matlab classes - it wouldn't be hard conceptually, but it would take time and testing.