| Version 63 (modified by , 16 years ago) ( diff ) |
|---|
Papywizard Developper Guide
Introduction
Papywizard is entirely written in python. It uses PyGTK (Python bindings for GTK) toolkit for the GUI, and a few additional modules, mainly for hardware control (pybluez and pyserial). Optionnaly, vpython (OpenGL-based module) can also be used to simulate the position of the head (note that this will be soon a separate application).
API
The API documentation is available as web page in the html/ directory.
Architecture
Papywizard uses a MVC-like pattern, which keeps the model separated from the views. This allows to use any other toolkit if needed; I recently switched from Tkinter to PyGTK, to run Papywizard on Nokia plateform. I hope, one day, to be able to run Papywizard on QTopia-based devices, like Openmoko. But I first need to get such device ;o)
Low-levels routines which control the hardware are also in their own package; I plan to made them even more modular, to be used in an external project to control the head. For know, only Merlin/Orion head is supported, but it is very easy to implement other heads.
A word about the simulation (to come).
Hardware
Merlin/Orion protocole
The head uses a simple ascii serial protocol; the serial line uses standard settings: 9600 8N1 (9600 bauds, 8 bits data, no parity, 1 stop bit). The head waits for incoming commands, and send response to them. The 2 axis are identical, and uses the same commands. They both wait for incoming commands; depending of the first value (see below), the command will be sent to one or the other axis.
A commands always starts with ':', and ends with '\r'. The head response always starts with '=', and also ends with '\r'. As TX/RX lines are wired together, the controller has to first readback its own command, before reading the head response. In the following documentation, the command readback is omitted, as the ':', '=' and '\r' chars.
Parameters used in the documentation:
| Parameter | What | Allowed value | Format | Note |
| <axis> | axis to control | 1 or 2 | 1 ascii digit | 1=yaw, 2=pitch axis |
| <pos> | position | 0 to 2²⁴-1 | 6 ascii digits, hex. | Low byte is sent first (A35483 is read 8354A3). When switched on, read value is 800000. Right sens increments axis 1; left sens decrements it. Up sens increments axis 2; down decrements it. A complete turn (360°) increments/decrements by 0E6600 (so, the axis can make almost 9 turns before the counter overflow) |
| <dir> | axis direction | 0 or 1 | 1 ascii digit | 0=increments (up/right), 1=decrements (down/left) |
| <status> | Axis status | 3 ascii digits | Second digit is 0 when axis is stopped | |
| <state> | State of the shutter contact | 1 ascii digit | 0 or 1 | 0 opens the contact, 1 closes the contact |
Merlin/Orion commands set
| Function | Command | Response | Note |
| Read axis position | j<axis> | <pos> | |
| Read axis status | f<axis> | <status> | |
| Stop moving | L<axis> | ||
| Init (at switch on) | F<axis> a<axis> D<axis> | 0E62D3 0006F9 | |
| Start moving | L<axis> G<axis>3<dir> I<axis>220000 J<axis> | 220000 seems to be the divider for the speed. The lower the value, the higher the speed | |
| Drive to position | L<axis> G<axis>00 S<axis><pos> J<axis> | ||
| Set shutter contact state | O<axis><state> | Both axis understand the command, but the contact is only set by yaw (0) axis | |
Merlin/Orion communication examples
When switched on:
command response :F1\r =\r :F2\r =\r :a1\r =D3620E\r :D1\r =F90600\r :a2\r =D3620E\r :D2\r =F90600\r :D2\r =F90600\r
Note: the last command is sent twice by the original remote control, but all works fine if sent only once (like Papywizard does).
Push up button in fast mode:
command response :L2\r =\r :G230\r =\r :I2220000\r =\r :J2\r =\r
Release up button if fast mode:
command response :L2\r =\r :f2\r =503\r
Model
View
Output XML file
Papywizard can generate a xml data file. This file mainly contains all positions reached during shooting, and can be used by Autopano Giga to help positionning orphan pictures. This is very helpfull for high-resolution panos with deep blue sky, without details. Sift algorithm often fail to find control points in such areas.
Description
The XML file is made of two parts: a header, containing global informations, and a shoot part, containing a list of all pictures positions. The exact header format depends of the mode (see examples below).
This format is open, and can be used by anyone who wants to implement motorized panohead output data file. Feel free to contact me if you want to add some entries to support special features. The goal is to make some sort of standard format. More informations here.
Example in mosaic mode
<?xml version="1.0" encoding="utf-8"?>
<papywizard version="0.9">
<header>
<shooting mode="mosaic">
<stabilizationDelay>0.5</stabilizationDelay>
<start>Mon Oct 13 10:52:33 2008</start>
<end>Mon Oct 13 10:52:53 2008</end>
<comment>Néron mountain</comment>
</shooting>
<camera>
<timeValue>0.5</timeValue>
<nbPicts>3</nbPicts>
<sensor coef="1.6" ratio="3:2"/>
</camera>
<lens>
<focal>17.0</focal>
</lens>
<mosaic>
<nbPicts pitch="1" yaw="3"/>
<overlap minimum="0.25" pitch="1.00" yaw="0.26"/>
<cameraOrientation>portrait</cameraOrientation>
</mosaic>
</header>
<shoot>
<pict id="1" num="1">
<time>Mon Oct 13 10:52:39 2008</time>
<position pitch="0.0" yaw="-44.4"/>
</pict>
<pict id="2" num="2">
<time>Mon Oct 13 10:52:40 2008</time>
<position pitch="0.0" yaw="-44.4"/>
</pict>
<pict id="3" num="3">
<time>Mon Oct 13 10:52:41 2008</time>
<position pitch="0.0" yaw="-44.4"/>
</pict>
<pict id="4" num="1">
<time>Mon Oct 13 10:52:45 2008</time>
<position pitch="0.0" yaw="-9.3"/>
</pict>
<pict id="5" num="2">
<time>Mon Oct 13 10:52:46 2008</time>
<position pitch="0.0" yaw="-9.3"/>
</pict>
<pict id="6" num="3">
<time>Mon Oct 13 10:52:47 2008</time>
<position pitch="0.0" yaw="-9.3"/>
</pict>
<pict id="7" num="1">
<time>Mon Oct 13 10:52:51 2008</time>
<position pitch="0.0" yaw="25.7"/>
</pict>
<pict id="8" num="2">
<time>Mon Oct 13 10:52:52 2008</time>
<position pitch="0.0" yaw="25.7"/>
</pict>
<pict id="9" num="3">
<time>Mon Oct 13 10:52:53 2008</time>
<position pitch="0.0" yaw="25.7"/>
</pict>
</shoot>
</papywizard>
Example in preset mode
<?xml version="1.0" encoding="utf-8"?>
<papywizard version="0.9">
<header>
<shooting mode="preset">
<stabilizationDelay>0.5</stabilizationDelay>
<start>Mon Oct 13 10:30:47 2008</start>
<end>Mon Oct 13 10:31:40 2008</end>
<comment>Inside my living room</comment>
</shooting>
<camera>
<timeValue>0.5</timeValue>
<nbPicts>3</nbPicts>
<sensor coef="1.6" ratio="3:2"/>
</camera>
<lens>
<focal>17.0</focal>
</lens>
<preset template="3@-15 + Z"/>
</header>
<shoot>
<pict id="1" num="1">
<time>Mon Oct 13 10:31:04 2008</time>
<position pitch="-15.0" yaw="0.0"/>
</pict>
<pict id="2" num="2">
<time>Mon Oct 13 10:31:05 2008</time>
<position pitch="-15.0" yaw="0.0"/>
</pict>
<pict id="3" num="3">
<time>Mon Oct 13 10:31:06 2008</time>
<position pitch="-15.0" yaw="0.0"/>
</pict>
<pict id="4" num="1">
<time>Mon Oct 13 10:31:16 2008</time>
<position pitch="-15.0" yaw="120.0"/>
</pict>
<pict id="5" num="2">
<time>Mon Oct 13 10:31:17 2008</time>
<position pitch="-15.0" yaw="120.0"/>
</pict>
<pict id="6" num="3">
<time>Mon Oct 13 10:31:18 2008</time>
<position pitch="-15.0" yaw="120.0"/>
</pict>
<pict id="7" num="1">
<time>Mon Oct 13 10:31:27 2008</time>
<position pitch="-15.0" yaw="240.0"/>
</pict>
<pict id="8" num="2">
<time>Mon Oct 13 10:31:28 2008</time>
<position pitch="-15.0" yaw="240.0"/>
</pict>
<pict id="9" num="3">
<time>Mon Oct 13 10:31:29 2008</time>
<position pitch="-15.0" yaw="240.0"/>
</pict>
<pict id="10" num="1">
<time>Mon Oct 13 10:31:38 2008</time>
<position pitch="90.0" yaw="240.0"/>
</pict>
<pict id="11" num="2">
<time>Mon Oct 13 10:31:39 2008</time>
<position pitch="90.0" yaw="240.0"/>
</pict>
<pict id="12" num="3">
<time>Mon Oct 13 10:31:40 2008</time>
<position pitch="90.0" yaw="240.0"/>
</pict>
</shoot>
</papywizard>
Distributing
Debian package
There is no debian packager yet.
Maemo package
Papywizard includes an distutils extension script to build maemo debian package in a easy way:
$ python maemo/setup.py bdist_debian
Windows installer
This is a little bit tricky (as always on this plateform!). You first need to install all developpement tools and libraries:
- TODO
Then, build the executable, by launching the windows setup script. The easiest is to use Ipython:
In [1]: run windows/setup.py py2exe
Last, run the script windows/papywizard.nsi (need to install NSIS software) to build the installer itself.
Note: the bluetooth doesn't work on Windows I don't know why, as I'm not really familiar with this plateform.
Contribute
There are several ways to contribute:
Help coding
Test and report bugs
Internationalization
If you want to contribute but don't know how to code, you can make translation.
To do that, you just need to ask me for the corresponding papywizard.po file which contains all sentences and words used in the soft, translate them using Poedit (important; don't translate using a simple text editor), and send it back to me.
If you are not sure about the usage of a word/sentence, feel free to ask about the context.
Note: some original strings, extracted from the GUI XML description file, contain spaces at the begining or the end; these extra spaces can be ommited in the translation.
