imageio 2.37.4: read and write PNG images with imageio.v3

# imageio.v3 PNG read and write API

This sample pins `imageio` 2.37.4 and demonstrates encoding and decoding PNG images using `imageio.v3.imread` and `imageio.v3.imwrite`.

The contract verifies:
- `imageio.v3.imwrite("<bytes>", img, extension=".png")` writes RGB NumPy ndarrays into PNG byte buffers with valid PNG magic header bytes.
- `imageio.v3.imread(png_bytes, extension=".png")` decodes PNG bytes back into NumPy ndarrays with matching shape, uint8 dtype, and identical pixel values.
- `imageio.v3.imwrite` and `imageio.v3.imread` support in-memory `io.BytesIO` binary streams.
- `imageio.v3.imwrite` and `imageio.v3.imread` support 2D single-channel grayscale image arrays.
- `imageio.v3.imread` raises an exception (`ValueError`, `RuntimeError`, or `OSError`) on corrupted or invalid input byte sequences.

Clean-room public code sample — generation instructions

Write a brand-new, minimal, self-contained code sample in this clean-room directory.
Do not copy, paraphrase, or reference any existing project source. Work only from this spec.

A csx.json manifest scaffold already exists. Do not recreate it from memory. Preserve its case.goal, packages and symbols; fill its empty case.contract with exact assertions and correct its environment, commands and verifierAdapter for the files you generate.

Goal: read and write PNG images with imageio.v3
Kind: HOW

Use EXACTLY these public packages and versions:
  - pkg:pypi/imageio@2.37.4
Demonstrate these symbols/APIs:
  - imageio.v3.imread
  - imageio.v3.imwrite

Rules:
  - One focused purpose; the smallest project that proves the goal.
  - Include a contract test (test/contract.*) that runs OFFLINE and exits 0 exactly when the goal behavior works.
  - Pin every dependency with a lockfile so resolution is reproducible.
  - No secrets, credentials, or tokens. No real URLs (only example.com or localhost). No absolute paths.
  - No personal names, emails, company names, or project identifiers of any kind.
  - No binaries and no generated output (node_modules, dist, target, venv, .git, .env).
  - Keep it under 200 files and 256KB packed.

{"case":{"caseId":"case:sha256:655bc30f6ce2a19123287536715e110df4d3f097bf96d0563ea11b3260eda6f6","contract":["imageio.v3.imwrite(\"\u003cbytes\u003e\", img, extension=\".png\") encodes an RGB NumPy ndarray into PNG formatted bytes starting with the PNG signature.","imageio.v3.imread(bytes, extension=\".png\") parses PNG encoded bytes into a NumPy ndarray with matching shape, uint8 dtype, and identical pixel values.","imageio.v3.imwrite and imageio.v3.imread read and write image data to and from in-memory io.BytesIO streams.","imageio.v3.imwrite and imageio.v3.imread handle 2D single-channel grayscale image arrays without losing pixel values or dimensions.","imageio.v3.imread raises an exception (ValueError, RuntimeError, or OSError) when given corrupted or invalid image bytes."],"goal":"read and write PNG images with imageio.v3","kind":"HOW","packages":["pkg:pypi/imageio@2.37.4"],"schemaVersion":1,"symbols":["imageio.v3.imread","imageio.v3.imwrite"]},"contractCommand":["python","test/contract.py"],"environment":{"arch":"x64","distro":"ubuntu","ecosystem":"pypi","libc":"glibc","libcVersion":"2.39","os":"linux","osVersionBucket":"24","packageManager":"pip","schemaVersion":1},"license":"MIT-0","packages":["pkg:pypi/imageio@2.37.4"],"schemaVersion":1,"subject":"pkg:pypi/imageio@2.37.4","symbols":["imageio.v3.imread","imageio.v3.imwrite"],"verifierAdapter":"python@1"}

imageio==2.37.4
numpy==2.5.2
pillow==12.3.0

{
  "schemaVersion": 1,
  "goal": "read and write PNG images with imageio.v3",
  "kind": "HOW",
  "packages": [
    "pkg:pypi/imageio@2.37.4"
  ],
  "symbols": [
    "imageio.v3.imread",
    "imageio.v3.imwrite"
  ]
}

import io
import numpy as np
import imageio.v3 as iio

def test_rgb_write_and_read():
    # 1. Verify imageio.v3.imwrite("<bytes>", img, extension=".png") produces valid PNG bytes
    img_rgb = np.zeros((10, 10, 3), dtype=np.uint8)
    img_rgb[0:5, 0:5] = [255, 0, 0]    # Red block
    img_rgb[5:10, 5:10] = [0, 255, 0]  # Green block

    png_bytes = iio.imwrite("<bytes>", img_rgb, extension=".png")
    assert isinstance(png_bytes, bytes), f"Expected bytes, got {type(png_bytes)}"
    assert len(png_bytes) > 0, "Expected non-empty byte buffer"
    # PNG signature: 89 50 4E 47 0D 0A 1A 0A
    assert png_bytes.startswith(b"\x89PNG\r\n\x1a\n"), "Expected PNG magic header bytes"

    # 2. Verify imageio.v3.imread(bytes, extension=".png") parses back identical image array
    decoded_img = iio.imread(png_bytes, extension=".png")
    assert isinstance(decoded_img, np.ndarray), f"Expected np.ndarray, got {type(decoded_img)}"
    assert decoded_img.shape == (10, 10, 3), f"Expected shape (10, 10, 3), got {decoded_img.shape}"
    assert decoded_img.dtype == np.uint8, f"Expected dtype uint8, got {decoded_img.dtype}"
    assert np.array_equal(decoded_img, img_rgb), "Decoded image array pixels must match original"

def test_bytesio_stream():
    # 3. Verify imageio.v3.imwrite and imread with io.BytesIO stream
    img_rgb = np.full((12, 12, 3), 100, dtype=np.uint8)
    stream = io.BytesIO()
    iio.imwrite(stream, img_rgb, extension=".png")
    
    stream.seek(0)
    read_stream_img = iio.imread(stream, extension=".png")
    assert isinstance(read_stream_img, np.ndarray)
    assert read_stream_img.shape == (12, 12, 3)
    assert np.array_equal(read_stream_img, img_rgb)

def test_grayscale_image():
    # 4. Verify 2D grayscale image write and read
    img_gray = np.full((16, 16), 180, dtype=np.uint8)
    gray_bytes = iio.imwrite("<bytes>", img_gray, extension=".png")
    read_gray = iio.imread(gray_bytes, extension=".png")
    assert isinstance(read_gray, np.ndarray)
    assert read_gray.shape == (16, 16)
    assert read_gray.dtype == np.uint8
    assert np.array_equal(read_gray, img_gray)

def test_corrupted_input_error():
    # 5. Verify exception raised on invalid image bytes
    corrupted_data = b"NOT_A_VALID_PNG_STREAM_DATA"
    try:
        iio.imread(corrupted_data, extension=".png")
        raise AssertionError("Expected an exception when decoding corrupted PNG bytes")
    except (ValueError, RuntimeError, OSError, IOError):
        pass

def main():
    test_rgb_write_and_read()
    test_bytesio_stream()
    test_grayscale_image()
    test_corrupted_input_error()
    print("CONTRACT PASS: imageio.v3 PNG read/write verified offline")

if __name__ == "__main__":
    main()