CARTAvis · confluence · May 3, 2023 · Jan 31, 2023 · Feb 2, 2023 · Feb 8, 2023
diff --git a/control/region.proto b/control/region.proto
@@ -12,6 +12,8 @@ message SetRegion {
     sfixed32 region_id = 2;
     // Region parameters
     RegionInfo region_info = 3;
+    // Update region for pv preview only
+    bool preview_region = 4;
 }
 
 

diff --git a/control/stop_pv_calc.proto b/control/stop_pv_calc.proto
@@ -2,6 +2,16 @@ syntax = "proto3";
 package CARTA;
 
 message StopPvCalc {
-    // Stop the PV image calculation with respect to the image file id
+    // Stop the PV image calculation for the image file id
     sfixed32 file_id = 1;
 }
+
+message StopPvPreview {
+    // Stop the PV preview for the preview viewer id
+    sfixed32 preview_id = 1;
+}
+
+message ClosePvPreview {
+    // Close the PV preview for the preview viewer id
+    sfixed32 preview_id = 1;
+}
diff --git a/docs/src/changelog.rst.txt b/docs/src/changelog.rst.txt
@@ -188,14 +188,17 @@ Changelog
      - Added ``keep`` to :carta:ref:`MomentRequest` message.
    * - ``28.4.0``
      - 05/12/22
-     - Added additional fields to :carta:ref:`FittingRequest` and :carta:ref:`FittingResponse` for generating model and residual images. Added :carta:ref:`FittingProgress` and :carta:ref:`StopFitting` messages for updaing progress and canceling tasks.
+     - Added additional fields to :carta:ref:`FittingRequest` and :carta:ref:`FittingResponse` for generating model and residual images. Added :carta:ref:`FittingProgress` and :carta:ref:`StopFitting` messages for updating progress and canceling tasks.
    * - ``28.5.0``
+     - 23/03/02
+     - Added sub-message :carta:ref:`PvPreviewSettings` to :carta:ref:`PvRequest` and message :carta:ref:`PvPreviewData` to :carta:ref:`PvResponse` for generating a PV preview image. Added :carta:ref:`StopPvPreview` to cancel preview image and :carta:ref:`ClosePvPreview` to release preview resources.
+   * - ``28.6.0``
      - 10/01/23
      - Added axes numbers to :carta:ref:`FileInfoExtended` message for dealing with swapped axes image cubes.
-   * - ``28.6.0``
+   * - ``28.7.0``
      - 17/03/23
      - Added additional fields to :carta:ref:`FittingResponse` for image fitting background offset as a free parameter.
-   * - ``28.7.0``
+   * - ``28.8.0``
      - 23/03/23
      - Added annotation regions to :carta:ref:`RegionType` and added additional style parameters in :carta:ref:`AnnotationStyle` to :carta:ref:`RegionStyle`.
 

diff --git a/docs/src/defs.rst.txt b/docs/src/defs.rst.txt
@@ -939,6 +939,55 @@ Source file: `shared/defs.proto <https://github.com/CARTAvis/carta-protobuf/blob
      - 
      - 
 
+.. carta:class:: carta-sub pvpreviewsettings
+
+.. _pvpreviewsettings:
+
+PvPreviewSettings
+~~~~~~~~~~~~~~~~~
+
+Source file: `shared/defs.proto <https://github.com/CARTAvis/carta-protobuf/blob/dev/shared/defs.proto>`_
+
+Preview parameters of a :carta:refc:`PV_REQUEST`
+
+.. list-table::
+   :widths: 20 20 20 40
+   :header-rows: 1
+   :class: proto
+
+   * - Field
+     - Type
+     - Label
+     - Description
+   * - preview_id
+     - sfixed32
+     - 
+     - Preview ID for the PV preview viewer
+   * - region_id
+     - sfixed32
+     - 
+     - Region ID for the subimage in the xy plane
+   * - rebin_xy
+     - sfixed32
+     - 
+     - Downsampling in xy axes
+   * - rebin_z
+     - sfixed32
+     - 
+     - Downsampling in z axis
+   * - compression_type
+     - :carta:refc:`CompressionType`
+     - 
+     - The compression algorithm to use
+   * - image_compression_quality
+     - float
+     - 
+     - Compression quality from frontend performance preferences
+   * - animation_compression_quality
+     - float
+     - 
+     - 
+
 .. carta:class:: carta-sub regioninfo
 
 .. _regioninfo:

