Diffeomorphic

Overview

Diffeomorphic implements diffeomorphic transformations for image and video morphing, as described in:

Stojanoski, B., & Cusack, R. (2014). Time to wave good-bye to phase scrambling: Creating controlled scrambled images using diffeomorphic transformations. Journal of Vision, 14(12), 6. doi:10.1167/14.12.6

This Python package was developed by Mohammad Ahsan Khodami, based on the original algorithms described in the paper by Stojanoski & Cusack.

Installation

pip install diffeomorphic

Usage

As a command-line tool

# Transform a single image
diffeomorphic-image --input image.jpg --output output_dir --maxdistortion 80 --nsteps 20

# Transform a video
diffeomorphic-movie --input video.mp4 --output output_dir --maxdistortion 60 --nsteps 20

# Transform with warpshift
diffeomorphic-warpshift --input image.jpg --output output_dir --maxdistortion 60 --nsteps 20 --phasedrift 0.39

As a Python library

import diffeomorphic

# Transform a single image
diffeomorphic.transform_image(
    input_path="image.jpg", 
    output_path="output_dir",
    max_distortion=80,
    n_steps=20
)

# Transform a video
diffeomorphic.transform_movie(
    input_path="video.mp4", 
    output_path="output_dir",
    max_distortion=60,
    n_steps=20
)

# Transform with warpshift
diffeomorphic.transform_warpshift(
    input_path="image.jpg", 
    output_path="output_dir",
    max_distortion=60,
    n_steps=20,
    phase_drift=0.39
)

Features

• Diffeomorphic transformation of images for experimental stimuli
• Video processing capabilities with frame-by-frame transformations
• WarpShift transformations with phase drift control
• Adjustable distortion parameters for experimental control
• Both command-line and Python API interfaces
• Implements peer-reviewed methods from vision science literature

Applications

Diffeomorphic transformations are particularly useful in vision and cognitive psychology research for:

• Creating controlled distortions of visual stimuli
• Generating stimulus sets with precise degrees of degradation
• Studies on object recognition and visual perception
• Neuroimaging experiments requiring parametric manipulation of visual stimuli
• Creating stimuli for investigating the visual system's response to distortion

License

This project is licensed under the MIT License - see the LICENSE file for details.