Read and write images, videos and cameras

Every image in PixelFlow is a NumPy array of shape (height, width, 3), uint8, in RGB order. The functions on this page read files, bytes, videos and cameras into that form, and write it back. OpenCV, which does the decoding and encoding, uses BGR; the conversion happens here, so the rest of your code never deals with it.

Images

Python
import pixelflow as pf

image = pf.read_image("street.jpg")
print(image.shape, image.dtype)

pf.save_image("street.png", image)
Text only
(1280, 1920, 3) uint8

read_image takes a path, the bytes of an encoded image, or an array:

You pass read_image
a path (str or Path) decodes the file
bytes, such as an upload or a database blob decodes them in memory
a NumPy array checks it is RGB uint8 HxWx3 and returns it as it is

Grayscale images come back with three channels, and an alpha channel is dropped (with a warning). A photo whose EXIF data says it was taken rotated comes back upright, as a photo viewer shows it.

An array is taken to be RGB already: its channel order cannot be checked. An array from cv2.imread is BGR, so pass the path to read_image instead.

save_image picks the format from the extension. To send an image without writing a file, for example as an HTTP response, encode_image returns the encoded bytes:

Python
data = pf.encode_image(image, ".jpg")

Videos

VideoReader gives the frames of a video file one by one; VideoWriter writes them to a new file:

Python
import pixelflow as pf

video = pf.VideoReader("crowd.mp4")
print(video)

with pf.VideoWriter("crowd-small.mp4", like=video) as writer:
    for frame in video:
        frame = pf.transform.resize(frame, width=640)
        writer.write(frame)
Text only
VideoReader('crowd.mp4', 1280x720, 25.00fps, 341 frames)

like=video gives the writer the reader's frame rate. Pass fps= instead when there is no reader, such as for frames you generate. The writer takes its width and height from the first frame you write, so the loop can resize frames, as above. Every frame after that must be the same size, or write raises a ValueError.

Use the writer in a with block, or call writer.close() at the end: the file is not complete until it is closed.

The reader tells you what it reads:

Attribute
width, height size of the frames, in pixels
fps frames per second, or None if the file does not say
frames number of frames, estimated from the file: good for a progress bar, not exact
duration length in seconds
codec the video's codec, such as "h264"

To work on fewer frames, stride=5 gives every 5th frame. fps and frames are divided to match, so a writer made with like= plays the result at the right speed: for the video above, 69 frames at 5 fps instead of 341 at 25. start=300 starts at frame 300, and seek(0) goes back to the beginning; looping over the reader again does not.

Cameras and streams

CameraStream reads a webcam by its number, or a network stream by its URL, with the same loop:

Python
import pixelflow as pf

with pf.CameraStream(0) as camera:
    with pf.VideoWriter("camera.mp4", fps=30) as writer:
        for frame in camera:
            writer.write(frame)

Most cameras do not report their frame rate (camera.fps is None), so give the writer fps= yourself. A stream has no end and no length: the loop runs until you stop it.

Show frames in a window

display_video shows one frame in a window and returns at once, so it goes inside the loop. Pressing q closes the window and raises pf.DisplayExit, which ends the loop:

Python
import pixelflow as pf

try:
    for frame in pf.VideoReader("crowd.mp4"):
        pf.display_video(frame, width=960)
except pf.DisplayExit:
    pass

width shrinks only what is shown. display_image(image) shows a single image and waits for a key; close_display() closes every window.

PIL images

to_pil(image) turns an array into a PIL image, and from_pil(pil_image) turns a PIL image into an RGB array:

Python
from PIL import Image

image = pf.from_pil(Image.open("logo.png"))

Whatever the PIL image's mode, the array is RGB uint8 with three channels, as with read_image: grayscale gets three channels, and an alpha channel is dropped with a warning.