CARTA Interface Control Document

Date

14 August 2023

Authors

Angus Comrie, Rob Simmonds and the CARTA development team

Version

28.13.0

ICD Version Integer

28

CARTA Target

Version 4.0

Changelog

Version	Date	Description
0.1.7	30/08/18	Added optional field channel_histogram_data to the image view message
0.1.8	07/09/18	Added computed_entries map to the File Info Extended message
0.1.9	10/09/18	Changed computed_entries map to an array of HeaderEntry messages
0.1.10	10/09/18	Added optional field spatial_requirements to the SET_CURSOR message
0.1.11	20/09/18	Added file_id field to SET_REGION and fixed control points typo
0.1.12	18/10/18	Deprecated channel_vals field in SPECTRAL_PROFILE_DATA
0.1.13	30/11/18	Added details on per-cube histogram calculations
0.1.14	07/02/19	Added $BASE folder placeholder
0.1.15	05/03/19	Added target version info
0.1.16	25/03/19	Removed stokes, channel_min and channel_max fields from SET_REGION, and changed StatisticsValue value field to a double type.
0.1.17	27/03/19	Added NumPixels and NanCount stats types
0.1.18	28/03/19	Changed rotation units from radians to degrees
0.2.0	07/05/19	Changed message header information, adjusted stats enum values, added double value support for spectral profile
0.2.1	09/05/19	Added feature flag enums as well as event type enums. Updated animation information and sequence diagrams to include flow control
0.2.2	14/05/19	Added information on tiled rendering
4.0.0	02/07/19	Expanded sequence diagrams and text on tiled rendering and animation. Changed version numbering to match ICD version integer
4.0.1	04/07/19	Fixed incorrect sequence diagrams for file loading
5.0.0	15/07/19	Switched to byte fields instead of repeated float/double for efficiency reasons in spatial and spectral profile messages
6.0.0	19/07/19	Animation ID and timestamps for ACKs
7.0.0	23/07/19	Region file browser and import/export messages
7.0.1	08/08/19	Region export coordinate type
8.0.0	21/08/19	Added messages for retrieving and setting user preferences and layouts
9.0.0	17/10/19	Added/updated messages for contour parameters and streaming
10.0.0	25/10/19	Updated messages for contour streaming
11.0.0	20/11/19	Added messages to resume the session and its ACK
12.0.0	18/02/20	Updated messages for tiled rendering usage during animation
13.0.0	19/05/20	Updated messages for scripting service information (WIP)
14.0.0	28/05/20	Updated messages for catalogs
15.0.0	04/07/20	Added date field to file info, reordered file types alphabetically
16.0.0	23/07/20	Added sub-message for region style, replace RegionProperties with map
17.0	27/07/20	Added spectral line request and response
17.1.0	11/08/20	Non-breaking change: added map of matched frames for spectral matched animation
17.2.0	12/08/20	Non-breaking change: added intensity limit field to line ID query
18.0.0	11/12/20	Added extrema enum value to StatsType. Removed deprecated messages: SetUserLayout, SetUserLayoutAck, SetUserPreferences, SetUserPreferencesAck, and SetRegionRequirements.
18.1.0	08/01/21	Non-breaking change: added beam_table (of type Beam) to OpenFileAck.
19.0.0	07/01/21	Adjusted FileInfoResponse to include map of extended file info messages
20.0.0	13/04/21	Added ConcatStokesFiles messages
20.1.0	23/04/21	Renamed REGION_WRITE_ACCESS to READ_ONLY in ServerFeatureFlags.
20.2.0	26/04/21	Added additional fields to SaveFile for sub-image support.
21.0.0	05/05/21	Added ListProgress and StopFileList messages
22.0.0	28/06/21	Added DirectoryInfo message.
23.0.0	28/06/21	Added SpatialConfig submessage with fields for spatial profile mip and range, and added mip field to SpatialProfile. Updated comments for SpatialConfig and SpectralConfig.
23.1.0	23/07/21	Added SplataloguePing and SplataloguePong messages.
23.1.1	29/07/21	Added return_path to ScriptingRequest message.
24.0.0	30/07/21	Added the stokes to SetStatsRequirements, HistogramConfig, and RegionHistogramData messages. Removed the channel from Histogram.
24.1.0	12/10/21	Added platform_strings to RegisterViewerAck message.
24.2.0	11/11/21	Added filter_mode to FileListRequest, CatalogListRequest and RegionListRequest messages; Added Unknown to CatalogFileType.
25.0.0	06/12/21	Added PvRequest, PvResponse, PvProgress, and StopPvCalc messages for PV generator.
26.0.0	13/01/22	Removed grpc_port from RegisterViewerAck message. Renamed GRPC_SCRIPTING to SCRIPTING in ServerFeatureFlags. Removed all references to gRPC in docs.
26.1.0	01/03/22	Added lel_expr to OpenFile message.
26.2.0	19/04/22	Added rest_freq to SaveFile message.
27.0.0	21/04/22	Added FittingRequest and FittingResponse messages for image fitting.
27.1.0	27/04/22	Added Ptotal, Plinear, PFtotal, PFlinear, and Pangle to PolarizationType enum. Added stokes_indices to StartAnimation message.
27.2.0	05/05/22	Added SetVectorOverlayParameters and VectorOverlayTileData messages. Moved TileData to shared.
27.3.0	09/05/22	Added width to SetSpatialRequirements and LineProfileAxis to SpatialProfile.
28.0.0	07/06/22	Removed spectral line request/response and Splatalogue ping/pong messages.
28.1.0	17/06/22	Added region_id and fov_info to FittingRequest message.
28.2.0	08/09/22	Added spectral_range, reverse, and keep to PvRequest message.
28.3.0	30/11/22	Added keep to MomentRequest message.
28.4.0	05/12/22	Added additional fields to FittingRequest and FittingResponse for generating model and residual images. Added FittingProgress and StopFitting messages for updating progress and canceling tasks.
28.5.0	10/01/23	Added axes numbers to FileInfoExtended message for dealing with swapped axes image cubes.
28.6.0	17/03/23	Added additional fields to FittingResponse for image fitting background offset as a free parameter.
28.7.0	23/03/23	Added annotation regions to RegionType and added additional style parameters in AnnotationStyle to RegionStyle.
28.8.0	14/04/23	Added number of bins and pixel bounds to HistogramConfig in SetHistogramRequirements message. Added HistogramConfig to RegionHistogramData message.
28.9.0	28/04/23	Added sub-message PvPreviewSettings to PvRequest and message PvPreviewData to PvResponse for generating a PV preview image. Added StopPvPreview to cancel preview image and ClosePvPreview to release preview resources.
28.10.0	18/05/23	Added lel_expr to ImageProperties message.
28.11.0	20/06/23	Added support_aips_beam to FileInfoRequest, OpenFile, and ImageProperties messages.
28.12.0	15/08/23	Added sync_id and tile_count to RasterTileSync and RasterTileData messages.
28.13.0	23/08/23	Added integrated flux to FittingResponse message.

