## Manuel de PyMecaVideo

### Georges Khaznadar

Résumé

PyMecaVideo est un logiciel facilitant le repérage de points mobiles dans une vidéo et d'en exploiter la cinématique pour des usages de mesure physique.

## PyMecaVideo, pourquoi faire?

Il est possible de faire des mesures physiques à l'aide d'images, dans certaines conditions. PyMecaVideo facilite les mesures physiques faites sur des séquences d'images vidéo. Il suffit de travailler à partir d'un fichier vidéo de type `AVI`, encodé à l'aide d'un codec libre[1], qui comporte au moins une image dont on peut déterminer l'échelle.

PyMecaVideo permet d'ouvrir et de décomposer en images la vidéo, et par des pointages successifs, de suivre le mouvement d'un point, et éventuellement le mouvement de l'origine d'un référentiel mobile dans le cadre des images. Les données pointées sont ensuite exploitables à l'aide de logiciels d'analyse standard.

## Téléchargement et installation

Les sources de PyMecaVideo sont disponibles parmi les Outils Physiques Pour Linux hébergés sur le site tuxfamily.org. Pour l'installation sous Linux, récupérer l'arbre des sources comme expliqué à la page d'accueil du projet, entrer dans le répertoire `pymecavideo/trunk`, et taper la commande suivante : `python setup.py install`. Cela met en place les modules nécessaires pour python. Activer l'attribut exécutable du fichier `pymecavideo`, par exemple en tapant la commande `chmod +x pymecavideo`, puis copier ce fichier dans une place où celui-ci sera facile à lancer en tant que commande. La liste des répertoires accessibles pour lancer une commande peut être obtenue en tapant `echo $PATH`.

Il est possible aussi d'obtenir des fichiers binaires, qui sont pris en charge par le gestionnaire de paquets de votre distribution préférée. Actuellement on trouve des paquets RPM et DEB.

Les paquets pour Debian et Ubuntu sont maintenus dans le dépôt debian de l'association OFSET. Les instructions de téléchargement sont expliquées dans la page d'accueil du dépôt.

## Lancement de PyMecaVideo

Il est possible de lancer PyMecaVideo de diverses façons : en ligne, on peut taper `pymecavideo` ou `pymecavideo nom_de_fichier_video.avi`. On peut aussi le lancer à partir du menu graphique de votre gestionnaire de fenêtre : KDE et Gnome intègrent l'application dans le menu si vous faites une installation à l'aide d'un paquet.

Dans le cas de KDE,

  l'application devrait être accessible par les menus Éducatif->Science->PyMecaVideo.

Dans le cas de Gnome,

  l'application devrait être accessible par les menus Éducation->PyMecaVideo.

Voici l'icône de l'application:

## Préparer une vidéo pour pouvoir la traiter

La préparation de la vidéo commence dès la prise de vues. Les points-clés sont les suivants:

- Choisir un bon éclairage. Les éclairages fluorescents posent parfois problème, car leur intensité varie très rapidement, et cela peut donner quelquefois naissance à des phénomènes stroboscopiques. D'autre part, pour les caméras vidéo disposant de bons automatismes, un éclairage suffisant facilite le choix de temps de pose courts, qui sont favorables à l'acquisition de données.

- La scène doit posséder un bon contraste. En particulier les points à suivre doivent se distinguer aisément par valeur, sinon par la couleur, de leur environnement.

- Il faut penser à laisser un objet de taille connue, dans le même plan focal que la scène qui sera filmée. Il est bon de documenter la dimension de l'objet-étalon.

- L'axe optique de la caméra doit être perpendiculaire au plan dans lequel se déplace l'objet étudié. Il doit pointer environ vers le milieu de la trajectoire probable.

- On commence à filmer avant l'évènement, on arrête après l'évènement. Il est préférable de fixer le début et la fin de la séquence vidéo à l'étape de montage.

- Utiliser un logiciel libre de montage, et couper la séquence pertinente. Quelques dizaines d'images au plus suffisent. La choix d'un logiciel libre assure que les codecs utilisés ne poseront pas de problème à l'avenir. Exemples de logiciels utilisables : Kino, Cinelerra. La vidéo sera enregistrée dans un conteneur au format `.avi`.

## Utilisation de PyMecaVideo

