:topic: Saving and Loading State

.. index::
   triple: DREAM3D-NX; Quad View; State

.. _QuadViewSavingState:

Saving and Loading State
##########################

**In this section we describe how to save the entire Quad View module
layout to a file and restore it later.**

The Quad View module can serialize its complete state — every loaded
data source, every open tab, and each tab's full set of control
settings — into a single ``.d3dstate`` file that can be reopened to
bring the module back exactly where it left off.

What Is Saved
==============

A Quad View ``.d3dstate`` file captures:

-  **Geometry Browser contents**: the full list of loaded data sources
   (pipeline runs and ``.dream3d`` files) along with their geometry
   children, in tree order.

-  **Tab list**: every Quad View tab is written out, plus the
   currently-active tab index.

-  **Per-tab control state**:

   -  Loaded geometry path
   -  Oblique reslice and thick-slab toggles, plus the thick-slab blend
      mode (Mean / Min Intensity / Max Intensity)
   -  Plane outline visibility, color legend visibility, stats annotation
      visibility, and the length-units text
   -  Active array name and active component (or magnitude)
   -  Per-array color preset, opacity transfer function control points,
      and custom data range
   -  Volume rendering blend mode
   -  Volume lighting parameters — shading on/off, ambient, diffuse,
      specular, specular power, light-follows-camera, SSAO, GI reach,
      volumetric scattering
   -  Reslice cursor center and orientation (so oblique-rotated planes
      restore to the same angles)

The file is plain JSON, so it can be inspected or hand-edited if needed.
A malformed file is reported to the application output console rather
than crashing the application.

What Is Not Saved
==================

The state file does **not** contain the underlying voxel data — only
references to the data sources that produced it. When a state file is
loaded:

-  ``.dream3d`` data sources are re-read from the paths stored in the
   file. If a referenced file no longer exists or has moved, that data
   source will fail to load and a warning is printed to the application
   output console; the rest of the layout is restored anyway.

-  Pipeline-derived data sources cannot be restored automatically — the
   originating pipeline must be re-run to repopulate them. The geometry
   browser entries are still listed but their geometries will not be
   available until the pipeline produces them again.

The current camera position / zoom in each window is also not persisted;
each restored pane resets its cameras to a centered framing of the data.

Saving the Current State
==========================

1. Make sure the Quad View module is the active dock by clicking on it.

2. From the application **File** menu, choose **Save State…**.

3. In the file dialog, pick a destination folder, type a file name, and
   click **Save**. The ``.d3dstate`` extension is appended automatically
   if it is not typed.

   The dialog uses your platform's native file chooser. On Windows and
   Linux the type filter shows ``DREAM3D-NX State Files (*.d3dstate)``;
   on macOS the native dialog hides the filter UI and saves the file
   with the ``.d3dstate`` extension automatically.

The file is written atomically using a ``QSaveFile`` so a partially
written file is never produced even if the application is interrupted
during the write.

Loading a Saved State
======================

Loading is supported in two ways.

**Via the File menu**

1. From the application **File** menu, choose **Load State…**.

2. In the file dialog, navigate to the ``.d3dstate`` file you want to
   open and click **Open**. The dialog uses your platform's native file
   chooser; the same filtering caveat noted under
   *Saving the Current State* applies.

**Via Drag and Drop**

   Drag a ``.d3dstate`` file from your system file browser and drop it
   anywhere onto the Quad View module area. The drop is recognized
   automatically and the file is loaded just as if it had been opened
   from the File menu.

In both cases the existing layout is replaced by the layout described in
the file. Any unsaved control changes in the current layout are lost, so
save first if those changes are worth keeping.

.. note::

   Loading a state file that does not match the Quad View JSON shape
   (for example, a state file written by a different DREAM3D-NX module)
   is reported as a parse error in the application output console and
   leaves the current Quad View layout untouched.

.. Local variables:
   coding: utf-8
   mode: text
   mode: rst
   End:
   vim: fileencoding=utf-8 filetype=rst :