{"id":9840,"library":"itk-io","title":"ITK-IO","description":"ITK-IO provides core input/output capabilities for the Insight Toolkit (ITK), an open-source, cross-platform toolkit for n-dimensional scientific image analysis. It enables reading and writing various image file formats. Currently at version 5.4.5, it follows ITK's maintenance release cadence, with major version 6.0 in beta, focusing on bug fixes, performance improvements, and C++ modernization.","status":"active","version":"5.4.5","language":"en","source_language":"en","source_url":"https://github.com/InsightSoftwareConsortium/ITK","tags":["image-processing","medical-imaging","n-dimensional","computer-vision","io","scientific-computing"],"install":[{"cmd":"pip install itk-io","lang":"bash","label":"Install specific IO components"},{"cmd":"pip install itk","lang":"bash","label":"Install full ITK including IO"},{"cmd":"pip install itk-full","lang":"bash","label":"Install ITK with all optional IO features"}],"dependencies":[{"reason":"The 'itk-io' package is part of the larger ITK ecosystem and relies on the core 'itk' package for fundamental image objects and processing. 'itk-io' internally depends on 'itk-core', which in turn depends on 'itk'.","package":"itk","optional":false},{"reason":"While not a strict dependency for 'itk-io' to run, 'numpy' is essential for practical Python usage of ITK, especially for converting between ITK image objects and NumPy arrays (e.g., via `itk.image_from_array`, `itk.array_from_image`).","package":"numpy","optional":true}],"imports":[{"note":"All ITK Python functionality, including IO, is typically exposed directly under the top-level `itk` namespace. Direct imports from `itk_io` are generally not supported or necessary.","wrong":"from itk_io import imread","symbol":"itk","correct":"import itk"},{"note":"Convenience function for reading images, part of the ITK-IO functionality exposed via the main `itk` module.","symbol":"imread","correct":"itk.imread"},{"note":"Convenience function for writing images, part of the ITK-IO functionality exposed via the main `itk` module.","symbol":"imwrite","correct":"itk.imwrite"},{"note":"The core ITK C++ class binding for reading images, accessible through the `itk` namespace.","symbol":"ImageFileReader","correct":"itk.ImageFileReader"}],"quickstart":{"code":"import itk\nimport numpy as np\nimport os\n\n# 1. Create a dummy NumPy array (e.g., 3D unsigned char)\nimage_array = np.arange(64*64*64, dtype=np.uint8).reshape((64, 64, 64))\n\n# 2. Convert NumPy array to ITK image object\nitk_image = itk.image_from_array(image_array)\n\n# Define a temporary file name for the image\noutput_filename = os.path.join(os.getcwd(), \"itk_dummy_image.mha\") # .mha is a common ITK format\n\n# 3. Write the ITK image to a file using itk.imwrite\nprint(f\"Writing image to {output_filename}\")\nitk.imwrite(itk_image, output_filename)\nprint(\"Image written successfully.\")\n\n# 4. Read the image back from the file using itk.imread\nprint(f\"Reading image from {output_filename}\")\nread_itk_image = itk.imread(output_filename) # itk.imread infers pixel type if not specified\nprint(\"Image read successfully.\")\n\n# 5. Verify properties of the read image\nprint(f\"Read image dimensions: {read_itk_image.GetImageDimension()}\")\nprint(f\"Read image size: {read_itk_image.GetLargestPossibleRegion().GetSize()}\")\nprint(f\"Read image pixel type: {read_itk_image.GetPixelIDTypeAsString()}\")\n\n# 6. (Optional) Convert the read ITK image back to a NumPy array for verification\nread_array = itk.array_from_image(read_itk_image)\nprint(f\"Read array shape: {read_array.shape}, dtype: {read_array.dtype}\")\nprint(f\"Arrays are equal: {np.array_equal(image_array, read_array)}\")\n\n# Clean up the dummy file\nif os.path.exists(output_filename):\n    os.remove(output_filename)\n    print(f\"Cleaned up {output_filename}\")","lang":"python","description":"This quickstart demonstrates how to create a simple 3D image using NumPy, convert it to an ITK image object, save it to a MetaImage (.mha) file, and then read it back. Finally, it verifies the integrity of the data by converting it back to a NumPy array and comparing it with the original."},"warnings":[{"fix":"Ensure your C++ compiler supports C++17. For Python users, ensure you are using pre-built wheels that are compatible with your system's C++ runtime, or update your build environment if compiling custom modules.","message":"ITK 6.0 (currently in beta) requires C++17. If you are building ITK from source, developing custom C++ ITK modules, or using specific compiler versions, this C++ standard update may cause compilation failures or require environment adjustments.","severity":"breaking","affected_versions":">=6.0b01"},{"fix":"Always import the top-level `itk` package: `import itk`. Then access IO functions like `itk.imread`, `itk.imwrite`, `itk.ImageFileReader`, etc.","message":"The `itk-io` Python package does not expose its functionality via `from itk_io import ...`. All ITK Python functionality, including IO, is consolidated under the main `itk` namespace. Attempting to import directly from `itk_io` will result in a `ModuleNotFoundError`.","severity":"gotcha","affected_versions":"All versions"},{"fix":"If you encounter errors reading specific file types (e.g., DICOM), try installing the `itk` metapackage (`pip install itk`) or `itk-full` (`pip install itk-full`) to ensure all necessary backend libraries are included.","message":"ITK has a complex C++ backend with many optional components (e.g., for specific file formats like DICOM, HDF5, JPEG2000). While `pip install itk-io` provides core IO, you might need `pip install itk` or `pip install itk-full` to get full support for all desired image formats and features, especially for medical imaging.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Always convert `pathlib.Path` objects to strings using `str(path_object)` before passing them to ITK functions or methods, especially those directly binding to C++ functions. Convenience functions like `itk.imread` and `itk.imwrite` are generally more forgiving.","message":"ITK Python bindings often expect plain Python strings for file paths and other string arguments, especially when interacting directly with underlying C++ ITK objects (e.g., `itk.ImageFileReader.SetFileName`). Passing `pathlib.Path` objects directly can sometimes lead to `TypeError`.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-17T00:00:00.000Z","next_check":"2026-07-16T00:00:00.000Z","problems":[{"fix":"Use `import itk` to access all ITK functionality, including IO functions like `itk.imread`.","cause":"Attempted to import directly from 'itk_io' instead of the unified 'itk' namespace.","error":"ModuleNotFoundError: No module named 'itk_io'"},{"fix":"Ensure you have `itk-io` installed (`pip install itk-io`) or install the full ITK package (`pip install itk` or `pip install itk-full`).","cause":"The installed `itk` package (or its sub-packages) does not include the IO components required for `imread`/`imwrite`. This can happen if only a minimal `itk` version without IO support was installed, or if the `itk-io` component is missing.","error":"AttributeError: module 'itk' has no attribute 'imread'"},{"fix":"Verify the file path and existence. Check if the file is valid and not corrupted. If reading a specialized format like DICOM, ensure `itk-full` is installed (`pip install itk-full`) as it includes more IO backends. For custom builds, ensure relevant ITK modules are enabled.","cause":"Generic error indicating ITK failed to read the image file. This could be due to the file not existing, corrupted data, an unsupported file format, or missing optional backend libraries (e.g., GDCM for DICOM, HDF5, etc.) required by ITK.","error":"RuntimeError: itk::ImageIOBaseException (0x...): Could not read image file \"path/to/image.dcm\""},{"fix":"Convert the path object to a string before passing it: `reader.SetFileName(str(my_path_object))`.","cause":"You are passing an object of an incorrect type (e.g., `pathlib.Path` object) to an ITK C++ binding method that specifically expects a Python string (which maps to `char const *` in C++).","error":"TypeError: in method 'ImageFileReader_SetFileName', argument 2 of type 'char const *'"}]}