update patch

README.md

@@ -11,8 +11,6 @@
 
 [Limitations](#limitations)
 
-[Known Issues](#known-issues)
-
 ---
 ## About
 
@@ -22,7 +20,9 @@ Pyxy3D (*pixie-3d*) is an open-source **Py**thon package for converting 2D **(x,
 - API for slotting various tracking solutions into the data pipeline
 - triangulation of tracked points
 
-The current functionality includes a sample tracker using Google's Mediapipe which illustrates how to use the tracker API. The camera management backend allows for recording of synchronized frames from connected webcams, though the frame rate/resolution/number of cameras will be limited by the bandwidth of the current system.
+The package comes included with a sample tracker using Google's Mediapipe which illustrates how to use the tracker API. The camera management backend allows for recording of synchronized frames from connected webcams, though the frame rate/resolution/number of cameras will be limited by the bandwidth of the current system.
+
+![Quick_Demo](https://github.com/mprib/pyxy3d/assets/31831778/5fc8e15e-ca64-447b-86b8-69c64601199c)
 
 ## Quick Start
 
@@ -49,13 +49,14 @@ C:\Python310\python.exe -m venv .venv
 ```powershell
 pip install pyxy3d
 ```
+Note that this will also install dependencies into the virtual environment, so complete download and installation make take several minutes..
 
 6. Launch Pyxy3D    
 ```powershell
 pyxy3d
 ```
+At this point, an application window should launch. It may take several seconds for this to load. Refer to the [Quick Start Video Walkthrough](https://youtu.be/QHQKkLCE0e4) to see how to calibrate, record and process data
 
-Refer to the [Quick Start Video Walkthrough](https://youtu.be/QHQKkLCE0e4) to see how to calibrate, record and process data
 ## Key Features
 
 The project leans heavily upon OpenCV, SciPy, and PyQt to provide the following **key features**:
@@ -79,6 +80,7 @@ Please note that the system currently has the following **limitations**:
 - MediaPipe is only configured to run on Windows
     - while the camera calibration will likely work on other systems, the included sample markerless tracking will not (currently)
 - It does not support anything other than standard webcams at the moment 
+- The frame capture backend presents a primary bottleneck that will limit the number of cameras/resolution/frame rates that can be used, which ultimately limits the size and precision of the capture volume.
 - Data export is currently limited to .csv, and .trc files. Use in 3D animation tools like Blender, which require character rigging, will require additional processing.
 
 

docs/calibration.md

@@ -0,0 +1,2 @@
+
+This is a placeholder for future documentation that is currently on the todo list. Please see the [demo video](https://www.youtube.com/embed/QHQKkLCE0e4) for how to calibrate your camera system. 

docs/data_capture.md

@@ -0,0 +1,2 @@
+
+This is a placeholder for future documentation that is currently on the todo list. Please see the [demo video](https://www.youtube.com/embed/QHQKkLCE0e4) for a sample data capture. 

docs/index.md

@@ -4,9 +4,13 @@
 
 # Welcome
 
+Pyxy3D (*pixie-3d*) is an open-source **Py**thon package for converting 2D **(x,y)** point data to **3D** estimates. It is intended to serve as the calibration and triangulation workhorse of a low-cost DIY motion capture studio. It's core functionality includes: 
 
-Pyxy3D is an open-source python package designed for two primary purposes: *calibrating* DIY motion capture systems and *triangulating* the 3D position  of tracked landmarks where (x,y) coordinates have been identified across concurrent frames. It includes a pre-built implementation of Google's Holistic Mediapipe, but aims to be tracker-agnostic and provides an API for implementing alternative tracking packages. Pyxy3D also provides functionality for recording synchronized frames from a small number of connected webcams. This may be sufficient for small-scale use cases, but it will become unstable as the resolution, frame rate, and number of cameras increases. Consequently, where larger capture volumes or greater spatial or temporal resolution is needed, alternate data capture techniques will be required. 
+- the estimation of intrinsic (focal length/optical center/distortion) and extrinsic (rotation and translation) camera parameters via a GUI
+- API for slotting various tracking solutions into the data pipeline
+- triangulation of tracked points
 
+The packages comes included with a sample tracker using Google's Mediapipe which illustrates how to use the tracker API. The camera management backend allows for recording of synchronized frames from connected webcams, though the frame rate/resolution/number of cameras will be limited by the bandwidth of the current system.
 
 This project is at a very early stage so please bear with us while going through the inevitable growing pains that are ahead. You feedback is appreciated. If you have specific recommendations, please consider creating an [issue](https://github.com/mprib/pyxy3d/issues). If you have more general questions or thoughts about the project, please open up a thread in the [discussions](https://github.com/mprib/pyxy3d/discussions).
 

pyxy3d/__init__.py

@@ -16,15 +16,30 @@
 __repo_issues_url__ = f"{__repo_url__}issues"
 
 
-# set up local app data folder and logging
-__app_dir__ = Path(os.getenv("LOCALAPPDATA"), __package_name__)
+# # set up local app data folder and logging
+# __app_dir__ = Path(os.getenv("LOCALAPPDATA"), __package_name__)
+# __app_dir__.mkdir(exist_ok=True, parents=True)
+
+# # create a toml file for user settings in LOCALAPPDATA and default the project folder to USER
+# __settings_path__ = Path(__app_dir__, "settings.toml")
+
+# __user_dir__ = Path(os.getenv("USERPROFILE"))
+# # __user_dir__.mkdir(exist_ok=True,parents=True)
+
+# Determine platform-specific application data directory
+if os.name == 'nt':  # Windows
+    app_data_dir = os.getenv('LOCALAPPDATA')
+else:  # macOS, Linux, and other UNIX variants
+    app_data_dir = os.path.join(os.path.expanduser("~"), '.local', 'share')
+
+__app_dir__ = Path(app_data_dir, __package_name__)
 __app_dir__.mkdir(exist_ok=True, parents=True)
 
-# create a toml file for user settings in LOCALAPPDATA and default the project folder to USER
-__settings_path__ = Path(__app_dir__, "settings.toml")
+# Create a toml file for user settings in app data directory and default the project folder to USER
+__settings_path__ = Path(__app_dir__, 'settings.toml')
 
-__user_dir__ = Path(os.getenv("USERPROFILE"))
-# __user_dir__.mkdir(exist_ok=True,parents=True)
+# Get user home directory in a cross-platform way
+__user_dir__ = Path(os.path.expanduser("~"))
 
 if __settings_path__.exists():
     USER_SETTINGS = toml.load(__settings_path__)