Merge pull request #592 from mprib/590-make-documentation-current

ongoing documentation updates

docs/calibration_board.md

@@ -0,0 +1,48 @@
+Camera calibration is performed with the aid of a [ChArUco calibration board](https://docs.opencv.org/3.4/df/d4a/tutorial_charuco_detection.html). This is basically a chessboard that has ArUco markers within it and is used to determine both the intrinsic properties of a camera (its optical center, focal length, and lens distortion) as well as where the cameras are relative to each other. 
+
+It is possible to purchase pre-printed calibration boards and then set the parameters of the ChArUco to fit the board you have. **Please keep in mind that row count and column count are not interchangeable, so visually inspect your physical board compared to the board shown in the GUI to make sure they are the same. You may need to swap row and column values. **
+
+# ChArUco Tab Options
+
+ChArUco board creation allows the following configuration options:
+
+## Board Inversion
+
+To save on printer ink, you can select to invert the board image so that white and black regions are swapped. If this is done, then pyxy3d will invert a grayscale image prior to running ChArUco recognition so that things will still work out.
+
+## Board Size
+
+This is the target size that the final printed board will have. This can minimize white space in the `png`. 
+
+## Row and Column Count
+
+While more rows and columns mean that you can get more recognized corners per board view, it results in smaller ArUco markers for a given board size. These smaller markers will then be harder to recognize from a distance, limiting the size of the capture volume you can calibrate for a given resolution of cameras. This presents a trade-off to consider for your set up.
+
+As noted above: row count and column count are not interchangeable. An 8x5 board is not the same as a 5x8 board.
+
+## Mirror Board
+
+In addition to a regular one-sided board, it is possible to print a double-sided board that has the mirror image printed on the back. If the tracker does not find the primary board in a frame, it will then flip the image and search for the board again, flipping the coordinates of any tracked points back to an unflipped frame of reference.
+
+This allows cameras that do not share a common view of a board to better estimate their position relative to each other. The intention is to allow better calibration of systems with surround camera setups as is common in larger scale motion capture. Please note that thicker foam boards may not work well for this. The feature has only been successfully tested with a paper print pressed between two panes of glass.
+
+## Actual Printed Square Size
+
+To ensure that the scale of the world is accurate in your final triangulated points, measure the actual length of a printed square of the board. While errors in this measurement will not cause failure along the way, it can result in very large or very small subjects in the triangulated output. Please note that even if you print directly to your intended board size, small differences in actual square size are likely to result.
+
+
+# Implementation Details
+
+## Taping together a board from multiple printed sheets
+
+Rather than paying for a professionally printed board, it is possible to print a board on multiple standard sheets of paper, trim them as appropriate, then tape them together. Undoubtedly, this will lead to larger errors in calibration, though I have been pleasantly surprised by the quality of the tracked landmark data. 
+
+## Flatness Matters Particularly for Intrinsics
+
+Having a truly flat board is crucial for a good intrinsic camera calibration. At the core of the calibration algorithm is the fact that all points exist on a common plane. Loosely taped pieces of paper or warped cardboard backings will undermine the calibration quality. 
+
+## Different boards from intrinsic and extrinsic calibration
+
+It is possible to perform the intrinsic calibration and extrinsic calibration using different boards, though you will have to adjust the board definition prior to running each calibration. In this way, a more perfectly flat and and aligned board could be used for intrinsic calibration when it is fine to have the board relatively close to a single camera. During extrinsic calibration, a larger board pieced together from multiple sheets of paper could be used to allow calibration of a larger capture volume.
+
+Please note that for a given set of cameras, the intrinsic calibration only needs to be performed once, and that configuration can be copied over to future projects with the same cameras.

docs/installation.md

@@ -1,8 +1,10 @@
 # Installation
 
-Pyxy3D is a powerful tool that can be installed easily using pip and launched from the command line. To ensure the best experience and compatibility, we strongly advise installing it within a virtual environment. This approach helps in maintaining a clean workspace and avoids conflicts with other packages. Pyxy3D is compatible with Python versions [3.10](https://www.python.org/downloads/release/python-3100/) and [3.11](https://www.python.org/downloads/release/python-3110/).
+Pyxy3D can be installed easily using pip and launched from the command line.
 
-To avoid complications, we recommend you use the full file path to your Python executable. Here's how to do it for different operating systems:
+## 1. Create a virtual environment
+
+We strongly advise installing within a virtual environment. This approach helps in maintaining a clean workspace and avoids conflicts with other packages. Pyxy3D is compatible with Python versions [3.10](https://www.python.org/downloads/release/python-3100/) and [3.11](https://www.python.org/downloads/release/python-3110/). To avoid complications, we recommend you use the full file path to your Python executable. Here's how to do it for different operating systems:
 
 === "Windows"
 
@@ -54,7 +56,7 @@ To avoid complications, we recommend you use the full file path to your Python e
 
 ## 2. Install pyxy3D via pip
 
-With your virtual environment ready, the next step is to install Pyxy3D itself. This is a straightforward process that can be done using pip, Python's package installer. Follow the instructions specific to your operating system below:
+With your virtual environment activated, the next step is to install pyxy3D itself. This is a straightforward process that can be done using pip, Python's package installer. Follow the instructions specific to your operating system below:
 
 
 === "Windows"
@@ -89,4 +91,4 @@ With the package installed and the virtual environment activated, the main GUI c
 pyxy3d
 ```
 
-*Note on First Launch*: The first time you launch Pyxy3D after installation, you might experience a longer than usual startup time. This is normal and expected as the application performs initial setup tasks like compiling components. Rest assured, these processes are one-time events, and subsequent launches of the GUI will be significantly faster.
+*Note on First Launch*: The first time you launch after installation, you might experience a longer than usual startup time. This is normal and expected as the application performs initial setup tasks like compiling components. Rest assured, these processes are one-time events, and subsequent launches of the GUI will be significantly faster.

docs/workspace_setup.md → docs/project_setup.md

@@ -16,13 +16,14 @@ ProjectDirectory/
 └── recordings/    # Empty by default prior to user populating data
 ```
 
-## Stage 1: Intrinsic Calibration
+## Stage 1: Intrinsic Calibrationa
 
-The first files to put in place are for the intrinsic calibration. These must follow the naming convention `port_1.mp4`, `port_2.mp4`, etc. They do not need to be synchronized. See [Best Practices](best_practice_calibration.md) for getting a good recording for intrinsic calibration. A project with 3 cameras would therefore look something like this going into the intrinsic camera calibration. 
+Place video files for the intrinsic camera calibration in the `intrinsic` folder. 
 
-As the intrinsic properties of the camera are calculated, parameters are stored in `config.toml` at the project root.
+These must follow the naming convention `port_1.mp4`, `port_2.mp4`, etc. They do not need to be synchronized. See [Best Practices](best_practice_calibration.md) for getting a good recording for intrinsic calibration. 
+
+A project with 3 cameras would therefore look something like this going into the intrinsic camera calibration. 
 
-With these files in place and the intrinsic calibration done, the folder structure will then looks like this
 ```
 ProjectDirectory/
 ├── config.toml          # following intrinsic calibration, this file will also have the camera matrix and distortion for each source camera
@@ -35,11 +36,12 @@ ProjectDirectory/
 └── recordings/
 ```
 
+As the intrinsic properties of the camera are calculated, parameters are stored in `config.toml` at the project root.
 
 
 ## Stage 2: Extrinsic Calibration
 
-Extrinsic calibration footage must be synchronized. This can be done in one of two ways:
+Place sychronized video files in the `extrinsic` folder. Synchronization can be accomplished in one of two ways:
 
 1. Record all video footage with a common external trigger such that each frame is at the same point in time as the corresponding frames from the other files. In other words: all mp4 files should start and stop at the same moment in time and have the same number of frames.
 
@@ -92,6 +94,9 @@ ProjectDirectory/
 
 
 ## Stage 3: Processing Motion Capture Trial
+
+For each motion capture trial, create a subfolder within `recordings` and populate it with synchronized footage as was done with the extrinsic calibration. After post-processing of the video footage has occurred, output will be created as shown in the following example:
+
 ```
 ProjectDirectory/
 ├── config.toml                             # File unchanged from above

docs/requirements.md

@@ -2,12 +2,7 @@
 
 - **Python version**: [Python 3.10](https://www.python.org/downloads/release/python-3100/) or [3.11](https://www.python.org/downloads/release/python-3110/)
 
-- **Operating System**: While the core calibration and GUI are cross-platform, Google's [MediaPipe](https://github.com/google/mediapipe/blob/master/docs/solutions/holistic.md) is currently used for pose tracking and has only been tested on Windows 10 and MacOS.
 
-- **Cameras**: At least two cameras are needed, though tracking accuracy improves with the use of more cameras. Mediapipe tracking is in-the-box 
-
-- **Computer**: 
-
-- **Calibration Board**: A [ChArUco board](https://docs.opencv.org/3.4/df/d4a/tutorial_charuco_detection.html) is needed for camera calibration and determining spatial relationships between multiple cameras. A sample board can be printed from the GUI on a standard 8.5 x 11 sheet of paper, though . It is crucial to place the printed board on a flat surface to ensure accurate calibration, such as taping it down to a rigid flat piece of cardboard.
+- **Calibration Board**: A [ChArUco board](https://docs.opencv.org/3.4/df/d4a/tutorial_charuco_detection.html) is needed for camera calibration and determining spatial relationships between multiple cameras. A sample board can be printed from the GUI on a standard 8.5 x 11 sheet of paper. For a given resolution of cameras, a larger board will be able to calibrate a larger capture volume because it can be recognized from farther away. It is crucial to place the printed board on a flat surface to ensure accurate calibration, such as taping it down to a rigid flat piece of cardboard.
 
 - **Capture Environment**: Data recording requires a well-lit and evenly lit environment. It is beneficial if the background contrasts highly with the individual being tracked. For example, tracking difficulties may arise if a person in dark clothing stands against a similarly dark wall. Be mindful of clothing, background, and lighting to optimize the quality of the captured data.

mkdocs.yml

@@ -31,13 +31,14 @@ theme:
 
 nav:
   - FAQ: faq.md
-  - Requirements: requirements.md
   - Installation: installation.md
-  - Workspace Setup: workspace_setup.md
-  - Best Practices:
+  - Project Setup: project_setup.md
+  - GUI Workflow: gui_workflow.md
+  - Workflow:
+    - ChArUco Board: calibration_board.md
     - Intrinsic Calibration: intrinsic_calibration.md
     - Extrinsic Calibration: extrinsic_calibration.md
-    - Motion Capture: extrinsic_calibration.md 
+    - Processing Footage: post_processing.md 
 
 plugins:
   - search