Update QC report and workflow to produce necessary qa items during main run (#63)

* use niivue to dynamically render report with rotating heads
* serve nifti's to niivue over http
* scan niivue preview added to full report
* generating svg's for comparison w/ good ole nipype
* add entrypoint for qa reports
* standardize commands
* refactored from defaced dir to bids dir to make qa usage more clear
* clean up toml and fix import

Author: bendhouseart

README.md

@@ -78,6 +78,7 @@ options:
                         Options: 't1' (included T1w template), 'mni' (MNI template), or 'pet' 
                         (averaged PET image).
   --open_browser        Open browser to show QA reports after completion
+  --qa-port QA_PORT     Port for NIfTI preview server (default: 8000)
 ```
 
 Working example usage:
@@ -106,6 +107,68 @@ Example usage with template anatomical:
 petdeface /inputfolder /outputfolder --use_template_anat t1 --n_procs 16
 ```
 
+### Quality Assessment (QA) Reports
+
+PETdeface includes a comprehensive quality assessment system that generates reports to help validate defacing results. The QA system creates both SVG reports and interactive NIfTI viewers.
+
+#### QA Report Location
+
+QA reports are automatically generated in the input BIDS directory under `derivatives/petdeface/qa/`. This includes:
+- SVG reports showing before/after defacing comparisons
+- Interactive HTML viewers for 3D NIfTI visualization
+- An index page linking to all available reports
+
+#### Running QA Reports
+
+**Automatic QA generation:**
+```bash
+petdeface /inputfolder /outputfolder --open_browser
+```
+
+**Manual QA generation using the separate QA tool:**
+```bash
+petdeface-qa /inputfolder --open-browser --start-server
+```
+
+#### NIfTI Preview Server
+
+For 3D NIfTI visualization, PETdeface can start a local HTTP server to serve NIfTI files. This is required due to browser security restrictions.
+
+**Start with server:**
+```bash
+petdeface-qa /inputfolder --start-server --open-browser
+```
+
+**Custom port:**
+```bash
+petdeface-qa /inputfolder --start-server --qa-port 8080
+```
+
+#### QA Tool Options
+
+The `petdeface-qa` command provides the following options:
+
+```bash
+usage: petdeface-qa [-h] bids_dir [--output-dir OUTPUT_DIR] 
+                    [--open-browser] [--start-server] [--qa-port QA_PORT]
+
+Generate SVG QA reports for PET deface workflow.
+
+positional arguments:
+  bids_dir               BIDS directory containing the defaced dataset (with derivatives/petdeface)
+
+options:
+  -h, --help            show this help message and exit
+  --output-dir OUTPUT_DIR, --output_dir OUTPUT_DIR
+                        Output directory for HTML files (default: derivatives/petdeface/qa/)
+  --open-browser        Open browser automatically
+  --start-server        Start local HTTP server for NIfTI file access (required for NIfTI viewers)
+  --qa-port QA_PORT, --qa_port QA_PORT
+                        Port for NIfTI preview server (default: 8000)
+```
+
+**Note**: The NIfTI preview server is required for 3D visualization due to browser CORS restrictions. Keep the terminal running while viewing NIfTI files.
+
 ### Docker Usage
 
 Requirements:

docs/modules.rst

@@ -26,6 +26,14 @@ petdeface.petdeface module
 --------------------------
 
 .. automodule:: petdeface.petdeface
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+petdeface.qa module
+------------------
+
+.. automodule:: petdeface.qa
     :members:
     :undoc-members:
     :show-inheritance:

docs/usage.rst

@@ -127,6 +127,7 @@ options:
                         Options: 't1' (included T1w template), 'mni' (MNI template), or 'pet' 
                         (averaged PET image).
   --open_browser        Following defacing this flag will open the browser to view the defacing results
+  --qa-port QA_PORT     Port for NIfTI preview server (default: 8000)
 
 Docker Based
 ------------
@@ -205,4 +206,76 @@ Example usage with template anatomical:
 
 .. code-block:: bash
 
-    petdeface /inputfolder /outputfolder --use_template_anat t1 --n_procs 16
+    petdeface /inputfolder /outputfolder --use_template_anat t1 --n_procs 16
+
+Quality Assessment (QA) Reports
+------------------------------
+
+PETdeface includes a comprehensive quality assessment system that generates reports to help validate defacing results. The QA system creates both SVG reports and interactive NIfTI viewers.
+
+QA Report Location
+~~~~~~~~~~~~~~~~~
+
+QA reports are automatically generated in the input BIDS directory under ``derivatives/petdeface/qa/``. This includes:
+
+- SVG reports showing before/after defacing comparisons
+- Interactive HTML viewers for 3D NIfTI visualization  
+- An index page linking to all available reports
+
+Running QA Reports
+~~~~~~~~~~~~~~~~~
+
+**Automatic QA generation:**
+
+.. code-block:: bash
+
+    petdeface /inputfolder /outputfolder --open_browser
+
+**Manual QA generation using the separate QA tool:**
+
+.. code-block:: bash
+
+    petdeface-qa /inputfolder --open-browser --start-server
+
+NIfTI Preview Server
+~~~~~~~~~~~~~~~~~~~
+
+For 3D NIfTI visualization, PETdeface can start a local HTTP server to serve NIfTI files. This is required due to browser security restrictions.
+
+**Start with server:**
+
+.. code-block:: bash
+
+    petdeface-qa /inputfolder --start-server --open-browser
+
+**Custom port:**
+
+.. code-block:: bash
+
+    petdeface-qa /inputfolder --start-server --qa-port 8080
+
+QA Tool Options
+~~~~~~~~~~~~~~
+
+The ``petdeface-qa`` command provides the following options:
+
+.. code-block:: bash
+
+    usage: petdeface-qa [-h] bids_dir [--output-dir OUTPUT_DIR] 
+                        [--open-browser] [--start-server] [--qa-port QA_PORT]
+
+    Generate SVG QA reports for PET deface workflow.
+
+    positional arguments:
+      bids_dir               BIDS directory containing the defaced dataset (with derivatives/petdeface)
+
+    options:
+      -h, --help            show this help message and exit
+      --output-dir OUTPUT_DIR, --output_dir OUTPUT_DIR
+                            Output directory for HTML files (default: derivatives/petdeface/qa/)
+      --open-browser        Open browser automatically
+      --start-server        Start local HTTP server for NIfTI file access (required for NIfTI viewers)
+      --qa-port QA_PORT, --qa_port QA_PORT
+                            Port for NIfTI preview server (default: 8000)
+
+**Note**: The NIfTI preview server is required for 3D visualization due to browser CORS restrictions. Keep the terminal running while viewing NIfTI files.

petdeface/pet.py

@@ -12,6 +12,11 @@
 
 class WeightedAverageInputSpec(BaseInterfaceInputSpec):
     pet_file = File(exists=True, desc="Dynamic PET", mandatory=True)
+    sidecar_file = File(
+        exists=True,
+        desc="Optional sidecar JSON file for timing info. If not provided, uses sidecar from pet_file.",
+        mandatory=False,
+    )
 
 
 class WeightedAverageOutputSpec(TraitedSpec):
@@ -47,9 +52,18 @@ def _run_interface(self, runtime):
         img = nib.load(pet_file)
         data = img.get_fdata()
 
-        meta = ReadSidecarJSON(
-            in_file=pet_file, bids_dir=bids_dir, bids_validate=False
-        ).run()
+        # Use optional sidecar file if provided, otherwise use pet_file's sidecar
+        if hasattr(self.inputs, "sidecar_file") and self.inputs.sidecar_file:
+            sidecar_file = self.inputs.sidecar_file
+            sidecar_bids_dir = os.path.dirname(sidecar_file)
+            meta = ReadSidecarJSON(
+                in_file=sidecar_file, bids_dir=sidecar_bids_dir, bids_validate=False
+            ).run()
+        else:
+            # Default behavior: use pet_file's sidecar
+            meta = ReadSidecarJSON(
+                in_file=pet_file, bids_dir=bids_dir, bids_validate=False
+            ).run()
 
         frames_start = np.array(meta.outputs.out_dict["FrameTimesStart"])
         frames_duration = np.array(meta.outputs.out_dict["FrameDuration"])