Open File
---------

.. uml::

    skinparam style strictuml
    hide footbox
    title Open File workflow

    actor User

    box "Client-side" #EDEDED
            participant Frontend
    end box

    box "Server-side" #lightblue
        participant Backend
    end box

    User -> Frontend: Open image
    activate Frontend
    Frontend -> Backend : 1. OPEN_FILE
    activate Backend
    Frontend <--[#red] Backend : <font color="red">2. OPEN_FILE_ACK [Check 1]</font>
    Frontend <-- Backend : 3. REGION_HISTOGRAM_DATA
    deactivate Backend
    deactivate Frontend

    User -> Frontend: Request tiles
    activate Frontend
    Frontend -> Backend : 4. ADD_REQUIRED_TILES
    activate Backend
    Frontend <--[#red] Backend : <font color="red">5. RASTER_TILE_DATA [Check 2]</font>
    deactivate Backend
    User <-- Frontend: Displays image
    deactivate Frontend

OPEN_FITS_GZ
~~~~~~~~~~~~~

See the `source code <https://github.com/CARTAvis/ICD-RxJS/blob/dev/src/test/OPEN_FITS_GZ.test.ts>`__.

This test verifies that a gzip-compressed FITS image file can be opened and rendered correctly.

1. Frontend sends: **OPEN_FILE** (``OpenFile``)

   .. code-block:: protobuf

     directory = "set_QA"
     file = "tu2310418.fits.gz"
     hdu = "0"
     file_id = 0
     render_mode = RASTER

2. Backend returns: **OPEN_FILE_ACK** (``OpenFileAck``) and **REGION_HISTOGRAM_DATA**

:red-text:`Check 1:` the OPEN_FILE_ACK should satisfy:

   - OPEN_FILE_ACK.success = True
   - OPEN_FILE_ACK.fileInfo.name = "tu2310418.fits.gz"

3. Frontend sends: **SET_CURSOR** at (2268, 2467) and **ADD_REQUIRED_TILES** (tile [0], ZFP quality 11)

4. Backend returns: **SPATIAL_PROFILE_DATA** and **RASTER_TILE_DATA**

:red-text:`Check 2:` the RASTER_TILE_DATA count = 3 (1 tile + 2 sync messages)

OPEN_IMAGE_APPEND
~~~~~~~~~~~~~~~~~

See the `source code <https://github.com/CARTAvis/ICD-RxJS/blob/dev/src/test/OPEN_IMAGE_APPEND.test.ts>`__.

This test verifies opening multiple image files sequentially without closing previous ones, confirming that multiple files can be open simultaneously.

1. Frontend sends: **OPEN_FILE** (``OpenFile``) for 4 files

   .. code-block:: protobuf

     file = "M17_SWex.fits", file_id = 0
     file = "M17_SWex.image", file_id = 1
     file = "M17_SWex.miriad", file_id = 2
     file = "M17_SWex.hdf5", file_id = 3

2. For each file, Backend returns: **OPEN_FILE_ACK** and **REGION_HISTOGRAM_DATA**

:red-text:`Check 1:` for each file, the OPEN_FILE_ACK should satisfy:

   - OPEN_FILE_ACK.success = True
   - OPEN_FILE_ACK.fileId matches expected file_id

3. For each file, Frontend sends: **SET_IMAGE_CHANNELS** with **ADD_REQUIRED_TILES** (tile [0], ZFP quality 11)

4. Backend returns: **RASTER_TILE_DATA**

:red-text:`Check 2:` the RASTER_TILE_DATA for each file should satisfy:

   - Tile dimensions: width = 160, height = 200 for all files
   - imageData.length > 0
   - nanEncodings.length > 0

:red-text:`Check 3:` REGION_HISTOGRAM_DATA for each file should satisfy:

   - regionId = -1, stokes = 0, progress = 1

OPEN_IMAGE_CASA_VARIENTS
~~~~~~~~~~~~~~~~~~~~~~~~~

See the `source code <https://github.com/CARTAvis/ICD-RxJS/blob/dev/src/test/OPEN_IMAGE_CASA_VARIENTS.test.ts>`__.

This test verifies opening multiple CASA image variants with different structures and formats.

1. Frontend sends: **OPEN_FILE** (``OpenFile``) for 5 CASA image variants

   .. code-block:: protobuf

     file = "componentlist.image", file_id = 200
     file = "concatenated.image", file_id = 201
     file = "pVimage.image", file_id = 202
     file = "UVamp.image", file_id = 203
     file = "UVphase.image", file_id = 204

2. Backend returns: **OPEN_FILE_ACK** and **REGION_HISTOGRAM_DATA** for each file

:red-text:`Check 1:` the OPEN_FILE_ACK should satisfy:

   - OPEN_FILE_ACK.success = True for all files

:red-text:`Check 2:` RASTER_TILE_DATA dimensions should match:

   - fileId 200: 256x256
   - fileId 201: 189x189
   - fileId 202: 160x52 (narrow PV image)
   - fileId 203: 150x150
   - fileId 204: 150x150

OPEN_IMAGE_PV
~~~~~~~~~~~~~

See the `source code <https://github.com/CARTAvis/ICD-RxJS/blob/dev/src/test/OPEN_IMAGE_PV.test.ts>`__.

This test verifies opening Position-Velocity (PV) images in both FITS and CASA formats.

1. Frontend sends: **OPEN_FILE** (``OpenFile``) for 2 PV images

   .. code-block:: protobuf

     file = "M17_SWex_pv.fits", file_id = 0
     file = "M17_SWex_pv.image", file_id = 1

2. Backend returns: **OPEN_FILE_ACK** and **REGION_HISTOGRAM_DATA** for each

:red-text:`Check 1:` the OPEN_FILE_ACK should satisfy:

   - OPEN_FILE_ACK.success = True
   - OPEN_FILE_ACK.fileInfo.name matches filename

:red-text:`Check 2:` histogram and tile data should satisfy:

   - REGION_HISTOGRAM_DATA.histograms.numBins = 109 for both files
   - RASTER_TILE_DATA dimensions: width = 241, height = 13 for both files

OPEN_SWAPPED_IMAGES
~~~~~~~~~~~~~~~~~~~

See the `source code <https://github.com/CARTAvis/ICD-RxJS/blob/dev/src/test/OPEN_SWAPPED_IMAGES.test.ts>`__.

This test verifies opening images with different axis orderings to ensure correct handling of swapped axes.

1. Frontend sends: **OPEN_FILE** (``OpenFile``) for 5 images with varying axis configurations

   .. code-block:: protobuf

     file = "HH211_IQU-swap-rfds.image"   (axes: RA-Freq-Dec-Stokes, 1049x5)
     file = "HH211_IQU-swap-rsdf.image"   (axes: RA-Stokes-Dec-Freq, 1049x1049)
     file = "HH211_IQU.fits"              (axes: RA-Dec-Freq-Stokes, 1049x1049)
     file = "HH211_IQU-swap-fdsr.image"   (axes: Freq-Dec-Stokes-RA, 5x1049)
     file = "supermosaic.10-cutted-stokes-glon-vard-glat.image" (483x51)

:red-text:`Check 1:` for each image, the OPEN_FILE_ACK should satisfy:

   - OPEN_FILE_ACK.success = True
   - fileInfoExtended axis numbers and dimensions match expected for each swap pattern

:red-text:`Check 2:` cursor values at specific positions should satisfy:

   - (510, 2): SpatialProfileData.value = 0.0015299528604373336
   - (555, 586): SpatialProfileData.value = 0.00048562639858573675
   - (4, 521): SpatialProfileData.value = 0.03848038613796234
   - (477, 12): SpatialProfileData.value = 20.193593978881836

OPENFILE_FITS_BEAMTABLE
~~~~~~~~~~~~~~~~~~~~~~~

See the `source code <https://github.com/CARTAvis/ICD-RxJS/blob/dev/src/test/OPENFILE_FITS_BEAMTABLE.test.ts>`__.

This test verifies that beam table information is correctly extracted from FITS format files.

1. Frontend sends: **OPEN_FILE** (``OpenFile``)

   .. code-block:: protobuf

     directory = "set_QA"
     file = "SDC335.579-0.292.spw0.line.fits"
     file_id = 0
     render_mode = RASTER

2. Backend returns: **OPEN_FILE_ACK** (``OpenFileAck``)

:red-text:`Check 1:` the OPEN_FILE_ACK should satisfy:

   - OPEN_FILE_ACK.success = True
   - fileInfo.type = CARTA.FileType.FITS
   - fileInfo.size = 1806465600
   - fileInfo.HDUList = ["0"]

:red-text:`Check 2:` the beam table entries should match at specific channels:

   - Channel 0: majorAxis = 5.927, minorAxis = 4.056, pa = -73.86
   - Channel 10: majorAxis = 6.085, minorAxis = 4.215, pa = -76.39
   - Channel 200: majorAxis = 6.154, minorAxis = 4.467, pa = -80.17
   - Channel 1000: majorAxis = 6.156, minorAxis = 4.468, pa = -80.17
   - Channel 2000: majorAxis = 6.158, minorAxis = 4.469, pa = -80.17
   - Channel 3839: majorAxis = 6.358, minorAxis = 4.732, pa = -85.62

OPENFILE_CASA_BEAMTABLE
~~~~~~~~~~~~~~~~~~~~~~~~

See the `source code <https://github.com/CARTAvis/ICD-RxJS/blob/dev/src/test/OPENFILE_CASA_BEAMTABLE.test.ts>`__.

This test verifies that beam table information is correctly extracted from CASA format files.

1. Frontend sends: **OPEN_FILE** (``OpenFile``)

   .. code-block:: protobuf

     directory = "set_QA"
     file = "SDC335.579-0.292.spw0.line.image"
     file_id = 0
     render_mode = RASTER

2. Backend returns: **OPEN_FILE_ACK** (``OpenFileAck``)

:red-text:`Check 1:` the OPEN_FILE_ACK should satisfy:

   - OPEN_FILE_ACK.success = True
   - fileInfo.type = CARTA.FileType.CASA
   - fileInfo.HDUList = [""]

:red-text:`Check 2:` the beam table entries should match identical values as the FITS beam table test at channels 0, 10, 200, 1000, 2000, and 3839