yupi examples

This repository contains a selection of examples to illustrate the usage of the python library yupi. Code examples are provided also with videos (in the cases where those are required) and camera calibration files.

Further description of yupi's API can be found in the official documentation.

Getting started

Installing required packages

To be able to execute the examples you first need to install yupi:

pip install yupi

Some of the examples are distributed as jupyter notebooks, so installing jupyter is also recommended:

pip install jupyter

Copying the examples

To get a local copy of the code examples and all the multimedia resources required just run:

git clone https://github.com/yupidevs/yupi_examples

Executing the examples

Depending on the example extension, you have to execute it using python directly or jupyter.

For the examples distributed as .py files, simply run:

python example_XXX.py

For the examples distributed as .ipynb files, run instead:

jupyter notebook intro_XXX.ipynb

This will open a browser window with the notebook.

Description of current examples

Examples are divided into two different categories: introductory tutorials and advanced examples. The first is designed to cover the very basics of yupi, while the later is designed to illustrate a more complex integration of yupi tools in order to reproduce the results of published research.

In this table you can easily find the examples that better suits you.

Filename	Related API functions	Description
intro_000.ipynb	Almost every yupi function :)	Showcases minimal examples of most of the yupi APIs in a jupyter notebook
intro_001.ipynb	yupi.Trajectory yupi.graphics.plot_2D	Creates a Trajectory using arrays of x and y, then plot it
intro_002.ipynb	yupi.graphics.plot_2D yupi.generators.RandomWalkGenerator	Generates a list of Trajectory objects and plot them all
intro_003.ipynb	yupi.tracking.ROI yupi.tracking.ObjectTracker yupi.tracking.TrackingScenario yupi.tracking.ColorMatching yupi.graphics.plot_2D	Extracts the trajectory of a blue ball inside a video of multiple balls and plots it
intro_004.ipynb	yupi.generators.LangevinGenerator yupi.graphics.plot_2D yupi.stats.speed_ensemble yupi.graphics.plot_speed_hist yupi.stats.turning_angles_ensemble yupi.graphics.plot_angles_hist yupi.stats.msd yupi.graphics.plot_msd yupi.stats.kurtosis yupi.graphics.plot_kurtosis yupi.stats.vacf yupi.graphics.plot_vacf yupi.stats.psd yupi.graphics.plot_psd	A general showcase of the stats and graphics modules.
intro_005.ipynb	yupi.Trajectory yupi.VelocityMethod yupi.WindowType	Details the differences among the available methods in yupi to estimate velocity
example_001.py	yupi.generators.LangevinGenerator yupi.graphics.plot_2D yupi.stats.speed_ensemble yupi.graphics.plot_speed_hist yupi.stats.turning_angles_ensemble yupi.graphics.plot_angles_hist yupi.stats.msd yupi.graphics.plot_msd yupi.stats.kurtosis yupi.graphics.plot_kurtosis yupi.stats.vacf yupi.graphics.plot_vacf	A simulation of the statistical properties for the motion of a lysozyme molecule in water. Several molecule trajectories are generated and later analyzed.
example_002.py	yupi.generators.DiffDiffGenerator yupi.stats.collect yupi.graphics.plot_hists	A model framework of a diffusion process with fluctuating diffusivity is presented.
example_003.py	yupi.graphics.plot_2D yupi.tracking.ROI yupi.tracking.ObjectTracker yupi.tracking.TrackingScenario yupi.tracking.ColorMatching yupi.tracking.TemplateMatching yupi.Trajectory (operations on Trajectory objects)	Tracking a scaled-size rover wheel moving over sand. The position is subsequently compared to the ideal position assuming it does not slip or sink.
example_004.py	yupi.graphics.plot_2D yupi.tracking.ROI yupi.tracking.ObjectTracker yupi.tracking.TrackingScenario yupi.tracking.ColorMatching yupi.tracking.RemapUndistorter	Tracking an intruder while penetrating a granular material in a quasi 2D enviroment.
example_005.py	yupi.graphics.plot_2D yupi.tracking.ROI yupi.tracking.CameraTracker yupi.tracking.ObjectTracker yupi.tracking.TrackingScenario yupi.tracking.ColorMatching yupi.tracking.RemapUndistorter	Simultaneous tracking of an ant and the camera capturing its movement with the reconstruction of the trajectory of the ant respect its initial position.
example_006.py	yupi.graphics.plot_2D yupi.tracking.ROI yupi.tracking.ObjectTracker yupi.tracking.TrackingScenario yupi.tracking.ColorMatching yupi.tracking.FrameDifferencing yupi.tracking.BackgroundEstimator yupi.tracking.BackgroundSubtraction yupi.tracking.TemplateMatching yupi.tracking.OpticalFlow	A comparison of different tracking methods over the same input video where the camera is fixed at a constant distance from the plane where an ant moves.
example_007.ipynb	yupi.core.JSONSerializer yupi.graphics.plot_2d	Inspection and processing of HURDAT2, a hurricane dataset provided by The National Hurricane Center and Central Pacific Hurricane Center
example_008.ipynb	yupi.core.JSONSerializer yupi.graphics.plot_3d yupi.grpahics.plot_angle_hist yupi.stats.collect	Inspection of the dataset presented in this article. This example reproduces some of the figures of the original paper focusing on showcasing yupi API for data processing and visualization for the case of 3D trajectories.