ENH: Release Python GIL during ITK operations

[Copilot]

Description

ITK Python wrappers hold the Global Interpreter Lock during C++ operations, preventing concurrent execution in multi-threaded contexts (Dask, Ray, threading module) and causing server lockups.

Changes

• CMake option: Added ITK_PYTHON_RELEASE_GIL (default ON) to control GIL release behavior
• SWIG configuration: Pass -threads flag to generate wrappers that release/reacquire GIL around C++ calls
• Test: test_gil_release.py verifies concurrent execution via timing overlap detection
• Documentation: ITK 6 migration guide section with usage examples

Implementation

Follows SimpleITK's approach (commit e9ce7283) - SWIG's -threads flag handles GIL release/reacquire automatically.

import itk
import threading

def process_image(path):
    # GIL released during ITK operations
    image = itk.imread(path)
    return itk.median_image_filter(image, radius=5)

# True concurrent execution now possible
threads = [threading.Thread(target=process_image, args=(p,)) for p in paths]
for t in threads: t.start()
for t in threads: t.join()

Disable with -DITK_PYTHON_RELEASE_GIL=OFF if callbacks/events require GIL.

PR Checklist

• No API changes were made (or the changes have been approved)
• No major design changes were made (or the changes have been approved)
• Added test (or behavior not changed)
• Updated API documentation (or API not changed)
• Added license to new files (if any)
• Added Python wrapping to new files (if any) as described in ITK Software Guide Section 9.5
• Added ITK examples for all new major features (if any)

Original prompt

---

This section details on the original issue you should resolve

<issue_title>Release the GIL in ITK operations</issue_title>
<issue_description>First, a question: Does the ITK Python library release the GIL when it calls down to lower level C/C++ code?

When I run ITK operations within Dask I notice that my servers lock up. The most common cause of this is that some low level code is holding onto the GIL and not letting go. Is it possible that ITK does this?

If ITK does not release the GIL, could it?

xref https://discourse.itk.org/t/parallelize-itk-imageseriesreader-itk-4-12/1745/15</issue_description>

Comments on the Issue (you are @copilot in this section)

@thewtex @mrocklin thanks for the report. We will dive deeper into this.

:xref: #1065 , which was not sufficient.</comment_new>
<comment_new>@blowekamp
This is how it is done in SimpleITK:
SimpleITK/SimpleITK@e9ce728</comment_new>
<comment_new>@thewtex
I am wondering if the observed behavior was related to:

cfdb502

or

#2069

@thewtex Hi @lust4life ,

Can you provide more context on ray?

itkElastixRegistrationMethod.UpdateLargestPossibleRegion, [...] it finished the registration.

It is expected that UpdateLargestPossibleRegion does not return until registration completes.</comment_new>
<comment_new>@blowekamp
This sample code appears to use asyncio, which is not multi-threading. Use the two concurrently can make things complicated, and at least make a poor example illustrated the issue. Unlocking the GIL during computation allows another thread to use the single threaded python interpreter, but does not "yield" in the async thread.

One possible work around is to wrap the computation in a async subprocess. Some ITK filters and process use callback to report progress, these could theoretically be use to yield computation but there are a lot of details here too.

Another alternative is to look at SimpleITK as it unlocks the GIL, as see if that could work better with the ray computational infrastructure.

@dzenanz @thewtex might want to comment now. @blowekamp > Plan to expose these function as an FastAPI http call, a long run case make the whole web service blocked.

There are many reasons why ITK computations should not be done in the same thread or process as a web server. I have used some type of task queue for this type of computational work, where the image processing is done in a separate process(es) shared by all api threads. As I suggested before at minimum I'd suggest running the ITK algorithm in a sub-process of the api thread, but managing resources when many ITK processes are requested would still be challanging.

I can't use it, as it has its own conventions which will generate the output image by default as the result for these calls, but what i want is just the registration output parameters.

Yes, that seams a reasonable weakness on the SimpleElastix interface, alternatives can always be proposed. </comment_new>
<comment_new>@thewtex
@lust4life thanks for the detailed report, explanation, and reproducible sample code 👏

I will:

1. Look into the ITK GIL usage with the sample code.
2. Look towards ITK-Wasm functionality for your use case, which inherently has better sandboxing.</comment_new>

• Fixes Release the GIL in ITK operations #1134

---

💬 We'd love your input! Share your thoughts on Copilot coding agent in our 2 minute survey.