Update to new Jupyter Notebook Examples

.gitignore

@@ -1,3 +1,14 @@
 /.venv
 /.venv39
 /exit
+*.log
+*.cu3s
+.history/*
+output/
+save/
+.ipynb_checkpoints/
+tiff_export
+pansharpen_export/
+view_export
+envi_export/
+cube_export/

Example_1_Take_Snapshot.ipynb

@@ -0,0 +1,333 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "id": "91abd7ea-4c7e-4eb4-97d1-4746e9d24212",
+   "metadata": {},
+   "source": [
+    "# Cuvis Python SDK Example 1\n",
+    "## Connect to camera and record a measurement\n",
+    "\n",
+    "This example provides a minimal starting point to allow you to get a camera and data acquisition running.\n",
+    "\n",
+    "**Used principles:**\n",
+    " - *AcquisitionContext* for camera control and data acquisition\n",
+    " - *SessionFile* as camera calibration file\n",
+    " - *CubeExporter* for saving measurements\n",
+    "\n",
+    "**Step-by-Step outline:**\n",
+    " 1. Import and initialize Cuvis SDK\n",
+    " 2. Load the calibration file for your camera using *SessionFile*\n",
+    " 3. Connect and initialize your camera using the *AcquisitionContext*\n",
+    " 4. Acquire a measurement\n",
+    " 5. Save the measurement to disk using the *CubeExporter*\n",
+    "\n",
+    "**Prerequisites to running this example:**\n",
+    " - Have a camera connected *or* downloaded the provided [demo data](https://drive.google.com/drive/folders/1Cjb0v_a2p1cCmhKH8w2OuRtnhXCJGz61?usp=sharing)\n",
+    " - Have the camera calibration file (*SN*.cu3c) ready *or* use the [demo data](https://drive.google.com/drive/folders/1Cjb0v_a2p1cCmhKH8w2OuRtnhXCJGz61?usp=sharing)\n",
+    " - Have the Cuvis SDK installed\n",
+    " - Have Python and the requirements.txt installed"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "b3391452-d716-4fb2-8977-fa95b09b54ff",
+   "metadata": {},
+   "outputs": [
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "Cuvis Python SDK Example 1\n",
+      "Initializing Cuvis\n"
+     ]
+    },
+    {
+     "name": "stderr",
+     "output_type": "stream",
+     "text": [
+      "c:\\Users\\nima.ghorbani\\code-repos\\cuvis.python.examples\\.venv\\Lib\\site-packages\\cuvis\\General.py:4: UserWarning: pkg_resources is deprecated as an API. See https://setuptools.pypa.io/en/latest/pkg_resources.html. The pkg_resources package is slated for removal as early as 2025-11-30. Refrain from using this package or pin to Setuptools<81.\n",
+      "  import pkg_resources\n"
+     ]
+    }
+   ],
+   "source": [
+    "# If the import of cuvis fails, the most common cause is a mismatch between\n",
+    "# the _cuvis_ python package and the installed version of the Cuvis SDK.\n",
+    "# Try re-installing both and make sure that the version numbers match exactly\n",
+    "import cuvis\n",
+    "import time\n",
+    "\n",
+    "print(\"Cuvis Python SDK Example 1\")\n",
+    "\n",
+    "# Initialize the Cuvis SDK using a settings-directory\n",
+    "# This is optional (all settings have defaults),\n",
+    "# but enables you to optimize Cuvis' performance on your system using the settings\n",
+    "# Your camera and the default Cuvis installation both provide these settings files\n",
+    "print(\"Initializing Cuvis\")\n",
+    "cuvis.General.init(\"./settings\")"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 20,
+   "id": "d345b826-29ba-4090-a7fa-4a016bd62905",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# Snapshot setup / User input\n",
+    "# Enter your data here!\n",
+    "import os\n",
+    "\n",
+    "snapshot_integration_time_ms = 100\n",
+    "save_directory = \"./output\" # set to a location where you want to save the data\n",
+    "\n",
+    "has_camera = False  # Set to True if you have a camera connected\n",
+    "camera_serial_number_str = \"Your camera serial here\"\n",
+    "\n",
+    "# If using demo data instead of a physical camera, change this to your download location:\n",
+    "demo_session_file = \"./SDK_Training_Example_Data/WinterUlm_X20P.cu3s\"\n",
+    "assert os.path.exists(demo_session_file), f\"Demo session file not found: {demo_session_file}\"\n",
+    "\n",
+    "camera_calibration_file_path = F\"./factory/{camera_serial_number_str}.cu3c\""
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "abc495f9-4143-4383-87d4-8fde6b79438f",
+   "metadata": {},
+   "source": [
+    "#### Calibration Files (.cu3c)\n",
+    "This calibration file contains everything needed to connect to and process data from your camera.\n",
+    "The **.cu3c** camera calibration file format is a special form of the SessionFile format **.cu3s**\n",
+    "\n",
+    "It is thus used as a calibration file and usually contains (among other things):\n",
+    " - The actual encrypted camera calibration file\n",
+    " - A spectral radiance calibration file\n",
+    " - Test references (Dark and White)\n",
+    " - A standard camera recording configuration (framerate, integration time, etc.)"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 21,
+   "id": "34fdcae0-4b4b-49a3-b426-8bfa78f3d716",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# Skip this if working without a physical camera\n",
+    "if has_camera:\n",
+    "    print(\"Load camera calibration file\")\n",
+    "    calib = cuvis.SessionFile(camera_calibration_file_path)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "e89674e2-697d-40f0-940f-850ef34d55d7",
+   "metadata": {},
+   "source": [
+    "#### Cube Exporter\n",
+    "To save measurements in the Cubert file format *SessionFile* (.cu3s), use the *CubeExporter*.\n",
+    "Using *SessionFiles* to save measurements, is highly recommended, as it can store multiple raw measurements, reference measurements and meta-data\n",
+    "all in one file, allowing you to re-process the measurements after the fact.\n",
+    "This enables you to fine-tune the final product, convert the output format and even fix some mistakes made during data acquisition."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 22,
+   "id": "05024d39-f138-42c7-abdc-9cd0a5c5b581",
+   "metadata": {},
+   "outputs": [
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "Create CubeExporter\n"
+     ]
+    }
+   ],
+   "source": [
+    "# Setup the Cube Exporter for saving the measurements to disk in the SessionFile format (.cu3s)\n",
+    "print(\"Create CubeExporter\")\n",
+    "save_config = cuvis.FileWriteSettings.SaveArgs(export_dir=save_directory)\n",
+    "exporter = cuvis.CubeExporter(save_config)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "1a6f730c-2bbe-46b1-8d53-7ef351620ae6",
+   "metadata": {},
+   "source": [
+    "#### Acquisition Context\n",
+    "The *Acquisition Context* is your interface to control the camera and all aspects of the data acquisition.\n",
+    "\n",
+    "Initialize it using a *SessionFile* object, then set the recording parameters and start an acquisition.\n",
+    "As soon as the **AcquisitionContext** is created, it will try to establish a connection with the camera.\n",
+    "\n",
+    "Here, the \"Software\" operation mode is used to enable data acquisition using a software trigger.\n",
+    "This is also called snapshot mode.\n",
+    "\n",
+    "*Please note:*\n",
+    "The *AcquisitionContext* will **only** connect to the **exact** camera of the same serial number matching the calibration file!\n",
+    "All other cameras/devices are ignored."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 23,
+   "id": "b47e7223-b588-4b4d-8059-f15b44c8cfb2",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# Skip this if working without a physical camera\n",
+    "if has_camera:\n",
+    "    # Create an AcquisitionContext to connect to the camera\n",
+    "    print(\"Loading Acquisition Context\")\n",
+    "    acq = cuvis.AcquisitionContext(calib)\n",
+    "\n",
+    "    # Wait for camera connection to be established\n",
+    "    print(\"Connecting with camera\")\n",
+    "    while(not acq.ready):\n",
+    "        time.sleep(1)\n",
+    "        print(\".\", end=\"\")\n",
+    "    print(\"\\nCamera connected!\")\n",
+    "\n",
+    "    # Set camera to software trigger\n",
+    "    acq.operation_mode = cuvis.OperationMode.Software\n",
+    "    acq.integration_time = snapshot_integration_time_ms"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "3587f5af-9e8b-4e4a-853c-669f95469446",
+   "metadata": {},
+   "source": [
+    "#### Simulated Acquisition - great for testing without a camera\n",
+    "The *Acquisition Context* can be initialized with the **simulated** kwarg set to **True** to pretend it has a camera connected.\n",
+    "In this mode, it will provide the measurements from a *SessionFile* as if they where received from a physically connected camera.\n",
+    "Upon reaching the end of the file, it will loop back to the first measurement.\n",
+    "\n",
+    "With this simulated camera, you can record and test your code as if a physical camera was connected.\n",
+    "Some methods/attributes don't have any effect, as they cannot relay changes to a camera, eg. integration time, auto-exposure, gain, etc."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 24,
+   "id": "4080c54c-6341-4257-bbd4-d555372d8798",
+   "metadata": {},
+   "outputs": [
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "Wait for Acqusition Context to be ready...\n",
+      "\n",
+      "Simulated camera loaded!\n"
+     ]
+    }
+   ],
+   "source": [
+    "# Simulated Acquisition: Skip this if working with a physical camera\n",
+    "if not has_camera:\n",
+    "    session = cuvis.SessionFile(demo_session_file)\n",
+    "    # Initialize the Acquisition Context in simulated camera mode\n",
+    "    acq = cuvis.AcquisitionContext(session, simulate=True)\n",
+    "\n",
+    "# Wait for the Acquisition Context to load the demo session file\n",
+    "print(\"Wait for Acqusition Context to be ready...\")\n",
+    "while(not acq.ready):\n",
+    "    time.sleep(1)\n",
+    "    print(\".\", end=\"\")\n",
+    "print(\"\\nSimulated camera loaded!\")\n",
+    "\n",
+    "# Set simulated camera to software trigger\n",
+    "acq.operation_mode = cuvis.OperationMode.Software"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "05924e40-63d1-40fb-9d7f-6c1253cae974",
+   "metadata": {},
+   "source": [
+    "#### Capturing a Measurement with Software Trigger (Single Snapshot)\n",
+    "Using the `capture()` method, a single measurement is initiated.\n",
+    "Taking a snapshot requires some time, so, to prevent the call to `capture()` from blocking execution, an *AsyncMesu* is returned.\n",
+    "To await the completion of the snapshot, use the `get()` method on the *AsyncMesu*. "
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 30,
+   "id": "99a6438c-70b7-4403-9b61-44385ff32a0e",
+   "metadata": {},
+   "outputs": [
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "Measurement reports: AsyncResult.done\n"
+     ]
+    }
+   ],
+   "source": [
+    "# Optional: Name the recording\n",
+    "acq.session_info = cuvis.SessionData(\"My_Measurement\", 0, 0)\n",
+    "\n",
+    "# With the camera connection established, a measurement can be triggered using the capture() method.\n",
+    "# This returns an AsyncMesu object\n",
+    "async_mesu = acq.capture()\n",
+    "\n",
+    "# To get the actual measurement, wait on the AsyncMesu using the get() method.\n",
+    "mesu, status = async_mesu.get(timeout_ms=5000)\n",
+    "print(F\"Measurement reports: {status}\")\n"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 31,
+   "id": "7e6633d5-b1ed-4570-a1b6-5ed1b2dec105",
+   "metadata": {},
+   "outputs": [
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "Measurement exported!\n"
+     ]
+    }
+   ],
+   "source": [
+    "# Export the measurement - write the data to the disk in SessionFile format using the CubeExporter\n",
+    "if status == cuvis.Async.AsyncResult.done:\n",
+    "    exporter.apply(mesu)\n",
+    "    print(\"Measurement exported!\")\n",
+    "else:\n",
+    "    print(\"Something went wrong!\")"
+   ]
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": ".venv (3.12.7)",
+   "language": "python",
+   "name": "python3"
+  },
+  "language_info": {
+   "codemirror_mode": {
+    "name": "ipython",
+    "version": 3
+   },
+   "file_extension": ".py",
+   "mimetype": "text/x-python",
+   "name": "python",
+   "nbconvert_exporter": "python",
+   "pygments_lexer": "ipython3",
+   "version": "3.12.7"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 5
+}