Skip to content

Commit 8a9622e

Browse files
thewtexthewtex
committed
DOC: Add AI agent guide for ITK development
Create comprehensive AGENTS.md to help AI coding agents navigate ITK's architecture and development workflows. The guide covers: - Modular architecture with itk-module.cmake dependency system - Template-heavy C++ design patterns and generic programming - Data pipeline execution model with lazy evaluation - CMake build system including Python wrapping via SWIG - Testing framework (CTest, GTest, ExternalData) - Development setup (git hooks, clang-format, KWStyle) - Code style conventions and common pitfalls - File organization patterns (.h, .hxx, .cxx separation) This resource enables AI agents to quickly understand ITK-specific conventions and become productive contributors.
1 parent 78fbad0 commit 8a9622e

File tree

1 file changed

+309
-0
lines changed

1 file changed

+309
-0
lines changed

‎AGENTS.md‎

Lines changed: 309 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,309 @@
1+
# ITK AI Agent Guide
2+
3+
ITK (Insight Toolkit) is a cross-platform, open-source toolkit for N-dimensional scientific image processing, segmentation, and registration. This guide helps AI agents navigate ITK's unique architecture and development workflows.
4+
5+
## Architecture Overview
6+
7+
### Modular Structure
8+
ITK uses a **module-based architecture** where each module is a self-contained unit with dependencies. Modules are organized in:
9+
- `Modules/Core/` - Essential classes (Image, Region, Point, Vector, pipeline infrastructure)
10+
- `Modules/Filtering/` - Image processing filters
11+
- `Modules/IO/` - Image, mesh, and transform I/O for various formats (JPEG, PNG, NIFTI, DICOM, etc.)
12+
- `Modules/Registration/` - Image registration algorithms
13+
- `Modules/Segmentation/` - Segmentation algorithms
14+
- `Modules/Numerics/` - Optimization and numerical methods
15+
- `Modules/ThirdParty/` - Vendored dependencies (HDF5, JPEG, TIFF, VNL, Eigen3)
16+
- `Modules/Bridge/` - Bridges to VTK, NumPy
17+
- `Modules/Remote/` - External modules fetched during build
18+
19+
Each module has an `itk-module.cmake` file declaring dependencies:
20+
```cmake
21+
itk_module(ITKCommon
22+
DEPENDS ITKEigen3 ITKVNL
23+
PRIVATE_DEPENDS ITKDoubleConversion
24+
COMPILE_DEPENDS ITKKWSys
25+
TEST_DEPENDS ITKTestKernel ITKMesh
26+
DESCRIPTION "Core ITK classes..."
27+
)
28+
```
29+
30+
### Template-Heavy C++ Design
31+
ITK extensively uses **C++ templates** and **generic programming** for:
32+
- Dimension-agnostic code (2D, 3D, nD images)
33+
- Type flexibility (pixel types: unsigned char, float, RGB, etc.)
34+
- Compile-time polymorphism via traits and policy classes
35+
36+
Example: `itk::Image<TPixel, VImageDimension>` where both parameters are compile-time constants.
37+
38+
### Pipeline Architecture
39+
ITK uses a **data pipeline** pattern:
40+
- **Process objects** (`itk::ProcessObject`, e.g. most filters) perform computations
41+
- **Data objects** (`itk::DataObject`, e.g., `itk::Image`) store data
42+
- Filters connect via `SetInput()` / `GetOutput()` and execute lazily with `Update()`
43+
- Smart pointers (`itk::SmartPointer<T>`) handle memory management
44+
45+
### Python Wrapping
46+
ITK provides **Python wrappers** via SWIG:
47+
- Wrapping configs in `Wrapping/` directory
48+
- Explicit template instantiations in `wrapping/` subdirectories of modules
49+
- Python package structure mirrors C++ modules
50+
- Snake_case functions available (e.g., `itk.median_image_filter()`)
51+
- Install via `pip install itk` or build with `ITK_WRAP_PYTHON=ON`
52+
53+
## Build System
54+
55+
### CMake Configuration
56+
ITK requires CMake 3.22.1+. Key build options:
57+
58+
**Essential:**
59+
```bash
60+
cmake -B build -S . \
61+
-DCMAKE_BUILD_TYPE=Release \
62+
-DITK_BUILD_DEFAULT_MODULES=ON \
63+
-DBUILD_TESTING=ON \
64+
-DBUILD_EXAMPLES=OFF
65+
```
66+
67+
**Python wrapping:**
68+
```bash
69+
cmake -B build-python -S . \
70+
-DITK_WRAP_PYTHON=ON \
71+
-DITK_WRAP_unsigned_short=ON \
72+
-DITK_WRAP_IMAGE_DIMS="2;3;4"
73+
```
74+
75+
**Module selection:**
76+
- `Module_<ModuleName>=ON` to enable specific modules
77+
- `ITK_BUILD_DEFAULT_MODULES=ON` builds standard modules
78+
- Use `find_package(ITK COMPONENTS ITKCommon ITKIOImageBase)` in external projects
79+
80+
### Building
81+
```bash
82+
# Standard build
83+
cmake --build build -j
84+
85+
# Python build
86+
cmake --build build-python -j
87+
88+
# Pixi (recommended for development)
89+
pixi run test # C++ tests
90+
pixi run test-python # Python tests
91+
```
92+
93+
For an interactive shell with ITK environment:
94+
```bash
95+
pixi shell -e cxx # C++ development
96+
pixi shell -e python # Python development
97+
```
98+
99+
### Module Dependencies
100+
ITK automatically resolves module dependencies via CMake. The module DAG is loaded from `itk-module.cmake` files. To find required modules for code:
101+
```bash
102+
python Utilities/Maintenance/WhatModulesITK.py /path/to/ITK/source file1.cxx file2.h
103+
```
104+
105+
## Testing
106+
107+
### CTest Integration
108+
Tests use **CTest** framework:
109+
```bash
110+
cd build
111+
ctest -j8 # Run all tests in parallel
112+
ctest -R ImageFilter # Run tests matching regex
113+
ctest -L REQUIRES_GPU # Run tests with label
114+
ctest --rerun-failed # Rerun only failed tests
115+
```
116+
117+
### Test Organization
118+
Each module has a `test/` directory with:
119+
- **CTest tests**: Defined via `itk_add_test()` macro
120+
- **GTest tests (preferred)**: Modern C++ tests using `creategoogletestdriver()`
121+
- **Baseline images**: Stored via `ExternalData` (downloaded on demand)
122+
123+
Example test definition:
124+
```cmake
125+
itk_add_test(NAME itkImageTest
126+
COMMAND ITKCommonTestDriver itkImageTest
127+
DATA{Input/image.png}
128+
${ITK_TEST_OUTPUT_DIR}/output.png
129+
)
130+
```
131+
132+
### ExternalData System
133+
Large test data is **not stored in Git**. Instead, ITK uses `ExternalData` with content hashes:
134+
- `DATA{path/to/file.png}` references data by hash
135+
- Data downloaded from `https` resources during build
136+
- Test data uploaded separately for new tests
137+
138+
## Development Workflow
139+
140+
### Setup for Development
141+
**First time only:**
142+
```bash
143+
./Utilities/SetupForDevelopment.sh
144+
```
145+
This configures:
146+
- Git hooks (pre-commit, commit-msg)
147+
- clang-format integration (auto-formats C++ on commit)
148+
- KWStyle configuration
149+
- GitHub remote setup
150+
151+
### Code Style
152+
153+
**Automatic C++ formatting:**
154+
ITK enforces `.clang-format` style automatically via pre-commit hook. To format manually:
155+
```bash
156+
Utilities/Maintenance/clang-format.bash --modified # Format modified files
157+
```
158+
159+
**Key style rules:**
160+
- Use `clang-format` 19.1.7 (enforced by pre-commit)
161+
- `constexpr` instead of `#define` for constants
162+
- Smart pointers for all ITK objects: `auto image = ImageType::New();`
163+
- American English spelling
164+
- Doxygen comments with `\` (backslash) style: `\class`, `\brief`
165+
- No `using namespace` in headers
166+
167+
**Naming conventions:**
168+
- Classes: `PascalCase` (e.g., `MedianImageFilter`)
169+
- Variables: `camelCase` or `lowercase` with no underscores
170+
- Member variables: `m_MemberVariable` prefix
171+
- Template parameters: `TInputImage`, `TOutputImage` prefix
172+
- Macros: `ITK_UPPERCASE_MACRO`
173+
174+
### Commit Guidelines
175+
**Required format** (enforced by `kw-commit-msg.py` hook):
176+
```
177+
PREFIX: Brief description (≤78 chars)
178+
179+
Longer explanation if needed. Reference issues or features.
180+
```
181+
182+
Common prefixes: `ENH:`, `BUG:`, `COMP:`, `DOC:`, `STYLE:`, `PERF:`, `WIP:`
183+
184+
### CI/CD
185+
ITK uses:
186+
- **Azure Pipelines** for Linux, Windows, macOS builds (C++ and Python)
187+
- **GitHub Actions** for Pixi builds and Apple Silicon
188+
- **CDash** dashboards at https://open.cdash.org/index.php?project=Insight
189+
190+
## Key Conventions
191+
192+
### ITK-Specific Patterns
193+
194+
**Object creation:**
195+
```cpp
196+
auto filter = FilterType::New(); // Factory method, returns SmartPointer
197+
filter->SetInput(image);
198+
filter->Update(); // Lazy evaluation
199+
auto output = filter->GetOutput();
200+
```
201+
202+
**Image iteration:**
203+
Use **iterators** (not raw buffers) for image traversal:
204+
```cpp
205+
itk::ImageRegionIterator<ImageType> it(image, region);
206+
for (; !it.IsAtEnd(); ++it) {
207+
it.Set(it.Get() * 2);
208+
}
209+
```
210+
211+
**Macros for class boilerplate:**
212+
```cpp
213+
using Self = MyClass;
214+
using Superclass = BaseClass;
215+
using Pointer = SmartPointer<Self>;
216+
itkNewMacro(Self); // Provides New() method
217+
itkTypeMacro(Self, Superclass); // RTTI support
218+
itkSetMacro(Radius, unsigned int); // Generates SetRadius()
219+
itkGetConstMacro(Radius, unsigned int); // Generates GetRadius()
220+
```
221+
222+
### File Organization
223+
Each module follows:
224+
```
225+
ModuleName/
226+
├── itk-module.cmake # Module metadata
227+
├── include/ # Public headers (.h)
228+
│ ├── itkClassName.h
229+
│ └── itkClassName.hxx # Template implementations
230+
├── src/ # Non-template implementations (.cxx)
231+
│ └── itkClassName.cxx # Non-template implementations
232+
├── test/ # Tests
233+
│ ├── CMakeLists.txt
234+
│ └── itkClassNameTest.cxx
235+
└── wrapping/ # Python wrapping (if applicable)
236+
└── itkClassName.wrap
237+
```
238+
239+
**Header structure:**
240+
- `.h` files: Class declarations
241+
- `.hxx` files: Template method implementations (included at end of `.h`)
242+
- `.cxx` files: Non-template implementations compiled into libraries
243+
244+
### Third-Party Code
245+
Third-party libraries in `Modules/ThirdParty/` are **subtrees**, not submodules:
246+
- Updated via `git subtree pull`
247+
- Maintained upstream separately
248+
- Wrapped with ITK CMake logic
249+
250+
## External Module Development
251+
252+
To create a remote module:
253+
1. Create `itk-module.cmake` with dependencies
254+
2. Create `MyModule.remote.cmake` in ITK's `Modules/Remote/`
255+
3. Use `itk_module_impl()` macro in module's CMakeLists.txt
256+
4. Test as external build:
257+
```bash
258+
cmake -B build-external -S path/to/module \
259+
-DITK_DIR=/path/to/ITK-build
260+
```
261+
262+
## Common Pitfalls
263+
264+
1. **Template compilation errors**: ITK's heavy template use causes verbose errors. Focus on the **first error** in the output.
265+
266+
2. **Python wrapping**: Not all C++ types are wrapped. Check `wrapping/` directories for available instantiations. Common wrapped types: `F` (float), `D` (double), `UC` (unsigned char), `US` (unsigned short).
267+
268+
3. **Memory management**: Always use `SmartPointer`. Never `delete` ITK objects manually.
269+
270+
4. **Update() calls**: Filters don't execute until `Update()` is called. Changes to filter parameters after `Update()` require another `Update()`.
271+
272+
5. **Module dependencies**: If code fails to link, check `itk-module.cmake` dependencies. Use `DEPENDS` for public deps, `PRIVATE_DEPENDS` for implementation deps.
273+
274+
## Resources
275+
276+
- Main docs: https://docs.itk.org/
277+
- Discourse forum: https://discourse.itk.org/
278+
- Software Guide: https://itk.org/ItkSoftwareGuide.pdf
279+
- Examples: https://examples.itk.org/
280+
- Doxygen API: https://itk.org/Doxygen/html/
281+
- Contribution guide: https://docs.itk.org/en/latest/contributing/
282+
283+
## Quick Reference
284+
285+
**Find class documentation:**
286+
```bash
287+
# Search Doxygen locally after building docs
288+
cmake -DITK_BUILD_DOCUMENTATION=ON ..
289+
```
290+
291+
**Test a single module:**
292+
```bash
293+
ctest -L ITKCommon
294+
```
295+
296+
**Build only specific modules:**
297+
```cmake
298+
set(Module_ITKCommon ON)
299+
set(Module_ITKIOImageBase ON)
300+
set(ITK_BUILD_DEFAULT_MODULES OFF)
301+
```
302+
303+
**Python quick test:**
304+
```python
305+
import itk
306+
image = itk.imread('input.png')
307+
smoothed = itk.median_image_filter(image, radius=2)
308+
itk.imwrite(smoothed, 'output.png')
309+
```

0 commit comments

Comments
 (0)