docs: keep state file guidance focused on saving and loading

Author: PaulHax

docs/quick_start_guide.md

@@ -66,4 +66,4 @@ VolView reads the DICOM tags of your data to determine appropriate preset parame
 
 ## 4. Saving / loading state
 
-Once you have made the measures and generated the visualizations that you want to store to recall later or share with others, use the icons at the top of the toolbar to Load and Save state files. For more information on the json format of these state files and how they can be used to integrate VolView with workflows and other services, see [State Files](state_files.html).
+Use the Load and Save icons in the toolbar to reopen or save your images, annotations, and view settings. See [State Files](./state_files.md) for details on saving and sharing your work.

docs/state_files.md

@@ -1,174 +1,17 @@
 # State Files
 
-VolView state files save your scene configuration: annotations, camera positions, colormaps, layouts, and more. There are two formats:
+State files save your scene so you can return to your work later or share it with others. They preserve annotations, segmentations, camera positions, colormaps, layouts, and other view settings.
 
-## Zip State Files (`*.volview.zip`)
+## Saving a Scene
 
-Save by clicking the "Disk" icon in the toolbar. This embeds your image data that was loaded from local files alongside the application state. Useful for sharing annotations with collaborators.
+Click the **Save** (disk) icon in the toolbar to download a `*.volview.zip` file. Images loaded from local files are included alongside the saved scene.
 
-## Sparse Manifest Files (`*.volview.json`)
+## Linked State Files
 
-JSON files that reference remote data via URIs instead of embedding it. Useful for:
+A `*.volview.json` file references data hosted on a server instead of including it in the file. This lets workflows and external applications open a prepared scene without copying large datasets. Anyone opening the scene needs access to the referenced data.
 
-- Linking to data hosted on servers
-- Sharing annotations without duplicating large datasets
-- Integrating with external systems (AI pipelines, access control, etc.)
+## Loading a Saved Scene
 
-## Manifest (version 7.0.0)
-
-Both formats carry this manifest. A segmentation owns one image's segment masks;
-labelmaps encode those masks for storage or interchange. The top-level `segments`
-list holds the identities the masks paint and the tools draw with, each mask names
-the segment it carries voxels for, and `order` lists the masks of that
-segmentation. A mask `order` leaves out is skipped on restore. `selectedSegment`
-names the segment that was selected.
-
-A segment has a `name` and an RGBA `color`. It may also state `visible` and
-`locked`, which default to `true` and `false`, and `fillOpacity`, `outlineOpacity`
-and `strokeWidth`, which fall back to the app defaults. A segmentation may state
-the `fillOpacity`, `outlineOpacity` and `outlineThickness` of the image's Display
-settings. Rulers, rectangles and polygons under `tools` name their segment with
-`segmentId`.
-
-A segment the file lists takes over an existing segment of the same name that
-holds no masks or shapes yet, such as one a configuration defined. If that
-segment already holds content, the restored one gets a numbered name like
-`Tumor (2)`.
-
-A mask saved into a zip names its own archive entry with `path`. A sparse
-manifest instead points at a whole label volume: `segmentationArtifacts` names
-that volume, its `dataSourceId` says where the bytes come from, and each mask
-whose `artifactId` points at it is filled from the `sourceValue` it declares, 1
-when omitted.
-An artifact is a single-component label volume; one with several components is
-skipped on restore. Extents are placeholders until the volume is read. A value
-no mask reads, including every value of a volume no mask points at, gets its
-segment the way loading that volume on its own would: it joins an existing
-segment of its name, even one holding content on another image, unless that
-segment already has a mask on this image, in which case the value gets a new
-segment with a numbered name.
-
-```json
-{
-  "version": "7.0.0",
-  "dataSources": [
-    { "id": 0, "type": "uri", "uri": "https://example.com/scan.zip" },
-    { "id": 1, "type": "uri", "uri": "https://example.com/segmentation.nii.gz" }
-  ],
-  "segments": [
-    {
-      "id": "segment-tumor",
-      "name": "Tumor",
-      "color": [255, 0, 0, 255],
-      "visible": true,
-      "locked": false
-    }
-  ],
-  "segmentations": [
-    {
-      "id": "segmentation-0",
-      "name": "Tumor Segmentation",
-      "parentImage": "0",
-      "masks": [
-        {
-          "id": "mask-tumor",
-          "segmentId": "segment-tumor",
-          "representations": {
-            "labelmap": {
-              "artifactId": "labelmap-1",
-              "sourceValue": 1,
-              "extent": [0, -1, 0, -1, 0, -1]
-            }
-          }
-        }
-      ],
-      "order": ["mask-tumor"]
-    }
-  ],
-  "segmentationArtifacts": [
-    {
-      "id": "labelmap-1",
-      "parentImage": "0",
-      "name": "Tumor Segmentation",
-      "dataSourceId": 1
-    }
-  ],
-  "selectedSegment": "segment-tumor",
-  "tools": {
-    "rectangles": {
-      "tools": [
-        {
-          "imageID": "0",
-          "frameOfReference": {
-            "planeNormal": [0, 0, 1],
-            "planeOrigin": [0, 0, 50]
-          },
-          "slice": 50,
-          "firstPoint": [-20, -20, 50],
-          "secondPoint": [20, 20, 50],
-          "segmentId": "segment-tumor"
-        }
-      ]
-    }
-  }
-}
-```
-
-## Legacy 6.x manifest (still read on import)
-
-Manifests up to version 6.4.0, such as this 6.2.0 one, are migrated on load: the
-historical `segmentGroups` field becomes the current segmentation model, and the
-per-tool `labels` records become segments the tools reference by id. Nothing
-writes this form any more.
-
-```json
-{
-  "version": "6.2.0",
-  "dataSources": [
-    { "id": 0, "type": "uri", "uri": "https://example.com/scan.zip" },
-    { "id": 1, "type": "uri", "uri": "https://example.com/segmentation.nii.gz" }
-  ],
-  "segmentGroups": [
-    {
-      "id": "seg-1",
-      "dataSourceId": 1,
-      "metadata": {
-        "name": "Tumor Segmentation",
-        "parentImage": "0",
-        "segments": {
-          "order": [1],
-          "byValue": {
-            "1": { "value": 1, "name": "Tumor", "color": [255, 0, 0, 255] }
-          }
-        }
-      }
-    }
-  ],
-  "tools": {
-    "rectangles": {
-      "tools": [
-        {
-          "imageID": "0",
-          "frameOfReference": {
-            "planeNormal": [0, 0, 1],
-            "planeOrigin": [0, 0, 50]
-          },
-          "slice": 50,
-          "firstPoint": [-20, -20, 50],
-          "secondPoint": [20, 20, 50],
-          "label": "lesion"
-        }
-      ],
-      "labels": {
-        "lesion": { "color": "red" }
-      }
-    }
-  }
-}
-```
-
-## Loading State Files
-
-- **Drag and drop** onto VolView
-- **File browser** via the "Folder" icon below the save button
-- **URL parameter**: `?urls=[https://example.com/session.volview.json]`
+- Drag and drop a state file onto VolView.
+- Click the **Load** (folder) icon in the toolbar and select a state file.
+- Open a link that includes a state file in the `urls` parameter, such as `?urls=[https://example.com/session.volview.json]`.