Il faut bien sûr commencer par charger une vidéo avant de pouvoir en faire quoi que ce soit. Ça peut se faire au lancement de la commande, en tapant en ligne de commande: `pymecavideo nom_de_fichier_video.avi`, ou en mode graphique quand PyMecaVideo est lancé, par le menu Fichier->Ouvrir une vidéo, ou encore si on veut une des vidéos d'exemple, par le menu Aide->Exemples ...

### Régler l'échelle

Quand on dispose d'un fichier vidéo ouvert, le bouton Définir l'échelle est actif, mais la valeur de l'échelle est encore indéfinie. On peut utiliser le curseur ou le champ de numéro d'image pour faire apparaître une image autre que la première de la séquence vidéo. Il faut que l'objet étalon soit dans le champ, et il faut connaître sa longueur en mètre.

On clique alors sur ce bouton, on renseigne la longueur de l'objet-étalon dans le dialogue qui surgit (on utilise la virgule ou le point comme séparateur décimal, indifféremment: par exemple 0,60 m pour signifier 60 cm), on valide, puis lorsque le curseur de la souris devient une crois de Malte, on réalise un tirer-glisser d'une extrémité à l'autre de l'objet-étalon.

Quand l'échelle est définie, c'est pour toute l'acquisition de données. En cas d'erreur, on peut tout réinitialiser à l'aide du bouton Tout réinitialiser

### Choix du nombre de points à étudier

Par défaut, on étudie le mouvement d'un seul point, le référentiel étant celui de la caméra.

Il est possible de faire porter l'étude sur deux points ou plus. Un des points de la série pourra plus tard être utilisé comme nouvelle origine du référentiel à volonté.

Pour étudier plus d'un point, il faut modifier la valeur affichée dans la boîte intitulée Nombre de points à étudier

### Pointer les positions

On peut décider de ne pas commencer le pointage dès la première image. Dans ce cas, il faut choisir manuellement l'image initiale à l'aide du curseur en haut à gauche, ou du champ de sélection de numéro d'image. Le pointage commence quand on clique sur le bouton Démarrer l'acquisition.

Quand l'acquisition est en cours, une petite phrase au-dessus de la vidéo rappelle le numéro du point qu'on est censé cliquer en suivant. Les traces des points cliqués dans les images précédentes de la vidéo apparaissent en couleurs. Les couleurs doivent se suivre sans discontinuité, sinon c'est la marque d'une faute de pointage.

#### Défaire et refaire

Les icônes défaire et refaire permettent éventuellement de rattraper une faute de pointage quand celle-ci est reconnue.

Il n'est possible de refaire des pointages antérieurs que tant qu'on n'a apporté aucune modification aux pointages précédemment défaits. Dès qu'un des pointages est corrigé à l'aide de la souris sur la vidéo, les pointages suivants disparaissent de la liste à refaire, et le bouton refaire est aussitôt inactivé (grisé).

Il est possible d'arrêter le pointage à tout moment, éventuellement avant la fin de la séquence vidéo.

### Enregistrer le travail

Après que des points aient été repérés, il devient possible d'enregistrer le travail grâce au menu Fichier->Enregistrer les données. On choisit alors un fichier de type `.csv`, `.dat`,`.txt` ou `.asc`[2]

NB:en même temps que le fichier que vous choisissez est enregistré, un autre le sera automatiquement. Si vous choisissez par exemple d'enregistrer un fichier de nom `data.csv`, un autre fichier de nom `data.csv.mecavideo` sera enregistré. Voici les caractéristiques de ces deux fichiers:

- Le fichier choisi explicitement (de nom `data.csv` par exemple) contient les données en unités seconde pour le temps et mètre pour les distances. C'est ce fichier qui est pertinent pour un traitement des données physiques à l'aide de logiciels d'analyse.