diff --git a/docs/src/enums.rst.txt b/docs/src/enums.rst.txt
@@ -531,6 +531,15 @@ Source file: `shared/enums.proto <https://github.com/CARTAvis/carta-protobuf/blo
    * - :carta:refc:`STOP_FITTING`
      - 84
      - 
+   * - :carta:refc:`PV_PREVIEW_DATA`
+     - 85
+     - 
+   * - :carta:refc:`STOP_PV_PREVIEW`
+     - 86
+     - 
+   * - :carta:refc:`CLOSE_PV_PREVIEW`
+     - 87
+     - 
 
 .. carta:class:: carta-sub filefeatureflags
 

diff --git a/docs/src/messages.rst.txt b/docs/src/messages.rst.txt
@@ -387,6 +387,31 @@ Instructs the backend to close a file with a given file ID
      - 
      - Which "file" slot to close
 
+.. carta:class:: carta-f2b closepvpreview
+
+.. _closepvpreview:
+
+ClosePvPreview
+~~~~~~~~~~~~~~
+
+Source file: `control/stop_pv_calc.proto <https://github.com/CARTAvis/carta-protobuf/blob/dev/control/stop_pv_calc.proto>`_
+
+
+
+.. list-table::
+   :widths: 20 20 20 40
+   :header-rows: 1
+   :class: proto
+
+   * - Field
+     - Type
+     - Label
+     - Description
+   * - preview_id
+     - sfixed32
+     - 
+     - Close the PV preview for the preview viewer id
+
 .. carta:class:: carta-f2b concatstokesfiles
 
 .. _concatstokesfiles:
@@ -1448,6 +1473,67 @@ Response for :carta:refc:`OPEN_FILE`. Also supplies file information
      - repeated
      - :carta:refc:`Beam` table for multiple-beam images
 
+.. carta:class:: carta-b2f pvpreviewdata
+
+.. _pvpreviewdata:
+
+PvPreviewData
+~~~~~~~~~~~~~
+
+Source file: `stream/pv_preview.proto <https://github.com/CARTAvis/carta-protobuf/blob/dev/stream/pv_preview.proto>`_
+
+Data stream for PV preview image
+
+.. list-table::
+   :widths: 20 20 20 40
+   :header-rows: 1
+   :class: proto
+
+   * - Field
+     - Type
+     - Label
+     - Description
+   * - preview_id
+     - sfixed32
+     - 
+     - Preview ID for the PV preview viewer
+   * - image_info
+     - :carta:refc:`FileInfoExtended`
+     - 
+     - Image extended file info
+   * - image_data
+     - bytes
+     - 
+     - Image data. For uncompressed data, this is converted into FP32, while for compressed data, this is passed to the compression library for decompression.
+   * - nan_encodings
+     - bytes
+     - 
+     - Run-length encodings of NaN values used to restore the NaN values after decompression.
+   * - width
+     - sfixed32
+     - 
+     - Dimensions of data
+   * - height
+     - sfixed32
+     - 
+     - 
+   * - compression_type
+     - :carta:refc:`CompressionType`
+     - 
+     - The compression algorithm used
+   * - compression_quality
+     - float
+     - 
+     - Compression quality switch
+   * - histogram_bounds
+     - :carta:refc:`FloatBounds`
+     - 
+     - :carta:refc:`Histogram` min/max, for rendering
+   * - histogram
+     - :carta:refc:`Histogram`
+     - 
+     - :carta:refc:`Histogram`, to tune rendering
+
 .. carta:class:: carta-b2f pvprogress
 
 .. _pvprogress:
@@ -1471,11 +1557,15 @@ Source file: `request/pv_request.proto <https://github.com/CARTAvis/carta-protob
    * - file_id
      - sfixed32
      - 
+     - File ID of the source image for the PV generator
+   * - preview_id
+     - sfixed32
      - 
+     - Preview ID of the PV preview viewer
    * - progress
      - float
      - 
-     - 
+     - Progress indicator, ranging from 0 to 1
 
 .. carta:class:: carta-f2b pvrequest
 
@@ -1500,27 +1590,31 @@ Source file: `request/pv_request.proto <https://github.com/CARTAvis/carta-protob
    * - file_id
      - sfixed32
      - 
-     - 
+     - File ID of the source image
    * - region_id
      - sfixed32
      - 
