iset/isetcam/authoring-tutorials-examples

Authoring Tutorials and Examples

ISETCam keeps tutorials/ and examples/ as separate teaching surfaces for different goals and audiences. Preserve this distinction when adding or editing files.

Tutorials (tutorials/, t_*.m)

• Audience: learners (including new students) who can program and are

learning image systems engineering and ISETCam object fundamentals.

• Purpose: short, heavily commented introductions to key objects and APIs.
• Expected content:
• object creation and setup
• *Get/*Set usage for key properties
• basic visualization (*Window, *Plot)
• one simple quantitative computation/checkpoint
• Expected behavior: runs relatively quickly and is easy to read linearly.

Examples (examples/, s_*.m)

• Audience: users looking for realistic analysis patterns to adapt.
• Purpose: applied workflows and more advanced computations using ISETCam.
• Expected content:
• end-to-end numerical analyses or visualization workflows
• realistic parameter choices and tradeoff exploration
• code that users may copy/adapt as a starting point for their own work
• Expected behavior: can be longer and more detailed than tutorials.

If content is mainly onboarding and API orientation, place it in tutorials/. If content is mainly applied workflow, analysis, or deeper exploration, place it in examples/.

Data-Generation Scripts (data_*.m)

Some scripts exist to generate or refresh repository data files rather than to serve as tutorials or examples. Name these scripts data_*.m. This distinguishes them from the automated tutorial (t_*.m) and example (s_*.m) smoke-test sources discovered by the test runners, and makes their side-effecting purpose explicit.

Student Contributors

For student contributors, prioritize clarity, reproducibility, and instructional value: use clear comments, stable outputs, and explicit links to related wiki pages, tests, and nearby tutorials/examples.

Excluding a File From Automated Smoke Runs

ieTutorialTest and ieExampleTest execute every t_* and s_* file by default. To opt a file out, add this exact comment anywhere in the file:

% SkipFile

Use sparingly — for files needing unavailable external data/toolboxes, deliberate user interaction, unusually expensive computation, or a known, documented failure. Remove the tag once the file is suitable for routine automated execution. See the testing-workflow skill for the full marker contract and the legacy % UTTBSkip compatibility note.

Reviewing Existing Scripts

To review scripts under examples/* or tutorials/* for runnability, comment quality, overlap, and coverage against nearby _tests_ directories, use the existing matlab-script-review agent (.github/agents/matlab-script-review.agent.md) rather than re-deriving that workflow here.

Publishing

To convert a tutorial or example into linkable HTML, see the publishing-tutorials-examples skill.