Changes between Initial Version and Version 1 of UserGuide2.0

Timestamp:

May 19, 2010, 11:14:05 AM (15 years ago)

Author:

Frédéric

Comment:

--

UserGuide2.0

@@ +1 @@
+[[TOC]]
+
+= Papywizard User Guide =
+
+''This documentation refers to the stable release of branch 2.x (2.0.0) of Papywizard; documentation of the developpement branch can be found [UserGuideSvn here].''
+
+== Usage overview ==
+
+Papywizard is very easy to use, and I hope the GUI is intuitive enough.
+
+The first thing to do is to edit the configuration, to reflect you camera/lens/head/hardware config. Basic settings are the delay to wait after moving (to let the head stop shaking), the delay to wait while shooting (camera Tv value), and the number of pictures to take at each position (bracketing). See below for specific mode settings.
+
+Second, you need to connect to the hardware (Menu ''Hardware > Connect''). If you use the bluetooth driver (default config), you need to enter the correct address of your adapter. Alternatively, you can get a list of all available bluetooth devices arround, and select the correct one.
+
+Then, just move the head either using the big GUI arrows, or using the keys shortcuts (see below), and set the start/end positions.
+
+Once it is done, just open the shooting dialog and launch the entire process. That's it!
+
+== Advanced usage ==
+
+Papywizard has now 2 modes: ''Mosaic'' mode, and ''Preset'' mode. The first one is mainly used for partial panos, and is especially designed for hi-res panos, using a large tele-lens. The second one is designed for full-spherical panos, using a wide-lens or a fisheye.
+
+=== Mosaic mode ===
+
+The mosaic mode computations are based on the following parameters:
+
+ * minimum overlap
+ * camera orientation
+ * sensor coef. and ratio
+ * focal lens
+
+So, these settings must exactly reflect your configuration.
+
+This mode also needs to know start/end positions, which are two opposite corners of the pano you want to shoot. There are 3 ways to give these positions:
+
+ * set them from the current position
+ * give the total field of view for both directions; start/end positions will be automatically computed arround the ''Home'' position (yaw=0, pitch=0)
+ * give the number of pictures to take for both directions; start/end positions will also be automatically computed arround the ''Home'' position (yaw=0, pitch=0)
+
+It does not matter which corner you use for start or end, but it will influence the direction the pano will be shot. Note that, depending of the settings, Papywizard can start shooting from the start position, or from the end position. This is usefull to avoid the head to go back to the opposite corner before shooting (which takes time and uses batteries).
+
+It is also possible to choose the initial shooting direction. Using ''yaw'' will shoot row by row; using ''pitch'' will shoot column by column. Same, the head can go back to the begining of the row/column before shooting the next one (see [TipsAndTricks#Shootingdirection Tips and tricks]).
+
+=== Preset mode ===
+
+This mode is very simple, and does not use any particular settings; it just shoots at all positions defined in the selected template. The only thing to do is to define the ''home'' position of the head (origin), which will be the reference for the template positions. In case the camera/lens can't be moved in all positions, it is possible to set some limits, to avoid potential colisions (limits are not saved in the current release, so they must be set each time the head is turned on).
+
+==== Custom presets ====
+
+Some default presets are provided with the software, but it is possible to add your own. For that, you need to create a xml file which describes them. The file must be named '''{{{presets.xml}}}''' and must be in the config directory: '''{{{~/.config/papywizard2/}}}''' on linux, '''{{{/home/user/.config/papywizard2/}}}''' on maemo, and '''{{{C:\Documents and settings\<user>\Application Data\papywizard2\}}}'''¹ on Windows.
+
+''¹: you have to configure the Windows Explorater so it shows you ''system'' files and directories.
+
+Here is the file structure:
+
+{{{
+#!xml
+<?xml version="1.0" encoding="utf-8" ?>
+<papywizard>
+    <preset name="My custom preset">
+        <tooltip>
+            20D + 50mm
+            12 picts @ +55°
+            20 picts @ +40°
+            50 picts @  10°/-10°
+            20 picts @ -40°
+            55 picts @ -70°
+        </tooltip>
+        <shoot>
+            <pict yaw="0." pitch="55." />
+            <pict yaw="30." pitch="55." />
+            <pict yaw="60." pitch="55." />
+            <pict yaw="90." pitch="55." />
+            ...
+        </shoot>
+    </preset>
+    <preset name="Another custom preset">
+    ....
+     </preset>
+</papywizard>
+}}}
+
+Where:
+ * {{{<preset> name attribute}}}: name used to present the preset in the GUI
+ * {{{<tooltip>}}}: information for that preset (shown in the information presets template window)
+ * {{{<shoot>}}}: list of all positions to shoot, described in {{{yaw/pitch}}} attributes of the {{{<pict>}}} tag (one tag per position)
+
+''Note: it is possible to define several presets in the same file.''
+
+To save time during shoot, take care of the order of positions. For example, don't ask the head to go back to the begining of the new row, it will take too long; instead, reverse the direction and go back for the next row.
+
+You can also import a custom preset file from the ''File'' menu. Note that this file won't be automatically loaded at next startup; this is mainly to test your presets before putting them in your user config. dir.
+
+If you add usefull templates, feel free to send them so they could be added as default ones.
+
+=== Preset converter ===
+
+As all files managed by Papywizard are xml, it is very easy to convert an output data file to a '''{{{presets.xml}}}''' file, using '''XSL transform'''. Here is a [DataToPresetConverter a form] to automatically make such conversion.
+
+== Shooting sequence ==
+
+It is possible to suspend/resume the shooting sequence using the '''{{{Pause/Resume}}}''' button. Once paused, the shooting sequence can be modified; clicking on any position on the GUI will set the next position to shoot to that new position.
+
+''Note: if you are shooting a hi-resolutio pano, there may be too much preview positions on the GUI to easily select one. In this case, just use the 2 button on both sides of the shooting area to rewind/forward the next shooting position. Arrow keys are also binded to these buttons.
+
+If the '''{{{manual shooting}}}''' flag is set, the shooting sequence will automatically go to pause mode after each move (before running the camera shutter sequence), and after each camera shutter sequence (before moving to the next position). During the camera shutter sequence, the shutter will be triggered one or more times, depending of the bracketing parameter in the config; no pause will be done inside this sequence.
+
+== Cutomization ==
+
+=== Style sheet ===
+
+Since release 1.9.1, Papywizard can load a user style sheet. This file must be name '''{{{papywizard.css}}}''', and must be located in the config directory.
+
+Here is a sample file:
+
+{{{
+#!c
+QPushButton {
+    color: red;
+}
+}}}
+
+For more informations about Qt style sheets, see [http://doc.trolltech.com/4.4/stylesheet.html this page].
+
+''Note: a dedicated page for nice style sheets will soon be created. Feel free to send yours.''
+
+== Tethered shooting ==
+
+It can be usefull to call an external program to make tethered shooting, instead of using the Merlin/Orion triggering.
+
+If a '''{{{shoot.py}}}''' python script is found in the user config. dir, the functions '''{{{mirrorLockup()}}}''' and '''{{{shoot(bracketNumber)}}}''' contained in this script will be called instead of internal ones.
+
+Here is a minimalistic example script:
+
+{{{
+#!python
+import subprocess
+
+
+def mirrorLockup():
+    """ Lockup the mirror.
+
+    @return: error code, stdout, stderr
+    @rtype: tuple of int, str, str
+    """
+
+    # See shoot() function
+    return 0, "", ""
+
+
+def shoot(bracketNumber):
+    """ Shoot.
+
+    @param bracketNumber: number of the current bracket picture
+    @type bracketNumber: int
+
+    @return: error code, stdout, stderr
+    @rtype: tuple of int, str, str
+    """
+
+    # Launch external command
+    args = ["gphoto2", "--capture-image"]
+    p = subprocess.Popen(args, stdout=subprocess.PIPE, stderr=subprocess.PIPE)
+
+    # Wait end of execution
+    stdout, stderr = p.communicate()
+
+    return p.returncode, stdout, stderr
+}}}
+
+The external program name (here, '''"gphoto2"''') must be the first element of the '''{{{args}}}''' list; optional params (here '''"--capture-image"''') can be given as additional elements of the list. If you want to give the '''{{{bracketNumber}}}''' value, use '''{{{"%d" % bracketNumber}}}''' (or '''{{{str(bracketNumber)}}}''') as param value.
+
+Under Windows, the full path of the program must be given, like '''{{{"C:\\Program Files\\notepad.exe"}}}'''.
+
+ * ''Note 1: the tethered program needs to support command-line call.''
+ * ''Note 2: if a function does not exist, the internal one will be used instead.''
+
+More informations about ''subprocess'' module usage can be found here:
+
+ * [http://www.python.org/doc/2.5.4/lib/node528.html]
+ * [http://www.python.org/doc/2.5.4/lib/node532.html]
+
+== Reference manual ==
+
+=== Main window ===
+
+==== Menus ====
+
+ * '''File > Quit''': exit from Papywizard
+ * '''File > Import Preset File...''': Import presets from file
+ * '''File > Load Style Sheet...''': load style sheet
+ * '''Hardware > Connect''': connect to the head hardware
+ * '''Hardware > Set limit...''': set the selected limit to curent position
+ * '''Hardware > Clear limits''': reset all limits
+ * '''Hardware > Goto Home...''': goto home position
+ * '''Hardware > Goto Initial...''': goto inital position (when turned on)
+ * '''Help > Manual''': open this documentation (network connection needed)
+ * '''Help > View log...''': open log dialog
+ * '''Help > About Papywizard''': open the Papywizard about dialog
+ * '''Help > About Qt''': open the Qt about dialog
+
+==== displays ====
+
+Mosaic tab:
+ * '''Start''': start shooting position
+ * '''End''': end shooting position
+ * '''Total Fov''': total shooting field of view
+ * '''Nb picts''': shooting number of pictures
+ * '''Real overlap''': real shooting overlap
+ * '''Resolution''': resolution of the pano
+Preset tab:
+ * '''Template''':
+Common:
+ * '''Position''': current position of the head
+
+==== buttons ====
+
+ * '''Mosaic/Preset''': switch between mosaic and preset mode
+Mosaic tab:
+ * '''Start/Yaw/Pitch''': set the start shooting position from current position (for both, yaw or pitch)
+ * '''End/Yaw/Pitch''': set the end shooting position from current position (for both, yaw or pitch)
+ * '''Total fov''': open a dialog to specify the wanted yaw/pitch fov
+ * '''NB picts''': open a dialog to specify the wanted yaw/pitch nb picts
+Preset tab:
+ * '''Template''': template defining all positions
+ * '''Templates information''': informations on available templates
+Common:
+ * '''Left/Right Yaw arrows''': move head on yaw axis
+ * '''Left/Right pitch arrows''': move head on pitch axis
+ * '''Set origin''': set the current position as origin (yaw=0.0°, pitch = 0.0°)
+ * '''Configuration...''': open the config. dialog
+ * '''Shoot...''': open the shooting dialog
+
+==== Status bar ====
+
+ * '''Messages'''
+ * '''Manual speed'''
+ * '''Connexion status'''
+
+=== Configuration dialog ===
+
+==== Shooting tab ====
+
+ * '''Head orientation''': orientation of the head
+ * '''Camera orientation''': camera orientation on the head (if combobox is set to ''custom'', real orientation can be given)
+ * '''Stabilization delay''': delay to wait after the head has stopped, and before shooting, to let the head stablizing
+
+==== Mosaic tab ====
+
+ * '''Overlap''': minimum wanted overlap
+ * '''Start from''': start position
+ * '''Initial direction''': initial moving direction
+ * '''CR''': if set, go back to the start of the row/columns before starting a new one
+
+==== Camera tab ====
+
+ * '''Time value''': shooting time. If set to 0, skip shooting sequence
+ * '''Pulse width (high/low)''': width of the shutter triggering pulse (high level duration, and minimum low level duration between too consecutive shots)
+ * '''Bracketing''': number of picture to take at each position, and the intent of the bracketing
+ * '''Sensor (coef/ratio)''': ratio to 24x36 size, width vs height ratio
+ * '''Sensor resolution''': resolution of the sensor
+
+==== Lens tab ====
+
+ * '''Type''': type of the lens (''rectilinear'' or ''fisheye'')
+ * '''Focal''': real focal of the lens (''rectilinear'' only)
+ * '''Optical multiplier''': optional optical multiplier coef. (''rectilinear'' only)
+
+==== Hardware tab ====
+
+ * '''Driver''': hardware driver to use ('bluetooth', 'serial', 'ethernet')
+ * '''BT device address''': bluetooth device address for 'bluetooth' driver
+ * '''Choose...''': open the bluetooth chooser dialog
+ * '''Serial port''': serial device port for 'serial' driver (either a int or a string, like {{{COM1}}} or {{{/dev/ttyS0}}})
+ * '''Ethernet host''': hostname/IP for the 'ethernet' driver
+ * '''Ethernet port''': port number of the 'ethernet' driver
+ * '''Auto-connect''': if set, try to automatically connect to the head at startup
+
+==== Data tab ====
+
+ * '''Data storage dir''': set the directory where data file are written
+ * '''Data file''': format to use for the output data file name. The final name is {{{papywizard_<format>.xml}}}
+  * {{{%(date)s}}}: expands to current date
+  * {{{%(time)s}}}: expands to start shooting time
+  * {{{%(date_time)s}}}: same as {{{%(date)s_%(time)s}}}
+  * {{{%(mode)s}}}: expands to shooting mode (mosaic or preset)
+ * '''Enable''': flag to enable the data file
+ * '''Title''': title of the pano
+ * '''GPS''': GPS informations of the pano
+ * '''Comment''': comment on the pano
+
+==== Timer tab ====
+
+ * '''Start after''': delay to wait before starting
+ * '''Enable''': switch to enable the '''Start after''' timer
+ * '''Repeat''': number of repeats
+ * '''Enable''': switch to enable the '''Repeat''' feature
+ * '''Repeat every''': shoot panos every given time
+
+==== Misc tab ====
+
+ * '''Logger level''': level of informations to log
+
+==== buttons ====
+
+ * '''OK''': validate settings and close dialog
+ * '''Cancel''': revert to previous settings and close dialog
+
+=== Bluetooth dialog ===
+
+This dialog shows the list of availabe bluetooth devices, and a button to refresh the list.
+
+=== Shoot dialog ===
+
+==== displays ====
+
+ * ''shooting scene'': display the shooting position. Clicking on this area while paused set the next position to shoot
+ * ''text shooting area'': display the shooting position in text mode
+ * ''sequence'': display the current shooting sequence
+ * ''repeat counter'': display the current repeat value
+ * ''elapsed time'': display the shooting time and total elapsed time
+ * ''progress bar'': shooting process progression (for current repeat and all repeats)
+
+==== buttons ====
+
+ * '''Text''': toggle text/gaphical shooting areas
+ * '''Rewind''': while paused, rewind the next position to shoot
+ * '''Forward''': while paused, forward the next position to shoot
+ * '''Data''': direct access button to the Data tab of configuration dialog
+ * '''Timer''': direct access button to the Timer tab of configuration dialog
+ * '''Step-by-step''': if checked, each step (moving, shooting) will need to be validated use the Pause/Resume button
+ * '''Start''': start shooting process
+ * '''Pause/Resume/Step''': pause/resume/step shooting process
+ * '''Stop''': cancel shooting process
+ * '''Close''': close shooting dialog
+
+=== Log dialog ===
+
+==== buttons ====
+
+ * '''Clear Log''': clear the log window
+ * '''Save Log''': save the log to file (in the data storage dir)
+
+== Keyboard shortcuts ==
+
+Papywizard main target is ''Nokia Internet Tablets'', so keyboard shortcuts are dedicated for that plateform (but works fine with normal PC). Here are defined shortcuts:
+
+ * In main window:
+||'''Nokia'''||'''PC'''||'''Function'''||
+||[[Image(Right.png, 24, nolink)]]||Right||Turn the head right (Yaw +)||
+||[[Image(Left.png, 24, nolink)]]||Left||Turn the head left (Yaw -)||
+||[[Image(Up.png, 24, nolink)]]||Up||Move the head up (Pitch +)||
+||[[Image(Down.png, 24, nolink)]]||Down||Move the head down (Pitch -)||
+||[[Image(F7-increase.png, 24, nolink)]]||End||Increase the manual speed||
+||[[Image(F8-decrease.png, 24, nolink)]]||Home||Decrease the manual speed||
+||[[Image(Return.png, 24, nolink)]]||Return||Open shooting dialog||
+||[[Image(Escape.png, 24, nolink)]]||Escape||Quit the application||
+||||Ctrl-q||Quit the application||
+||||Alt-F4||Quit the application||
+
+ * In shooting dialog:
+||'''Nokia'''||'''PC'''||'''Function'''||
+||[[Image(Right.png, 24, nolink)]]||Right||Forward shooting position (while paused)||
+||[[Image(Left.png, 24, nolink)]]||Left||Rewind shooting position (while paused)||
+||[[Image(Up.png, 24, nolink)]]||Up||Forward shooting position (while paused)||
+||[[Image(Down.png, 24, nolink)]]||Down||Rewind shooting position (while paused)||
+||[[Image(Return.png, 24, nolink)]]||Return||Start/pause shooting||
+||[[Image(Escape.png, 24, nolink)]]||Escape||Stop shooting - Return to main window||
+
+ * In all dialogs:
+||'''Nokia'''||'''PC'''||'''Function'''||
+||[[Image(F4-menu.png, 24, nolink)]]||F10||Show menu||
+||[[Image(F5-home.png, 24, nolink)]]||-||Standard maemo behaviour||
+||[[Image(F6-fullscreen.png, 24, nolink)]]||F11||Toggle fullscreen mode||