Image IO APIs for wide range image formats (jpg, png, tif, dng, bmp, yuv, nv12 and RAWs), support Exif, interact nicely with numpy array.
CXX Image IO is a Python project which provides the image IO interfaces, binding with the C++ library: https://github.com/emmcb/cxx-image, These IO interfaces are designed to read and write images in many file formats in generic way and to interact nicely with numpy array.
| Image format | Read | Write | EXIF | Pixel precision | Pixel type | File extension | Sidecar needed |
|---|---|---|---|---|---|---|---|
| BMP | x | x | 8 bits | Grayscale, RGB, RGBA | .bmp | ||
| CFA | x | x | 16 bits | Bayer | .cfa | ||
| DNG | x | x | x | 16 bits, float | Bayer, RGB | .dng | |
| JPEG | x | x | x | 8 bits | Grayscale, RGB | .jpg, .jpeg | |
| MIPI RAW | x | x | 10 bits, 12 bits | Bayer | .RAWMIPI, .RAWMIPI10, .RAWMIPI12 | x | |
| PLAIN RAW | x | x | * | * | .raw .plain16, .nv12, yuv, * | x | |
| PNG | x | x | 8 bits, 16 bits | Grayscale, RGB, RGBA | .png | ||
| TIFF | x | x | x | 8 bits, 16 bits, float | Bayer, RGB | .tif, .tiff |
This projet currently supports Python from 3.10 to 3.13 on
x86_64x86_64 and aarch64, glibc v2.28+, musl libc v1.2+x86_64 and arm64, v11.0+The python package cxx-image-io is to be installed by pip
pip install cxx-image-io
read_image is able to read a image file and return a numpy array and ImageMetadata object.
from cxx_image_io import read_image
from cxx_image_io import ImageMetadata
import numpy as np
from pathlib import Path
image, metadata = read_image(Path('/path/to/image.jpg'))
assert isinstance(image, np.ndarray)
print('Type:', image.dtype)
print('Shape:', image.shape)
image is a numpy array which is suitable for the image processing afterwards.
The print result could be like this:
Type: uint8
Shape: (551, 603, 3)
ImageMetadata is the information about the image, the component fileInfo including the pixel type, pixel precision and image layout, which define fundamentally how the pixels arranged in buffer.
print(metadata.fileInfo)
The print result could be like this:
{'pixelPrecision': 8, 'imageLayout': 'interleaved', 'pixelType': 'rgb'}
metadata.fileInfo shows: image is a 3-dimensional numpy array, where rgb 3 channels interleaved, in each channel, pixel depth is 8 bits.
ImageMetadata has more components than fileInfo, it also includes ExifMetadata, help(ImageMetadata) will show the details.
Some file formats need to know in advance some informations about the image. For example, the PLAIN RAW format is just a simple dump of a buffer into a file, thus it needs to know how to interpret the data.
Bayer Plain Raw 16 bits
image, metadata = read_image(Path('/path/to/image.plain16'))
print('Type:', image.dtype)
print('Shape:', image.shape)
print(metadata.fileInfo)
In this case, user need to have an image sidecar JSON located next to the image file as the same name and path '/path/to/image.json'
{
"fileInfo": {
"format": "plain",
"height": 3072,
"width": 4080
"pixelPrecision": 16,
"pixelType": "bayer_gbrg",
}
}
After image reading, the information in JSON sidecar is parsed in ImageMetadata object.
The print result of will be like this:
Type: uint16
Shape: (3072, 4080)
{'width': 4080, 'height': 3072, 'pixelPrecision': 16, 'imageLayout': 'planar', 'pixelType': 'bayer_gbrg'}
metadata.fileInfo shows that image is a 2-dimensional numpy array, where pixel is Bayer type, planar layout (not interleaved), pixel depth is 16 bits.
Image sidecar is not mandatory, for the other formats which have already image information in their header, like jpg, png, tif, cfa. we don't need to provide image metadata.
python code
image, metadata = read_image(Path('/path/to/image.RAWMIPI12'))
sidecar json
{
"fileInfo": {
"fileFormat": "raw12",
"height": 3000,
"width": 4000,
"pixelPrecision": 12,
"pixelType": "bayer_gbrg"
}
}
python code
image, metadata = read_image(Path('/path/to/image.RAWMIPI'))
sidecar json
{
"fileInfo": {
"height": 3000,
"width": 4000,
"format": "raw10",
"pixelPrecision": 10,
"pixelType": "bayer_grbg"
}
}
python code
image, metadata = read_image(Path('/path/to/image.yuv'))
sidecar json
{
"fileInfo": {
"format": "plain",
"height": 300,
"width": 400,
"imageLayout": "yuv_420"
}
}
python code
image, metadata = read_image(Path('/path/to/image.nv12'))
sidecar json
{
"fileInfo": {
"format": "plain",
"height": 300,
"width": 400,
"imageLayout": "nv12"
}
}
After calling read_image, cxx-image-io provides a public API split_image_channels which helps to split to different colors channels, so that user can do the different processes on them. The function return type is a dictionary which contains the different color channel name as keys, and the value in numpy array of one single channel.
before calling write_image, cxx-image-io provides a public API merge_image_channels which helps to merge different colors channels to a numpy array buffer.
from cxx_image_io import read_image, split_image_channels, merge_image_channels, ImageLayout, ImageMetadata, PixelRepresentation, PixelType
import numpy as np
from pathlib import Path
rgb, metadata = read_image(Path('rgb_8bit.jpg'))
channels = split_image_channels(rgb, metadata)
# print(channels['r']) # Red channel in numpy array
# print(channels['g']) # Green channel in numpy array
# print(channels['b']) # Blue channel in numpy array
rgb_post = merge_image_channels(channels, metadata)
np.array_equal(rgb, rgb_post)
cfa, metadata = read_image(Path('bayer_16bit.plain16'))
channels = split_image_channels(cfa, metadata)
# print(channels['gr']) # Bayer Gr pixels in numpy array
# print(channels['r']) # Bayer R pixels in numpy array
# print(channels['b']) # Bayer B pixels in numpy array
# print(channels['gb']) # Bayer Gb pixels in numpy array
cfa_post = merge_image_channels(channels, metadata)
np.array_equal(cfa, cfa_post)
yuv, metadata = read_image(Path('raw.nv12'))
channels = split_image_channels(yuv, metadata)
# print(channels['y']) # Y plane in numpy array
# print(channels['u']) # U plane in numpy array
# print(channels['v']) # V plane in numpy array
yuv_post = merge_image_channels(channels, metadata)
np.array_equal(yuv, yuv_post)
write_image is able to write a numpy array to image file.
To write the pure numpy array to different image file extensions. User need to define the following fundamental parameters in ImageMetadata which is part of ImageWriter.Options. In order to call the specific C++ image libraries with them.
from cxx_image_io import ImageMetadata, ImageWriter, FileFormat, PixelType, ImageLayout
from cxx_image_io import write_image
import numpy as np
from pathlib import Path
metadata = ImageMetadata()
metadata.fileInfo.pixelType = PixelType.RGB
metadata.fileInfo.imageLayout = ImageLayout.INTERLEAVED
write_options = ImageWriter.Options(metadata)
assert isinstance(image, np.ndarray)
write_image(Path('/path/to/image.jpg'), image, write_options)
write_image can determine the image format by file extensions, but some formats don't not rely on a specific extension, for example the PLAIN format that allows to directly dump the image buffer to a file. In this case, the format can be specified through ImageWriter.Options.
metadata = ImageMetadata()
metadata.fileInfo.pixelType = PixelType.BAYER_GBRG
metadata.fileInfo.imageLayout = ImageLayout.PLANAR
write_options = ImageWriter.Options(metadata)
write_options.fileFormat = FileFormat.PLAIN
assert isinstance(image, np.ndarray)
write_image(Path('/path/to/image.plain16'), image, write_options)
metadata = ImageMetadata()
metadata.fileInfo.pixelType = PixelType.BAYER_GBRG # adapt with User's RAW Bayer pattern.
metadata.fileInfo.imageLayout = ImageLayout.PLANAR
metadata.fileInfo.pixelPrecision = 12
write_options = ImageWriter.Options(metadata)
assert isinstance(image, np.ndarray)
write_image(Path('/path/to/image.RAWMIPI12'), image, write_options)
metadata = ImageMetadata()
metadata.fileInfo.pixelType = PixelType.BAYER_GBRG # to adapt with User's RAW Bayer pattern.
metadata.fileInfo.imageLayout = ImageLayout.PLANAR
metadata.fileInfo.pixelPrecision = 10
write_options = ImageWriter.Options(metadata)
assert isinstance(image, np.ndarray)
write_image(Path('/path/to/image.RAWMIPI10'), image, write_options)
metadata = ImageMetadata()
metadata.fileInfo.pixelType = PixelType.YUV
metadata.fileInfo.imageLayout = ImageLayout.YUV_420
write_options = ImageWriter.Options(metadata)
write_options.fileFormat = FileFormat.PLAIN
assert isinstance(image, np.ndarray)
write_image(Path('/path/to/image.yuv'), image, write_options)
metadata = ImageMetadata()
metadata.fileInfo.pixelType = PixelType.YUV
metadata.fileInfo.imageLayout = ImageLayout.NV12
write_options = ImageWriter.Options(metadata)
write_options.fileFormat = FileFormat.PLAIN
assert isinstance(image, np.ndarray)
write_image(Path('/path/to/image.nv12'), image, write_options)
metadata = ImageMetadata()
metadata.fileInfo.pixelType = PixelType.BAYER_RGGB # adapt with User's RAW Bayer pattern.
metadata.fileInfo.imageLayout = ImageLayout.PLANAR
metadata.fileInfo.pixelPrecision = 12
write_options = ImageWriter.Options(metadata)
assert isinstance(image, np.ndarray)
write_image(Path('/path/to/image.dng'), image, write_options)
metadata = ImageMetadata()
metadata.fileInfo.pixelType = PixelType.RGB
metadata.fileInfo.imageLayout = ImageLayout.INTERLEAVED
write_options = ImageWriter.Options(metadata)
assert isinstance(image, np.ndarray)
write_image(Path('/path/to/image.jpg'), image, write_options)
metadata = ImageMetadata()
metadata.fileInfo.pixelType = PixelType.BAYER_RGGB # adapt with User's RAW Bayer pattern.
metadata.fileInfo.imageLayout = ImageLayout.PLANAR
metadata.fileInfo.pixelPrecision = 16
write_options = ImageWriter.Options(metadata)
assert isinstance(image, np.ndarray)
write_image(Path('/path/to/image.cfa'), image, write_options)
metadata = ImageMetadata()
metadata.fileInfo.pixelType = PixelType.GRAYSCALE
metadata.fileInfo.imageLayout = ImageLayout.PLANAR
metadata.fileInfo.pixelPrecision = 16
write_options = ImageWriter.Options(metadata)
assert isinstance(image, np.ndarray)
write_image(Path('/path/to/image.png'), image, write_options)
metadata = ImageMetadata()
metadata.fileInfo.pixelType = PixelType.BAYER_RGGB # adapt with User's RAW Bayer pattern.
metadata.fileInfo.imageLayout = ImageLayout.PLANAR
metadata.fileInfo.pixelPrecision = 16
write_options = ImageWriter.Options(metadata)
assert isinstance(image, np.ndarray)
write_image(Path('/path/to/image.tif'), image, write_options)
Some image formats, like JPEG and TIFF, support EXIF reading and writing.
If supported, EXIF can be read by calling read_exif and be written by calling write_exif.
from cxx_image_io import read_exif, write_exif
from pathlib import Path
exif = read_exif(Path('/path/to/image.jpg'))
print(exif)
write_exif(Path('path/to/new_image.jpg'), exif)
print(exif) will give the following output like:
{
'make': 'Canon',
'model': 'Canon EOS 40D',
'orientation': 1,
'software': 'GIMP 2.4.5',
'exposureTime': [1, 160],
'fNumber': [71, 10],
'isoSpeedRatings': 100,
'dateTimeOriginal': '2008:05:30 15:56:01',
'exposureBiasValue': [0, 1],
'focalLength': [135, 1]
}
user can use help(exif) to see the definition of ExifMetdata.
EXIF metadata can be read and written along with an image by specifying them in the ImageMetadata. In this case, the EXIF wil be read and written when calling read_image and write_image.
image, metadata = read_image(Path('/path/to/image.jpg'))
metadata.exifMetadata.make = 'Custom'
write_options = ImageWriter.Options(metadata)
write_image(Path('/path/to/image.jpg'), image, write_options)
This project has the dependencies of the following libraries by cmake FetchContent:
This project is licensed under the MIT License - see the LICENSE.md file for details.
FAQs
Image IO APIs for wide range image formats (jpg, png, tif, dng, bmp, yuv, nv12 and RAWs), support Exif, interact nicely with numpy array.
We found that cxx-image-io demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
PyPI confirms no security flaws were exploited in the Ultralytics supply chain attack and highlights improvements for safer package publishing.
Security News
Research
The Socket Research Team breaks down a malicious wrapper package that uses obfuscation to harvest credentials and exfiltrate sensitive data.
Research
Security News
Attackers used a malicious npm package typosquatting a popular ESLint plugin to steal sensitive data, execute commands, and exploit developer systems.