-     - 
+     - Region ID of the PV cut in the source image
    * - width
      - sfixed32
      - 
-     - 
+     - Averaging width along PV cut
    * - spectral_range
      - :carta:refc:`IntBounds`
      - 
-     - 
+     - Range of channels to be used in velocity axis
    * - reverse
      - bool
      - 
-     - 
+     - Flag whether to generate [Spatial, Spectral] image or reverse
    * - keep
      - bool
      - 
+     - Flag whether to keep or replace previously-generated images
+   * - preview_settings
+     - :carta:refc:`PvPreviewSettings`
      - 
+     - Parameters for preview mode
 
 .. carta:class:: carta-b2f pvresponse
 
@@ -1545,19 +1639,23 @@ Source file: `request/pv_request.proto <https://github.com/CARTAvis/carta-protob
    * - success
      - bool
      - 
-     - 
+     - Defines whether :carta:refc:`PV_REQUEST` was successful
    * - message
      - string
      - 
-     - 
+     - Error message (if applicable)
    * - open_file_ack
      - :carta:refc:`OpenFileAck`
      - 
+     - PV generator result: generated PV image
+   * - preview_data
+     - :carta:refc:`PvPreviewData`
      - 
+     - PV preview result: generated PV image
    * - cancel
      - bool
      - 
-     - 
+     - Defines whether :carta:refc:`PV_REQUEST` was canceled
 
 .. carta:class:: carta-b2f rastertiledata
 
@@ -2463,6 +2561,10 @@ Creates or updates a region. Backend responds with :carta:refc:`SET_REGION_ACK`
      - :carta:refc:`RegionInfo`
      - 
      - Region parameters
+   * - preview_region
+     - bool
+     - 
+     - Update region for pv preview only
 
 .. carta:class:: carta-b2f setregionack
 
@@ -3132,7 +3234,32 @@ Source file: `control/stop_pv_calc.proto <https://github.com/CARTAvis/carta-prot
    * - file_id
      - sfixed32
      - 
-     - Stop the PV image calculation with respect to the image file id
+     - Stop the PV image calculation for the image file id
+
+.. carta:class:: carta-f2b stoppvpreview
+
+.. _stoppvpreview:
+
+StopPvPreview
+~~~~~~~~~~~~~
+
+Source file: `control/stop_pv_calc.proto <https://github.com/CARTAvis/carta-protobuf/blob/dev/control/stop_pv_calc.proto>`_
+
+
+
+.. list-table::
+   :widths: 20 20 20 40
+   :header-rows: 1
+   :class: proto
+
+   * - Field
+     - Type
+     - Label
+     - Description
+   * - preview_id
+     - sfixed32
+     - 
+     - Stop the PV preview for the preview viewer id
 
 .. carta:class:: carta-b2f vectoroverlaytiledata
 

diff --git a/request/pv_request.proto b/request/pv_request.proto
@@ -3,24 +3,43 @@ package CARTA;
 
 import "defs.proto";
 import "open_file.proto";
+import "pv_preview.proto";
 
 message PvRequest {
+    // File ID of the source image
     sfixed32 file_id = 1;
+    // Region ID of the PV cut in the source image
     sfixed32 region_id = 2;
+    // Averaging width along PV cut
     sfixed32 width = 3;
+    // Range of channels to be used in velocity axis
     IntBounds spectral_range = 4;
+    // Flag whether to generate [Spatial, Spectral] image or reverse
     bool reverse = 5;
+    // Flag whether to keep or replace previously-generated images
     bool keep = 6;
+    // Parameters for preview mode
+    PvPreviewSettings preview_settings = 7;
 }
 
 message PvResponse {
+    // Defines whether PV_REQUEST was successful
     bool success = 1;
+    // Error message (if applicable)
     string message = 2;
+    // PV generator result: generated PV image
     OpenFileAck open_file_ack = 3;
-    bool cancel = 4;
+    // PV preview result: generated PV image
+    PvPreviewData preview_data = 4;
+    // Defines whether PV_REQUEST was canceled
+    bool cancel = 5;
 }
 
 message PvProgress {
+    // File ID of the source image for the PV generator
     sfixed32 file_id = 1;
-    float progress = 2;
+    // Preview ID of the PV preview viewer
+    sfixed32 preview_id = 2;
+    // Progress indicator, ranging from 0 to 1
+    float progress = 3;
 }