iset/isetcam/matlab-evaluation

MATLAB Evaluation Workflow

Repository layout

Use the repository that owns the source file. Do not assume that Psych 221 uses ISETCam's tutorial or example directory structure.

Psych 221 provides psych221RootPath.m at its root. Add the Psych 221 root and its subdirectories to the MATLAB path when running its tutorials because they can rely on local helper functions or data:

psychRoot = fullfile(getenv('HOME'), 'Documents', 'MATLAB', 'teach', 'psych221');
addpath(genpath(psychRoot));
rmpath(fullfile(psychRoot, 'livescripts'));

Keep livescripts/ off the runtime path. Its .mlx source files can otherwise shadow same-stem converted .m scripts elsewhere in Psych 221.

Do not look for psych221/tutorials/, psych221/examples/, psych221/data/, psych221/utility/, run_all_scripts.sh, or publish_scripts.sh; they are not part of this repository.

Find MATLAB

MATLAB is not necessarily on the shell PATH. Discover installed releases and use an app bundle executable:

ls /Applications | rg '^MATLAB_R'
/Applications/MATLAB_R2026a.app/bin/matlab -batch "disp(version)"

Prefer the newest installed release unless the user specifies another one. Use -batch rather than -r: it exits automatically and reports an uncaught MATLAB error through the process exit status.

Run a script in batch mode

Use absolute paths for the script and both repository roots. -batch inherits the shell working directory, so do not rely on a relative script path unless the working directory was deliberately selected.

/Applications/MATLAB_R2026a.app/bin/matlab -batch "\
isetRoot = fullfile(getenv('HOME'), 'Documents', 'MATLAB', 'isetcam'); \
psychRoot = fullfile(getenv('HOME'), 'Documents', 'MATLAB', 'teach', 'psych221'); \
addpath(genpath(isetRoot)); \
addpath(genpath(psychRoot)); \
rmpath(fullfile(psychRoot, 'livescripts')); \
run(fullfile(psychRoot, 'ImageFormation_01a.m'))"

For ISETCam-only code, add ISETCam rather than Psych 221 unless the script actually requires Psych 221 support files. Before executing an unfamiliar script, inspect it for deliberate interactive calls such as pause, input, keyboard, or waitfor.

Convert a Psych 221 Live Script

Keep the .mlx source in psych221/livescripts/ and write its plain-text .m conversion into the Psych 221 root:

sourceFile = fullfile(psychRoot, 'livescripts', 'ImageFormation_01a.mlx');
targetFile = fullfile(psychRoot, 'ImageFormation_01a.m');
matlab.internal.liveeditor.openAndConvert(sourceFile, targetFile);

Do not write converted files back into livescripts/ unless explicitly asked. Verify that each .mlx source has a non-empty same-stem .m file at the Psych 221 root.

Publish HTML with ISETCam

iePublish is an ISETCam utility. It accepts a plain-text .m file and writes self-contained HTML beside that source file; it does not publish an .mlx file and it does not write into isetcam/docs/ by default.

For a Psych 221 tutorial, add both repositories to the path and pass the full path to the converted root-level script:

isetRoot = fullfile(getenv('HOME'), 'Documents', 'MATLAB', 'isetcam');
psychRoot = fullfile(getenv('HOME'), 'Documents', 'MATLAB', 'teach', 'psych221');
addpath(genpath(isetRoot));
addpath(genpath(psychRoot));
rmpath(fullfile(psychRoot, 'livescripts'));
 
htmlFile = iePublish(fullfile(psychRoot, 'ImageFormation_01a.m'), ...
    'imageFormat', 'inline');

Use evalCode, showCode, maxHeight, maxWidth, and catchError as needed. Set evalCode to false only for a code-only preview; execute the tutorial when figures and output must be regenerated. s_publishTutorials and s_publishExamples are ISETCam batch helpers for ISETCam's own source directories, not a publisher for the Psych 221 root-level tutorials.

Verify the session

Confirm expected functions before evaluating or publishing:

which iePublish
which psych221RootPath

Check the MATLAB process exit status and inspect generated HTML locally when publishing. Keep generated HTML next to the .m source unless the user asks to move it elsewhere.