ntt

ntt is a Python module that provides simple and consistent interfaces for common image and video processing tasks. It wraps around popular Python libraries to simplify their usage and make them interchangeable, to build complex pipelines. In particular:

• Pillow – image file handling
• OpenCV – computer vision, image and video processing
• imageio – read/write images and videos
• scikit-image – scientific image processing
• NumPy – arrays and calculations

Installation

Using venv (recommended)

1. Create a virtual environment:

python -m venv venv

2. Activate the environment:

• On macOS/Linux:

source venv/bin/activate

• On Windows:

venv\Scripts\activate

3. Install the module:

The module is available on Pypi:

pip install ntt

Or install the development version from source:

git clone
pip install -e .

Tests

import ntt
print(ntt.__version__)  # Check the version

Assuming you have cloned the repository or installed the source package, you can run tests with pytest:

$ pytest tests

Samples

To download the data samples (videos, images, sounds, etc.) used in tests and examples, clone the repository and update the .env file with the path to the cloned folder:

git clone https://github.com/centralelyon/ntt-samples.git

Alternatively, you can generate fake videos samples by running the following script:

from ntt.videos.video_generation import random_video

video = random_video(320, 240, 10, 2)

Building pipelines

An interesting use of ntt is to build complex pipelines for video and image processing. For that, we also built a separate tool, the Pipeoptz library, which provides a simple way to create and manage pipelines of functions.

The image above is generated using the code below available as a gist.

import random

from ntt.frames.frame_generation import random_frame
from ntt.frames.display import display_frame
from pipeoptz import Pipeline, Node

def random_number():
    num = random.randint(100, 600)
    return num

pipeline = Pipeline("Simple Pipeline", "Generate a random image.")

node_gen_width = Node("GenWidth", random_number) 
node_gen_height = Node("GenHeight", random_number)
node_random_frame = Node(
    "random_frame", random_frame, fixed_params={"width": 10, "height": 3}
)

pipeline.add_node(node_gen_width)
pipeline.add_node(node_gen_height)
pipeline.add_node(
    node_random_frame, predecessors={"width": "GenWidth", "height": "GenHeight"}
)

outputs = pipeline.run()
display_frame(outputs[1][pipeline.static_order()[-1]])

Examples

You may look at the examples folder to see how to use ntt functions. Also a look a the tests folder to see how functions are tested. And of course, the documentation at https://ntt.readthedocs.io.

Assuming you have a crop.mp4  video in a samples folder and an output folder, here is how to use extract_first_frame function.

At the command line you can now use the corresponding helper as well:

python -m ntt extract_first_frame samples/crop.mp4   # prints saved path

import os
from dotenv import load_dotenv
from ntt.frames.frame_extraction import extract_first_frame

if __name__ == "__main__":
    load_dotenv()

    output = extract_first_frame(
        video_path_in=os.environ.get("NTT_SAMPLES_PATH"),
        video_name_in="crop.mp4",
        frame_path_out=os.environ.get("PATH_OUT"),
        frame_name_out="crop-ex.jpg",
    )

    print(f"Frame successfully extracted at {output}") if output is not None else print(
        "Frame extraction failed"
    )

GitHub Actions

The project is configured to run tests on GitHub Actions. The configuration file is .github/workflows/tests.yml.

Docker

A Dockerfile is provided to quickly set up an environment with all system dependencies (OpenCV, FFmpeg, etc.) and run tests or scripts.

Build the image

docker build -t ntt .

To rebuild the image without cache (for example to test changes in the Dockerfile), run:

docker build --no-cache -t ntt .

Run tests

By default, running the container executes the pytest test suite:

# Run tests using the code inside the container
docker run --rm ntt

During development, you can mount your local directory to run tests on your current code:

# Linux / macOS / Windows PowerShell
docker run --rm -v ${PWD}:/app ntt

# Windows Command Prompt (cmd)
docker run --rm -v "%cd%:/app" ntt

Run a custom script

You can override the default command to run a specific Python script:

docker run --rm -v ${PWD}:/app ntt python tests/test_random_strings.py

Example scripts

The scripts/ folder contains small end-to-end examples that can all be run in one Docker command. The image examples write files through ntt.frames.io.write, and the video example writes files through ntt.videos.io.write. The Pipeoptz example uses the pipeoptz development dependency that is included in the Docker image.

docker run --rm -v ${PWD}:/app ntt python /app/scripts/example_generate_random_image.py /app/output/random_image.jpg
docker run --rm -v ${PWD}:/app ntt python /app/scripts/example_generate_video_and_extract_first_frame.py /app/output
docker run --rm -v ${PWD}:/app ntt python /app/scripts/example_generate_and_stitch_perspective_videos.py /app/output/perspective_stitch_demo
docker run --rm -v ${PWD}:/app ntt python /app/scripts/example_flatdir_exif.py /app/output --output /app/output/files_with_exif.json
docker run --rm -v ${PWD}:/app ntt python /app/scripts/example_pipeoptz_transform_pipeline.py /app/output/pipeoptz_transform_pipeline.jpg --dag-output /app/output/pipeoptz_transform_pipeline_dag.png --no-display
docker run --rm -v ${PWD}:/app ntt python /app/scripts/generate_pipeoptz_script_gallery.py /app/output/pipeoptz_script_gallery

The Flatdir example requires flatdir and creates a JSON file index enriched with EXIF data extracted by ntt. The Pipeoptz example recreates the transform_frame() workflow as a pipeline with separate resize, grayscale, and annotate nodes, writes the final frame, and can also render the pipeline DAG as .dot + .png. The gallery generator renders one Pipeoptz DAG per script in scripts/, plus one overview image and a JSON manifest.

You can also run those examples from VS Code:

This repository includes VS Code tasks in .vscode/tasks.json for the Docker build and for each example script.

In VS Code:

1. Open Terminal > Run Task.
2. Run docker-build-ntt to build the image.
3. Run any example task such as docker-run-example-extract-exif-from-image.

Each example task runs the matching script in Docker with the workspace mounted at /app, so outputs are written to the local output/ folder.

To rebuild the image without cache (for example to test changes in the Dockerfile), run:

Run in interactive mode

To explore the container or run multiple commands manually, start a bash shell:

docker run --rm -it -v ${PWD}:/app ntt bash

Examples of commands to run inside the container:

# Run tests
pytest
# Run a script
python /app/scripts/example_generate_random_image.py /app/output/random_image.jpg

The python version in the container is 3.13 and you can check the versions of the dependancies in the Dockerfile.

License

This project is licensed under the MIT License. See the LICENSE file.

Acknowledgments