16.1. So You Want to Write an AFNI Program

A developer’s handbook for writing new C programs against AFNI’s libraries.

This section is written for someone who has cloned the AFNI source tree, can build it, and now wants to add a new command-line program (or hack on an existing one) using the same datasets, I/O routines, statistics, and communication machinery that the rest of AFNI uses. The emphasis throughout is on the existing API: nearly everything you need already has a function, a macro, or a whole subsystem written for it, and dozens of shipped programs show you how it is meant to be called. Wherever a topic is introduced, we point at real programs in src/ that use the same calls so you can read a complete, working example.

The spine of this handbook is src/3dToyProg.c, a deliberately over-commented demonstration program that creates a dataset from scratch, reads one from disk, walks its coordinate system, and does both volume-wise and voxel-wise computations. Read it alongside these pages.

• 16.1.1. Anatomy of an AFNI Program
  • The 30-second version
  • The one header to rule them all
  • The main() skeleton
  • ENTRY / RETURN: the call-stack traceback
  • Talking to the user: message macros
  • Help, option-suggestion, and tab-completion
  • Provenance: dataset history
  • Overwrite protection
  • Building your program into AFNI
  • What to read next
• 16.1.2. Datasets and Volumes
  • The two core structures
  • Reading a dataset from disk
  • Reaching into the voxel data
  • Navigating: voxel indices and mm coordinates
  • Masks
  • Creating a dataset from scratch
  • Deriving a new dataset from an existing one
  • The voxel-wise convenience engine
  • Writing the result
• 16.1.3. Surfaces
  • The surface geometry: SUMA_SurfaceObject
  • The surface data: SUMA_DSET
  • How this fits together
• 16.1.4. Communication: NIML and Live Data
  • The NIML data model
  • Streams: the same API over any transport
  • Talking to the AFNI/SUMA GUIs
  • InstaCorr: live seed-based correlation
  • GroupInCorr: correlation across a group, over a socket
• 16.1.5. The Function Cookbook
  • Opening, loading, and writing datasets
  • Getting voxel data in and out
  • Whole-dataset time series: the MRI_vectim
  • Time-series and correlation primitives
  • Masks and clustering
  • Statistics: p-values and thresholds
  • 1D (text column) I/O
  • Provenance and attributes
  • Where to read real callers

Note

This handbook documents C-language internals. For how to write and format the -help output of a program (so it shows up correctly on the web docs and supports tab-completion), see How to Format Help Strings. For how to get your work merged, see the pull-request walkthrough in the developer docs.