Versioning

• Major version change (1.2.3 -> 2.0.0): this is a breaking change.

• Minor version change (1.2.3 -> 1.3.0): this is added functionality which is optional and non-breaking.

• Patch (1.2.3 -> 1.2.4): this is a change which does not affect functionality (e.g. a typo fix in a comment, or a changed field name).

Some legacy changelog entries may not follow this approach. Only changes to the protocol buffer source files should be recorded here; changes only to this documentation do not require a version bump.

Contents:

• 1. Introduction
• 2. Context
• 3. Behaviour
  • 3.1. Connection
  • 3.2. File browsing
  • 3.3. Data cube navigation
    • 3.3.1. Zooming and panning
    • 3.3.2. Channel navigation
    • 3.3.3. Animation
  • 3.4. Changing view parameters
  • 3.5. Region selection and statistics
    • 3.5.1. Region creation
    • 3.5.2. Cursor updates
    • 3.5.3. Region requirements
    • 3.5.4. Per-cube histograms
  • 3.6. Data streaming
  • 3.7. User preferences
  • 3.8. Resume the session
  • 3.9. Catalog overlay
    • 3.9.1. Sequence Diagrams
  • 3.10. Moments generator
  • 3.11. Image fitting
• 4. Layer descriptions
  • 4.1. Application Layer
  • 4.2. Presentation layer
  • 4.3. Session Layer
  • 4.4. Transport Layer