- Le fichier créé en plus (de nom `data.csv.mecavideo` pour l'exemple) contient des données différentes : ce sont uniquement des nombres entiers pour les positions, c'est à dire qu'on enregistre les lieux des pointages en unité pixel. De plus, les données permettant de reconstituer l'échelle font partie de ce fichier. Ce dernier fichier est plutôt destiné à l'usage interne de l'application.

### Le volet des trajectoires

Quand les pointages sont faits, il est intéressant d'activer le volet des trajectoires. Celui-ci permet d'attirer l'attention plus précisément sur le mouvement et la vitesse des objets étudiés, en faisant apparaître ceux-ci sans la vidéo où on les avait capturés.

#### Représentation absolue ou relative

Sitôt que plus d'un point fait partie de l'étude, il est possible de faire afficher les positions et les vitesses de plusieurs façons: soit les positions et les vitesses absolues, c'est-à-dire relatives au référentiel de la caméra, soit les positions et les vitesses relatives par rapport à un des points étudiés, choisi comme origine d'un nouveau référentiel.

#### L'échelle pour les vecteurs vitesse

L'échelle des vecteurs vitesse se règle à l'aide d'une zone de saisie intitulée Échelle de vitesses. Modifiez sa valeur et appuyez sur la touche Entrée pour obtenir une autre taille des vecteurs vitesse.

### Les préférences de PyMecaVideo

Par le menu Édition -> Préférences ont fait apparaître un menu pour les valeurs préférées, qui seront réutilisées lors de lancements successifs de PyMecaVideo. Parmi ces préférences figurent

- L'échelle des vitesses;

- La façon d'afficher les vecteurs vitesse: soit partout, soit au voisinage du pointeur de souris quand on l'approche des points;

- L'afficheur vidéo à utiliser pour visualiser les vidéos de synthèse: vlc, xine ou mplayer ... tous des visionneurs que Pymecavideo peut contrôler par une ligne de commande;

- Le niveau de verbosité pour le débogage si un comportement anormal de PyMecaVideo vous gène, augmenter la valeur de ce niveau permet éventuellement d'intercepter des messages informatifs au sujet du déroulement du programme. Ces messages peuvent éventuellement servir pour prendre contact utilement avec les auteurs de PyMecaVideo et signaler un dysfonctionnement.

### Créer une vidéo de synthèse

Dans le volet des trajectoire, on trouve deux boutons commandant la fabrication d'une vidéo de synthèse, qui permet de revoir le film tel qu'il aurait été si la caméra avait été solidaire du point sélectionné comme origine du référentiel.

Le bouton du dessous (Vidéo normale .. par défaut) sert à spécifier un déroulement normal pour la vidéo de synthèse, ou un ralenti par un facteur numérique de 2, 4 ou 8. Le bouton du dessus Vidéo calculée déclenche un calcul assez long, la génération de la vidéo de synthèse. Dès que cette vidéo est calculée, on la voit apparaître en boucle dans une nouvelle fenêtre. Le logiciel utilisé pour afficher cette vidéo est vlc, xine ou mplayer selon le choix réalisé dans les préférences de PyMecaVideo.

#### Exemple de vidéo de synthèse

Les vidéos de synthèse sont intéressantes quand on choisit comme origine de référentiel un point qui se déplace en ligne droite à vitesse constante.

Par exemple, on peut étudier simultanément deux points, dans une vidéo d'un cycliste laissant tomber un objet: un point du cadre du vélo (P1) et un point de l'objet qui tombe (P2). Dans le référentiel terrestre, celui de la caméra si on est en plan fixe, la trajectoire de P2 est une parabole. Mais dans le référentiel galiléen d'origine P1, le point P2 est en chute libre sans vitesse initiale.

Dans ces circonstances, la vidéo de synthèse obtenue après avoir choisi de représenter le volet des trajectoires à partir de l'origine P1 montre bien une chute libre.

NB.: quand on choisit de réaliser une vidéo de synthèse, il faut garder présent à l'esprit que les images seront en fait découpées à l'intérieur des images déjà existantes. Il faut donc éviter de traiter des images où le point qui utilisé comme origine se trouve trop près d'un bord de l'image, parce que ça diminue la taille du gabarit de découpe utilisé pour produire la vidéo de synthèse.

### Le volet des coordonnées

Le troisième et dernier volet de PyMecaVideo est le volet des coordonnées. Il présente un tableau dont la première colonne représente des dates en seconde, et les suivantes des coordonnées en mètre des points étudiés. Ce tableau est juste là pour démystifier le fonctionnement de PyMecaVideo, montrer qu'il ne s'agit que de traitement numérique.

Cependant, ce volet des coordonnées est le lieu utile pour envoyer les données de PyMecaVideo vers d'autres applications qui serviront à les analyser.

### Exporter des données vers d'autres applications

Le bouton Copier les données vers le presse-papiers permet d'exporter la totalité du tableau vers le presse-papiers. De même, il suffit de sélectionner (de mettre en surbrillance) une partie du tableau pour que cette partie soit automatiquement copiée vers le presse-papiers. La partie sélectionnée peut aussi être tirée-glissée vers d'autres applications. Si ces applications sont capables de récupérer les données et d'en faire usage, elles accepteront l'exportation. C'est le cas des traitements de texte et des tableurs les plus courants.

## Les logiciels de traitement des données

Le volet « coordonnées » de Pymecavideo permet des exportation automatiques vers divers logiciels de traitement de données, en plus du simple export vers le presse-papiers. Les exportations automatiques permettent l'ouverture des logiciels choisis, avec les données prêtes à l'utilisation. Le tableau suivant signale les logiciels supportés, ainsi que leur disponibilité sous GNU/Linux et sous Windows™.

Tableau 1. Logiciels libres de traitement des données

Logiciel |  |  | Description
--- | --- | --- | ---
OpenOffice.org Calc |  |  | Un tableur plutôt destiné à la bureautique, mais déjà connu par de nombreuses personnes
Qtiplot |  |  | Un véritable outil de traitement de données, très riche en fonctionnalités
SciDavis |  |  | Un autre outil de traitement de données, aussi riche en fonctionnalités

## Comment contribuer

- En rapportant les bogues aux auteurs. Celles-ci peuvent être de diverses natures : disfonction du logiciel, mauvaise présentation de l'interface, souhait d'amélioration, etc.

  Dans chaque cas, soyez très précis : un rapport de bogue ne permet à l'auteur de réagir que si celui-ci donne une description détaillée. Aussi, n'hésitez pas à jeter un coup d'œil dans les sources du logiciel : vous les avez à disposition ! en fait, plus d'un contributeur s'est déjà joint aux auteurs, à l'occasion d'un rapport de bogue, pour lequel il apportait la solution (une modification de la source).

  Les sources de Pymecavideo sont en langage Python, et en général assez bien commentées pour être largement compréhensibles.

- Pubiez des vidéos pédagogiques sous licences libres ! Les vidéos déjà utilisables ne manquent pas, mais beaucoup d'entre elles sont publiées sans que leur licence permette vraiment de les réutiliser librement.

  Notez bien qu'une vidéo sans licence, en droit français, appartient à son auteur et ne peut pas être redistribuée sans son consentement écrit.

- Une liste de diffusion permet d'échanger des idées de façon constructive, abonnez vous à `<pymecavideo@lists.tuxfamily.org>`

## A. Notice légale concernant PyMecaVideo

## Auteurs

2007-2010, Jean-Baptiste Butet `<ashashiwa@gmail.com>` : initiateur du projet PyMecaVideo

2008-2010, Georges Khaznadar `<georgesk@ofset.org>` : contribution, empaquetage Debian

2008-2010, Benoît Markey `<markey@free.fr>` : vidéos d'exemple

2010, Cédrick Faury `<cedrick.faury@laposte.net>` : portage sous Windows, contributions

## Licence du programme

Le programme est sous licence libre, vous pouvez le copier, le distribuer et le modifier, dans le respect de la licence GPL-V3

## Licence des exemples

Les vidéos qui accompagnent le programme à titre d'exemple sont diffusées sous la licence CC-BY-SA 3.0 .

Selon les termes de cette licence, vous avez le droit de copier et diffuser les vidéos, ainsi que d'en faire des dérivés, et l'obligation de citer l'auteur original, ainsi que d'appliquer la même licence aux travaux dérivés.

[1] Attention, un grand nombre de séquences vidéo sont encodées à l'aide de logiciels de codage/décodage (codecs) propriétaires, dont les concepteurs interdisent d'étudier le fonctionnement. PyMecaVideo est un logiciel libre, il n'incorpore pas de sous-ensemble opaque, donc il vous appartient de vérifier la codec utilisé par les séquences vidéo que vous voulez utiliser.

Attention : le format `.avi` du fichier est un format conteneur, qui autorise différents codecs. On ne peut donc pas se baser sur le nom complet du fichier pour deviner le codec de celui-ci. Pour déterminer le codec d'un fichier vidéo, vous pouvez utiliser la commande `file`, par exemple:

    $ file video/g1.avi
    video/g1.avi: RIFF (little-endian) data, AVI, 400 x 300, 25.00 fps, video: DivX 5

[2] Les types de fichiers `.csv`, `.dat`,`.txt` ou `.asc` sont par convention réservés à des fichiers de données à un format texte pur, c'est à dire humainement lisible. Essayez d'ouvrir un fichier que vous produirez ainsi à l'aide d'un éditeur de texte, vous vous rendrez compte de sa structure, claire et simple à comprendre.