Enhance plot_MIP_with_mask_outlines with flexible unit handling and physical scaling

docs/source/tutorials/getting_started/project_setup_tutorial.ipynb

@@ -263,6 +263,74 @@
     "Let's create a custom configuration for a kidney dosimetry study:"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "id": "dd1729d3",
+   "metadata": {},
+   "source": [
+    "### Plot Colors Configuration\n",
+    "\n",
+    "The `voi_mappings_config.json` also includes a `plot_colors` section to customize how organs appear in MIP plots:\n",
+    "\n",
+    "**Default behavior**: Leave `plot_colors` empty `{}` to use matplotlib's automatic color cycle\n",
+    "\n",
+    "**Custom colors**: Add organ keywords mapped to colors (case-insensitive substring matching)\n",
+    "\n",
+    "Example:\n",
+    "```json\n",
+    "\"plot_colors\": {\n",
+    "    \"kidney\": \"lime\",\n",
+    "    \"liver\": \"#FFD700\",\n",
+    "    \"tumor\": \"red\",\n",
+    "    \"lesion\": \"magenta\"\n",
+    "}\n",
+    "```\n",
+    "\n",
+    "Colors can be:\n",
+    "- **Named colors**: `\"red\"`, `\"lime\"`, `\"cyan\"`, `\"magenta\"`, etc.\n",
+    "- **Hex codes**: `\"#FF5733\"`, `\"#00FF00\"`, etc.\n",
+    "- **Empty**: `{}` uses matplotlib's default color cycle for all organs\n",
+    "\n",
+    "The keyword matching is flexible - `\"kidney\"` will match `\"kidney_left\"`, `\"Kidney_Right\"`, `\"kidney_cyst\"`, etc."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "3cbdede6",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# Example: Customize plot colors for your study\n",
+    "import json\n",
+    "\n",
+    "# Load the mappings config\n",
+    "with open(mappings_path, 'r') as f:\n",
+    "    config = json.load(f)\n",
+    "\n",
+    "# Option 1: Use automatic colors (recommended for starting)\n",
+    "config['plot_colors'] = {}\n",
+    "\n",
+    "# Option 2: Set custom colors for specific organs\n",
+    "# Uncomment and customize as needed:\n",
+    "# config['plot_colors'] = {\n",
+    "#     \"kidney\": \"lime\",\n",
+    "#     \"liver\": \"#FFD700\",  # gold\n",
+    "#     \"spleen\": \"cyan\",\n",
+    "#     \"tumor\": \"red\",\n",
+    "#     \"lesion\": \"magenta\"\n",
+    "# }\n",
+    "\n",
+    "# Save the updated config\n",
+    "with open(mappings_path, 'w') as f:\n",
+    "    json.dump(config, f, indent=2)\n",
+    "\n",
+    "print(\"Plot colors configuration:\")\n",
+    "print(f\"  {config['plot_colors']}\")\n",
+    "print(\"\\nThese colors will be used by plot_MIP_with_mask_outlines()\")\n",
+    "print(\"Tip: Edit voi_mappings_config.json directly for permanent changes\")"
+   ]
+  },
   {
    "cell_type": "code",
    "execution_count": null,
@@ -442,8 +510,12 @@
     "   - Combine structures (e.g., all ribs → \"Skeleton\")\n",
     "\n",
     "2. **voi_mappings_config.json**\n",
-    "   - Map between naming conventions\n",
-    "   - Unify CT (morphology) and SPECT (activity) names\n",
+    "   - Map between naming conventions (CT ↔ SPECT)\n",
+    "   - Unify organ names across data sources\n",
+    "   - **NEW**: Configure plot colors for MIP visualizations\n",
+    "     - Leave `plot_colors` empty `{}` for automatic colors\n",
+    "     - Add custom colors: `{\"kidney\": \"lime\", \"tumor\": \"red\"}`\n",
+    "     - Supports matplotlib color names and hex codes\n",
     "\n",
     "### ✓ Customization Options\n",
     "- Selective templates (`templates=['config.json']`)\n",
@@ -453,12 +525,14 @@
     "### ✓ Best Practices\n",
     "- Start with `init_project()` for new studies\n",
     "- Customize config files for your specific organs of interest\n",
+    "- Configure plot colors in `voi_mappings_config.json` for consistent visualizations\n",
     "- Use standardized directory structure for reproducibility\n",
     "- Keep configs in version control (git) alongside analysis code\n",
     "\n",
     "## Next Steps\n",
     "\n",
     "- **Tutorial**: Check out the [TotalSegmentator Tutorial](./segmentation/total_segmentator_tutorial.ipynb) to use these configs\n",
+    "- **Plotting**: See `plot_MIP_with_mask_outlines()` in API docs for visualization examples\n",
     "- **Documentation**: See API Reference for detailed function signatures\n",
     "- **Examples**: Browse Data Ingestion Examples for real workflows\n",
     "\n",
@@ -510,6 +584,12 @@
     "\n",
     "**Remember**: Always edit the configuration files to match your specific study needs before running analysis workflows!"
    ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "eeff51a6",
+   "metadata": {},
+   "source": []
   }
  ],
  "metadata": {

pytheranostics/data/configuration_templates/voi_mappings_config.json

@@ -1,11 +1,15 @@
 {
-  "_instructions": "Map VOI names between different naming conventions.",
+  "_instructions": "Map VOI names between different naming conventions and configure visualization colors. Edit this file to customize organ name mappings and plot appearance.",
 
   "ct_mappings": {
     "organ_name_in_ct": "standardized_name"
   },
 
   "spect_mappings": {
     "organ_name_in_spect": "standardized_name"
+  },
+
+  "plot_colors": {
+    "_description": "Configure colors for organ contours in MIP plots. Add entries with organ names or keywords as keys (case-insensitive substring matching) and matplotlib color names or hex codes as values. Leave empty {} to use matplotlib's default color cycle. Example: 'kidney': 'lime', 'liver': '#FFD700', 'tumor': 'red'"
   }
 }

pytheranostics/plots/__init__.py

@@ -1 +1,9 @@
-"""PyTheranostics package."""
+"""Plotting utilities for PyTheranostics workflows."""
+
+from .plots import ewin_montage, plot_MIP_with_mask_outlines, plot_tac_residuals
+
+__all__ = [
+    "ewin_montage",
+    "plot_MIP_with_mask_outlines",
+    "plot_tac_residuals",
+]