ENH: Add ctype aliases for numeric types of specific sizes to Python

[N-Dekker]

Added the following aliases:

float32_t
float64_t
uint8_t
uint16_t
uint32_t
uint64_t
int8_t
int16_t
int32_t
int64_t

Aims to provide a more human-readable alternative to F, D, UC, US, UI, ULL, SC, SS, SI, and SLL. Eases writing code for which the specific size of numeric types should be platform-independent.

Typical use cases, specifying the pixel type of an image:

• itk.Image[itk.uint8_t, 2] (equivalent to itk.Image[itk.UC, 2])
• itk.Image[itk.float64_t, 2] (equivalent to itk.Image[itk.D, 2])
• itk.Image[itk.int64_t, 2] (equivalent to itk.Image[itk.SL, 2] on Linux and itk.Image[itk.SLL, 2] on Windows)

---

For the record, this comment is updated, following the replacement of the _ctype postfixes with _t (see #6762 (comment) and this force-pushed amend)

[greptile-apps]

Greptile Summary

This change adds top-level Python aliases for fixed-width integer and floating-point ITK C types, with regression coverage registered for their NumPy dtype mappings.

Confidence Score: 5/5

No blocking failure remains.

No accepted blocking findings remain.

T-Rex Logs

What T-Rex did

• The team attempted the documented Pixi build command and observed it could not progress because the Pixi package manager was not installed.
• The team attempted the registered focused test with the build-tree using PYTHONPATH and observed a ModuleNotFoundError for itk, indicating that ITK Python is not built or installed in the environment.
• The blockers were captured and a path forward was outlined: install Pixi, build the declared Python 3.13 ITK wrapper environment, then re-run the build commands and the ctest suite.

_{Ran code and verified through T-Rex}

_{Reviews (2): Last reviewed commit: "ENH: Add ctype aliases for numeric types..." | Re-trigger Greptile}

[thewtex]

How about using uint8, etc per:

https://github.com/InsightSoftwareConsortium/ITK/blob/main/Wrapping/Generators/Python/itk/support/extras.py#L266-L295

?

[N-Dekker]

How about using uint8, etc per:
https://github.com/InsightSoftwareConsortium/ITK/blob/main/Wrapping/Generators/Python/itk/support/extras.py#L266-L295
?

Thanks Matt, can you please elaborate a little bit? For example, how would you define a 2D itk Image of int64 pixels? With the proposed PR, it would be itk.Image[itk.int64_ctype, 2].

---

P.S. It looks like there is a bug at

ITK/Wrapping/Generators/Python/itk/support/extras.py

Line 286 in d56ecc0

np.dtype(np.int64): itk.SL,

    # This is a Mapping from numpy array types to itk pixel types. (Bug?)
    _np_itk = {
        ...
        np.dtype(np.int64): itk.SL,
        ...
     }

itk.SL is not int64, on Windows. Once this pull request is merged, it can be fixed by doing:

    # This is a Mapping from numpy array types to itk pixel types. (Fixed!)
    _np_itk = {
        ...
        np.dtype(np.int64): itk.int64_ctype,
        ...
     }

Is that what you meant to say?

[thewtex]

itk.Image[itk.int64_ctype, 2].

I think it would be easier to write, easier to read, and more expected names if we had itk.Image[itk.int64, 2] or itk.Image[np.int64, 2].

np.dtype(np.int64): itk.SL,

Good catch!

[N-Dekker]

Update: Inspired by Matt's comments, I just renamed the proposed aliases (with this force-pushed amend) to:

float32_t
float64_t
uint8_t
uint16_t
uint32_t
uint64_t
int8_t
int16_t
int32_t
int64_t

Under the hood, they are still simply aliases of itk.F, itk.D, itk.UC, etc.

The PR will now allow users to write (for example) itk.Image[itk.int64_t, 2], which looks very similar to the C++ equivalent, itk::Image<std::int64_t, 2>.

Hope that it's good enough now!

[blowekamp]

Does itk.Image[np.int64, 2] already work? I know it's not in this PR, but both of Matt's examples looked intuitive to me as a python user.

[N-Dekker]

Thanks for your approval, @blowekamp

Does itk.Image[np.int64, 2] already work?

No, itk.Image[np.int64, 2] does not work, sorry. I tried:

import itk
import numpy as np
image_type = itk.Image[np.int64, 2]

It said:

Traceback (most recent call last):
  File "...\Lib\site-packages\itk\support\template_class.py", line 526, in __getitem__
    this_item = self.__template__[key]
                ~~~~~~~~~~~~~~~~~^^^^^
KeyError: (<class 'numpy.int64'>, 2)

During handling of the above exception, another exception occurred:

Traceback (most recent call last):
  File "...\my_arithmetic_types.py", line 3, in <module>
    image_type = itk.Image[np.int64, 2]
                 ~~~~~~~~~^^^^^^^^^^^^^
  File "...\Lib\site-packages\itk\support\template_class.py", line 530, in __getitem__
    raise itk.TemplateTypeError(self, key)
itk.support.extras.TemplateTypeError: itk.Image is not wrapped for input type `int64, int`.

To limit the size of the package, only a limited number of
types are available in ITK Python. To print the supported
types, run the following command in your python environment:

    itk.Image.GetTypes()

Possible solutions:
* If you are an application user:
** Convert your input image into a supported format (see below).
** Contact developer to report the issue.
* If you are an application developer, force input images to be
loaded in a supported pixel type.

    e.g.: instance = itk.Image[itk.RGBPixel[itk.UC], int].New(my_input)

* (Advanced) If you are an application developer, build ITK Python yourself and
turned to `ON` the corresponding CMake option to wrap the pixel type or image
dimension you need. When configuring ITK with CMake, you can set
`ITK_WRAP_${type}` (replace ${type} with appropriate pixel type such as
`double`). If you need to support images with 4 or 5 dimensions, you can add
these dimensions to the list of dimensions in the CMake variable
`ITK_WRAP_IMAGE_DIMS`.

Supported input types:

itk.RGBPixel[itk.UC]
itk.RGBAPixel[itk.UC]
itk.Vector[itk.F,2]
itk.Vector[itk.F,3]
itk.Vector[itk.F,4]
itk.CovariantVector[itk.F,2]
itk.CovariantVector[itk.F,3]
itk.CovariantVector[itk.F,4]
itk.SS
itk.UC
itk.US
itk.F
itk.D
itk.complex[itk.D]
itk.complex[itk.F]
itk.Vector[itk.D,2]
itk.Vector[itk.D,3]
itk.Vector[itk.D,4]
itk.SI
itk.UI
itk.UL
itk.ULL
itk.B
itk.FixedArray[itk.F,2]
itk.FixedArray[itk.D,2]
itk.Offset[2]
itk.SymmetricSecondRankTensor[itk.D,2]
itk.SymmetricSecondRankTensor[itk.F,2]
itk.RGBPixel[itk.UC]
itk.RGBAPixel[itk.UC]
itk.Vector[itk.F,2]
itk.Vector[itk.F,3]
itk.Vector[itk.F,4]
itk.CovariantVector[itk.F,2]
itk.CovariantVector[itk.F,3]
itk.CovariantVector[itk.F,4]
itk.SS
itk.UC
itk.US
itk.F
itk.D
itk.complex[itk.D]
itk.complex[itk.F]
itk.Vector[itk.D,2]
itk.Vector[itk.D,3]
itk.Vector[itk.D,4]
itk.SI
itk.UI
itk.UL
itk.ULL
itk.B
itk.FixedArray[itk.F,3]
itk.FixedArray[itk.D,3]
itk.Offset[3]
itk.SymmetricSecondRankTensor[itk.D,3]
itk.SymmetricSecondRankTensor[itk.F,3]
itk.RGBPixel[itk.UC]
itk.RGBAPixel[itk.UC]
itk.Vector[itk.F,2]
itk.Vector[itk.F,3]
itk.Vector[itk.F,4]
itk.CovariantVector[itk.F,2]
itk.CovariantVector[itk.F,3]
itk.CovariantVector[itk.F,4]
itk.SS
itk.UC
itk.US
itk.F
itk.D
itk.complex[itk.D]
itk.complex[itk.F]
itk.Vector[itk.D,2]
itk.Vector[itk.D,3]
itk.Vector[itk.D,4]
itk.SI
itk.UI
itk.UL
itk.ULL
itk.B
itk.FixedArray[itk.F,4]
itk.FixedArray[itk.D,4]
itk.Offset[4]
itk.SymmetricSecondRankTensor[itk.D,4]
itk.SymmetricSecondRankTensor[itk.F,4]
itk.Vector[itk.F,1]
itk.Vector[itk.F,1]
itk.Vector[itk.D,2]
itk.Vector[itk.D,3]
itk.Vector[itk.D,4]
itk.Vector[itk.F,1]
itk.CovariantVector[itk.D,2]
itk.CovariantVector[itk.D,3]
itk.CovariantVector[itk.D,4]
itk.CovariantVector[itk.D,2]
itk.CovariantVector[itk.D,3]
itk.CovariantVector[itk.D,4]
itk.CovariantVector[itk.D,2]
itk.CovariantVector[itk.D,3]
itk.CovariantVector[itk.D,4]
itk.NormalBandNode[itk.Image[itk.F,2]]
itk.NormalBandNode[itk.Image[itk.D,2]]
itk.NormalBandNode[itk.Image[itk.F,3]]
itk.NormalBandNode[itk.Image[itk.D,3]]
itk.NormalBandNode[itk.Image[itk.F,4]]
itk.NormalBandNode[itk.Image[itk.D,4]]

Press any key to continue . . .

[N-Dekker]

As a follow-up, it might be nice to add support for using a NumPy type to specify the pixel type of an itk.Image. But I think there should still be a direct and ITK-specific way as well, for users to specify a pixel type of a specific size.

[thewtex]

@N-Dekker nice! LGTM! 🥇

[N-Dekker]

Thanks for your approval, @thewtex, @dzenanz, @blowekamp

When it's merged, I'm considering a style PR to replace code of the form:

if os.name == "nt":
use itk.SLL
else:
use itk.SL

With simply just: use itk.int64_t. To be continued... 😃