• 5. Protocol buffer reference
  • 5.1. Messages
    • 5.1.1. AddRequiredTiles
    • 5.1.2. AnimationFlowControl
    • 5.1.3. CatalogFileInfoRequest
    • 5.1.4. CatalogFileInfoResponse
    • 5.1.5. CatalogFilterRequest
    • 5.1.6. CatalogFilterResponse
    • 5.1.7. CatalogListRequest
    • 5.1.8. CatalogListResponse
    • 5.1.9. CloseCatalogFile
    • 5.1.10. CloseFile
    • 5.1.11. ClosePvPreview
    • 5.1.12. ConcatStokesFiles
    • 5.1.13. ConcatStokesFilesAck
    • 5.1.14. ContourImageData
    • 5.1.15. ContourSet
    • 5.1.16. ErrorData
    • 5.1.17. ExportRegion
    • 5.1.18. ExportRegionAck
    • 5.1.19. FileInfoRequest
    • 5.1.20. FileInfoResponse
    • 5.1.21. FileListRequest
    • 5.1.22. FileListResponse
    • 5.1.23. FittingProgress
    • 5.1.24. FittingRequest
    • 5.1.25. FittingResponse
    • 5.1.26. ImageProperties
    • 5.1.27. ImportRegion
    • 5.1.28. ImportRegionAck
    • 5.1.29. MomentProgress
    • 5.1.30. MomentRequest
    • 5.1.31. MomentResponse
    • 5.1.32. OpenCatalogFile
    • 5.1.33. OpenCatalogFileAck
    • 5.1.34. OpenFile
    • 5.1.35. OpenFileAck
    • 5.1.36. PvPreviewData
    • 5.1.37. PvProgress
    • 5.1.38. PvRequest
    • 5.1.39. PvResponse
    • 5.1.40. RasterTileData
    • 5.1.41. RasterTileSync
    • 5.1.42. RegionFileInfoRequest
    • 5.1.43. RegionFileInfoResponse
    • 5.1.44. RegionHistogramData
    • 5.1.45. RegionListRequest
    • 5.1.46. RegionListResponse
    • 5.1.47. RegionStatsData
    • 5.1.48. RegisterViewer
    • 5.1.49. RegisterViewerAck
    • 5.1.50. RemoveRegion
    • 5.1.51. RemoveRequiredTiles
    • 5.1.52. ResumeSession
    • 5.1.53. ResumeSessionAck
    • 5.1.54. SaveFile
    • 5.1.55. SaveFileAck
    • 5.1.56. ScriptingRequest
    • 5.1.57. ScriptingResponse
    • 5.1.58. SetContourParameters
    • 5.1.59. SetCursor
    • 5.1.60. SetHistogramRequirements
    • 5.1.61. SetImageChannels
    • 5.1.62. SetRegion
    • 5.1.63. SetRegionAck
    • 5.1.64. SetSpatialRequirements
    • 5.1.65. SetSpectralRequirements
    • 5.1.66. SetStatsRequirements
    • 5.1.67. SetVectorOverlayParameters
    • 5.1.68. SpatialConfig
    • 5.1.69. SpatialProfileData
    • 5.1.70. SpectralConfig
    • 5.1.71. SpectralProfileData
    • 5.1.72. StartAnimation
    • 5.1.73. StartAnimationAck
    • 5.1.74. StatsConfig
    • 5.1.75. StokesFile
    • 5.1.76. StopAnimation
    • 5.1.77. StopFileList
    • 5.1.78. StopFitting
    • 5.1.79. StopMomentCalc
    • 5.1.80. StopPvCalc
    • 5.1.81. StopPvPreview
    • 5.1.82. VectorOverlayTileData
  • 5.2. Sub-messages
    • 5.2.1. AnimationFrame
    • 5.2.2. AnnotationStyle
    • 5.2.3. AxesNumbers
    • 5.2.4. Beam
    • 5.2.5. CatalogFileInfo
    • 5.2.6. CatalogHeader
    • 5.2.7. CatalogImageBounds
    • 5.2.8. ColumnData
    • 5.2.9. Coosys
    • 5.2.10. DirectoryInfo
    • 5.2.11. DoubleBounds
    • 5.2.12. DoublePoint
    • 5.2.13. FileInfo
    • 5.2.14. FileInfoExtended
    • 5.2.15. FilterConfig
    • 5.2.16. FloatBounds
    • 5.2.17. GaussianComponent
    • 5.2.18. HeaderEntry
    • 5.2.19. Histogram
    • 5.2.20. HistogramConfig
    • 5.2.21. ImageBounds
    • 5.2.22. IntBounds
    • 5.2.23. LineProfileAxis
    • 5.2.24. ListProgress
    • 5.2.25. MatchedFrameList
    • 5.2.26. Point
    • 5.2.27. PvPreviewSettings
    • 5.2.28. RegionInfo
    • 5.2.29. RegionStyle
    • 5.2.30. SpatialProfile
    • 5.2.31. SpectralProfile
    • 5.2.32. StatisticsValue
    • 5.2.33. TileData
  • 5.3. Enums
    • 5.3.1. CatalogFileType
    • 5.3.2. ClientFeatureFlags
    • 5.3.3. ColumnType
    • 5.3.4. ComparisonOperator
    • 5.3.5. CompressionType
    • 5.3.6. CoordinateType
    • 5.3.7. EntryType
    • 5.3.8. ErrorSeverity
    • 5.3.9. EventType
    • 5.3.10. FileFeatureFlags
    • 5.3.11. FileListFilterMode
    • 5.3.12. FileListType
    • 5.3.13. FileType
    • 5.3.14. FittingSolverType
    • 5.3.15. Moment
    • 5.3.16. MomentAxis
    • 5.3.17. MomentMask
    • 5.3.18. PointAnnotationShape
    • 5.3.19. PolarizationType
    • 5.3.20. ProfileAxisType
    • 5.3.21. RegionType
    • 5.3.22. RenderMode
    • 5.3.23. ServerFeatureFlags
    • 5.3.24. SessionType
    • 5.3.25. SmoothingMode
    • 5.3.26. SortingType
    • 5.3.27. StatsType
    • 5.3.28. TextAnnotationPosition