CARTA Documentation

CARTA DocumentationRelease 1.3

CARTA team

Sep 18, 2020

CARTA user manual for v1.3 and v1.3.1

1 Introduction 31.1 The mission of CARTA . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31.2 Client-Server architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31.3 Codebase and releases . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31.4 Getting help . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51.5 Contributors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51.6 Software citation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61.7 Acknowledgement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61.8 Copyright and License . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7

2 Installation and configuration 92.1 CARTA-server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92.2 CARTA-desktop: macOS 10.14/10.15 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92.3 CARTA-desktop: Ubuntu 16.04 LTS/18.04 LTS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102.4 CARTA-desktop: Redhat 7 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112.5 CARTA-desktop: Redhat 6 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122.6 Command line startup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132.7 Troubleshooting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15

3 Graphical user interface 193.1 Components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 193.2 Quickstart guide . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20

3.2.1 Image viewing interactions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 203.2.2 Region of interest interactions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 203.2.3 Cursor update . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 213.2.4 Chart interactions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21

3.3 Getting help . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 213.4 Configuring the layout . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21

3.4.1 Resizing a panel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 213.4.2 Relocating a tab as a new panel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 223.4.3 Relocating a tab to another panel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 223.4.4 Maximizing and restoring a panel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 223.4.5 Detaching and attaching a tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 223.4.6 Creating a widget as a floating widget or as a tab . . . . . . . . . . . . . . . . . . . . . . . 223.4.7 Light and dark theme . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 223.4.8 Custom layout, save, and restore . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22

3.5 User preferences . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23

i

3.6 Mouse interactions with images . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 253.6.1 Zooming . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 253.6.2 Panning . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25

3.7 Mouse interactions with region of interest . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 253.7.1 Region creation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 253.7.2 Region selection and modification . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25

3.8 Mouse interactions with charts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 263.8.1 Zooming . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 263.8.2 Panning . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 263.8.3 Resetting range . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26

3.9 Controls and shortcuts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26

4 Image cube visualization 294.1 Server-side status and session resume . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 294.2 File browser . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30

4.2.1 HDF5 (IDIA schema) image support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 314.3 Image viewer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 314.4 Tiled rendering . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 324.5 Render configuration of a raster image . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 334.6 Contour rendering . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 344.7 Match images in world coordinates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 364.8 Changing image view . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 374.9 Cursor information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 374.10 Configuring an image plot . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 384.11 Animator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38

5 Image cube analysis tools 395.1 Region of interest . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 395.2 Spatial profiler . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 415.3 Spectral profiler . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 425.4 Stokes analysis widget . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 435.5 Statistics widget . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 445.6 Histogram widget . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44

6 Appendix A: version history 456.1 Version 1.3.1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 456.2 Version 1.3 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 456.3 Version 1.2.2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 466.4 Version 1.2.1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 466.5 Version 1.2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 466.6 Version 1.1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 466.7 Version 1.0.1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 476.8 Version 1.0 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47

7 Appendix B: known issues 497.1 Stability and performace . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 497.2 File browser . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 497.3 Animator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 497.4 Contour configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 507.5 Image viewer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 507.6 Spectral profiler . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 507.7 Stokes analysis . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 507.8 Region of interest . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 507.9 GUI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51

ii

8 Appendix C: development log 538.1 v1.2 -> v1.3 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 538.2 v1.1 -> v1.2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 538.3 v1.0 -> v1.1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53

Index 55

iii

CARTA Documentation, Release 1.3

Note: CARTA v1.4 is released on 17th of September 2020. V1.4 user manual is available now.

CARTA user manual for v1.3 and v1.3.1 1

https://doi.org/10.5281/zenodo.3377984

https://carta.readthedocs.io/en/1.4/


2 CARTA user manual for v1.3 and v1.3.1

CHAPTER 1

Introduction

1.1 The mission of CARTA

CARTA is the Cube Analysis and Rendering Tool for Astronomy, a new image visualization and analysis tool designedfor the ALMA, the VLA, and the SKA pathfinders - MeerKAT and ASKAP. As the image size increases drasticallywith modern telescopes in recent years, viewing an image with a local image viewer or with a remote image viewervia the ssh protocol plus X11 tunneling or the VNC becomes much less efficient. The mission of CARTA is to provideusability and scalability for the future by utilizing modern web technologies and computing parallelization.

1.2 Client-Server architecture

CARTA uses a client-server architecture which is suitable for visualizing images with large file sizes (GB to TB) easilyobtained from ALMA, VLA, or SKA pathfinders (MeerKAT and ASKAP) observations. It is practically difficult toprocess such a huge file with personal computer or laptop. By using a client-server architecture, computation anddata storage are handled by remote enterprise-class servers or clusters with high performance storage, while processedproducts are sent to clients only for visualization with modern web features, such as GPU-accelerated rendering. Thisarchitecture also enables users to interact with the ALMA and VLA science archives by using CARTA as an interface.

1.3 Codebase and releases

CARTA is an open-source project. Its source code is available at https://github.com/CARTAvis.

CARTA has two flavors: CARTA-server and CARTA-desktop. The former is intended for hosting multiple users withan enterprise-class server, while the later is intedned for single-user usage with a personal computer or a laptop. Thedesktop version can also be used in the “remote” mode, where the backend (server) is run in a remote server and thefrontend (client) is run locally with an internet browser.

Deployment of CARTA in a server environment may require addtional efforts of server configurations, suchas user authentication, server load balance, or resource monitoring, etc. Please contact the CARTA Helpdesk([email protected]) for consultations.

3

https://github.com/CARTAvis

mailto:[email protected]



Installation guides for the desktop version are provided in the section Installation and configuration, including theusages of the remote mode.

The release plan and major goals are the following:

• v1.0: Basic image and profile viewing capability (released 29th December 2018)

• v1.1: Initial support of region of interest, ROI (released 2nd May 2019)

– basic ROI for single image including rectangle and ellipse

– ROI statistics

– ROI spectral profile

– ROI histogram

– HDF5-IDIA image format support

– Improved remote version

– Performance and memory usage improvements

• v1.2: performance and usability improvement (released 28th August 2019)

– New server authentication method

– User preferences and layouts

– Tiled rendering and animator enhancement

– support point and polygon regions

– support region import/export in crtf syntax

– introducing enhanced profile delivery strategies

– new Stokes analysis widget

– support HDF5 images under IDIA schema

• v1.3: WCS matching (current release)

– Contour rendering

– Raster image matching in world coordinates

– Contour image matching in world coordinates

– Image matching in spectral domain

– Drag-to-pan support

– Spectral conversion in the spectral profiler

– Enhanced usability with “Active” region type

– Enhanced “remote” mode

– Optional low-bandwidth mode for poor network connections

– Offline in-app help manual

– Bug fixes and performance improvements

• v1.4: Catalogue overlay and analysis tools (subject to change)

– Catalogue overlay

– WCS region of interest

4 Chapter 1. Introduction


– Animator improvement for spatially and spectrally matched images

– Mip map support in HDF5 (IDIA schema) format

– Initial support of scripting interface in Python3

– Server-side authentication improvements

– Profile smoothing

– Moment map generator

– Line catalogue overlay

• Into the future (this is a non-exclusive list of features we would like in subsequent releases but these are notdecided upon yet, and depend on feedback from users, resourcing etc. )

– Polarization contour and images

– Interactive CLEAN with CASA

– Multi-panel view

– Channel map view

– View other image formats including complex value images

– Position-velocity map generator

– Collaborative tools

– Vector field rendering

– Volume rendering

– Profile, histogram, and image fitting tools

– Scripting interface (Python3)

– Three-color blender

1.4 Getting help

The CARTA team welcomes any suggestion, feature request, or bug report, to make CARTA better via

• CARTA Helpdesk ([email protected])

• Github Issue (https://github.com/CARTAvis/carta/issues)

1.5 Contributors

The development of the CARTA project is a joint effort from (in alphabetical order):

• Academia Sinica, Institute of Astronomy and Astrophysics (ASIAA)

• Inter-university Institute for Data Intensive Astronomy (IDIA)

• National Radio Astronomy Observatory (NRAO)

• Department of Physics, University of Alberta

1.4. Getting help 5



https://github.com/CARTAvis/carta/issues

https://github.com/CARTAvis/carta/issues

https://www.asiaa.sinica.edu.tw

https://idia.ac.za

https://science.nrao.edu

https://www.ualberta.ca/physics


1.6 Software citation

Please use the following DOI as a citation when using CARTA for publications.

The bibtex is

@software{angus_comrie_2018_3377984,author = {Angus Comrie and

Kuo-Song Wang andPamela Harris andAnthony Moraghan andShou-Chieh Hsu andAdrianna Pinska andCheng-Chin Chiang andHengtai Jan andRob Simmonds andTien-Hao Chang andMing-Yi Lin},

title = {{CARTA: The Cube Analysis and Rendering Tool forAstronomy}},

month = dec,year = 2018,publisher = {Zenodo},doi = {10.5281/zenodo.3377984},url = {https://doi.org/10.5281/zenodo.3377984}}

1.7 Acknowledgement

ASIAA CASA Development Center (ACDC) acknowledges the grant from the Ministry of Science and Technologyof Taiwan for the ALMA-NA collaboration.

The Inter-University Institute for Data Intensive Astronomy is a partnership of three South African universities: theUniversity of Cape Town, the University of the Western Cape and the University of Pretoria.

The National Radio Astronomy Observatory is a facility of the National Science Foundation operated under coopera-tive agreement by Associated Universities, Inc.

The Department of Physics at the University of Alberta has contributed to the CARTA project thanks to support fromthe National Radio Astronomy Observatory under an ALMA Development Project and from the Canada Foundationfor Innovation as part of the Canadian Initiative for Radio Astronomy Data Analysis (CIRADA).

CARTA is mainly built in C++, TypeScript, and JavaScript, and with the following third-party libraries:

• AST: http://starlink.eao.hawaii.edu/starlink/AST

• Blueprint: https://blueprintjs.com

• casacore: https://casacore.github.io

• CASA source code: https://casa.nrao.edu/index.shtml

• Chart.js: https://www.chartjs.org

• Electron: https://electronjs.org

• GoldenLayout: https://golden-layout.com


https://doi.org/10.5281/zenodo.3377984

http://starlink.eao.hawaii.edu/starlink/AST

https://blueprintjs.com

https://casacore.github.io

https://casa.nrao.edu/index.shtml

https://www.chartjs.org

https://electronjs.org

https://golden-layout.com


• jsoncpp: https://github.com/open-source-parsers/jsoncpp

• MobX: https://mobx.js.org

• MongoDB: https://www.mongodb.com

• React: https://reactjs.org

• TBB: https://www.threadingbuildingblocks.org

The source code of CARTA is hosted on Github.

The CARTA development team is grateful to David Berry for consultation of the AST library and to Kumar Golap forconsultation of the casacore library.

1.8 Copyright and License

Copyright (C) 2018-2020 ASIAA, IDIA, NRAO, and Department of Physics, University of Alberta. This program isfree software; you can redistribute it and/or modify it under the terms of the GNU General Public License version 3 aspublished by the Free Software Foundation.

1.8. Copyright and License 7

https://github.com/open-source-parsers/jsoncpp

https://mobx.js.org

https://www.mongodb.com

https://reactjs.org

https://www.threadingbuildingblocks.org

https://github.com/CARTAvis

http://www.gnu.org/copyleft/gpl.html

CHAPTER 2

Installation and configuration

CARTA v1.3 supports the following operating systems:

• macOS 10.14/10.15

• Ubuntu 16.04 LTS/18.04 LTS

• RedHat 7

• RedHat 6 (conditional)

Command line to launch CARTA is supported (see Command line startup for instructions).

CARTA utilizes discrete or integrated GPU for image rendering. For users who wish to run CARTA from a remoteRedHat 6/7 or Ubuntu 16.04 LTS/18.04 LTS server via the ssh protocol, CARTA v1.3 also provides a “remote” modefor this use case (see Command line startup for instructions). As the majority of servers do not have onboard GPUs,the remote mode runs the CARTA “backend” on the server, while the CARTA “frontend” is accessed through yourweb browser of choice running on your local machine. This allows your local machine’s GPU to perform the imagerendering, while the remote server handles the storage and CPU/RAM intensive tasks.

If there is any problem, please contact CARTA Helpdesk for help.

2.1 CARTA-server

The installation and configuration of the server version is available through CARTA Helpdesk. The CARTA teamwould be happy to work with you on getting CARTA-server installed on your server.

2.2 CARTA-desktop: macOS 10.14/10.15

Please follow the steps:

1. Download the DMG installer file

2. Open the DMG file and drag the CARTA icon to your /Applications folder.

9



https://github.com/CARTAvis/carta-releases/releases/download/v1.3.1/CARTA-v1.3.1.dmg


3. To run CARTA either:

a) Find the CARTA icon in the Launchpad and click it, or double click it in the Finder.

b) (Highly recommended) Create an alias in your ~/.bashrc file by opening your ~/.bashrc file in a texteditor and add the following line:

alias carta='/Applications/CARTA.app/Contents/MacOS/CARTA'

Then, after entering source ~/.bashrc in the terminal, you will be able to start CARTA by simply typing“carta”.

source ~/.bashrccarta

Note: If you see a prompt with “CARTA can’t be opended because Apple cannot check it for malicious software.”,please go to System preferences -> Security & Privacy and hit the Open anyway button to launch CARTA.

2.3 CARTA-desktop: Ubuntu 16.04 LTS/18.04 LTS


1. Download the tgz file

2. Unzip the tgz file

tar -xvf CARTA-v1.3.1-ubuntu.tgz

3. To run CARTA either

a) Execute the AppImage directly

./CARTA.AppImage

b) (Highly recommended) Create an alias in your shell script file. For example, if you are using bash andthe AppImage happens to be in your Downloads folder, open ~/.bashrc file in a text editor and add a line

alias carta='~/Downloads/CARTA.AppImage'

Then, after entering source ~/.bashrc in the terminal, you will be able to start carta by simply typing “carta”.


If you use csh or tcsh, the syntax differs only in that there is no equals sign, therefore it would be

alias carta '~/Downloads/CARTA.AppImage'

and

source ~/.cshrccarta

or

10 Chapter 2. Installation and configuration

https://github.com/CARTAvis/carta-releases/releases/download/v1.3.1/CARTA-v1.3.1-ubuntu.tgz


source ~/.tcshrccarta

Note: For this v1.3 release we are providing a combined desktop and remote server capability.

Invoke remote mode with the “–remote” flag

./CARTA.AppImage --remote

or, if an alias is created,

carta --remote

2.4 CARTA-desktop: Redhat 7


1. Download the tgz file

2. Unzip the tgz file

tar -xvf CARTA-v1.3-RedHat7.tgz

3. To run CARTA either

a) Execute the AppImage directly

./CARTA.AppImage

b) (Highly recommended) Set up an alias in your shell script file. For example, if your are using bashand the AppImage happens to be in your Downloads folder, open your ~/.bashrc file in a text editorand add a line

alias carta='~/Downloads/CARTA.AppImage'

Then, after entering source ~/.bashrc in the terminal, you will be able to start carta by simply typing“carta”.



alias carta '~/Downloads/CARTA.AppImage'

and


or


2.4. CARTA-desktop: Redhat 7 11

https://github.com/CARTAvis/carta-releases/releases/download/v1.3.1/CARTA-v1.3.1-RedHat7.tgz


Note: On RedHat7 machines, an updated ‘nss’ package may need to be installed.

sudo yum install nss

Note: On RedHat7 machines after starting the AppImage, you may see a warning about ‘Fontconfig’. It does notaffect usage of CARTA, but the warning can be removed by installing the fontconfig package.

sudo yum install fontconfig

Note: For this v1.3 release we are providing a combined desktop and remote server capability.

Invoke remote mode with the “–remote” flag e.g.

./CARTA.AppImage --remote

or

carta --remote

If using remote mode on RedHat7 with Firefox browser, the Firefox version needs to be newer than ESR 52.7.2 andhave “wasm” streaming enabled (See Troubleshooting for more information).

2.5 CARTA-desktop: Redhat 6

Neither AppImage nor Electron runs on RedHat 6, therefore we supply a “standalone” remote server package. It isintended for RedHat 6 use only, however it can also run on both RedHat 7 and Ubuntu 16.04 LTS/18.04 LTS.


1. Download the tar.gz file

2. Extract the archive

tar -xvf CARTA-v1.3.1-remote.tgz

3. Execute the carta script within the “CARTA-v1.3.1-remote” folder

./carta

4. Follow the onscreen instructions to copy and paste the unique URL into your web browser.

5. Usage instructions are slightly different from the Desktop versions so please check the help command with“./carta –help”. For example, you can not open images directly (can not “./carta image.fits”)

6. You could make an alias in your ~/.bashrc file similar to this

alias carta='~/CARTA-v1.3.1-remote/carta'



https://github.com/CARTAvis/carta-releases/releases/download/v1.3.1/CARTA-v1.3.1-remote.tgz


alias carta '~/Downloads/CARTA-v1.3.1-remote/carta'

and


or


2.6 Command line startup

CARTA can be started through the command line. To enable this feature, an alias of the CARTA executable needs tobe created first.

Once it is set, simply typing “carta” then hitting the “return” key will launch CARTA.

carta # file browser will show images in the current working directory (→˓$PWD)

The CARTA executable alias accepts keyword arguments or flags to configure how the CARTA backend is initialized.Common use cases are summarized below.

• open an image via the command line

carta M51.fits # to open an image in FITS formatcarta M51.image # to open an image in CASA formatcarta M51.hdf5 # to open an image in HDF5-IDIA formatcarta M51.im # to open an image in MIRIAD format

• launch CARTA and have the file browser to show images at a custom directory

carta /my/image/directory

If CARTA is installed on a remote server, and users access the server via the ssh protocol, CARTA backend can beinitialized via the following options.

• initialize a remote CARTA backend service with both frontend and backend ports selected automatically:

carta --remote # CARTA URL will be shown in the prompt.# Copy-and-paste the URL to your local browser (Chrome,

→˓Firefox, or Safari)

=========== what you may see after hitting return key ===========Starting CARTA in remote mode

To access CARTA, please enter either of the following URLs in your local web→˓browser:

www.carta.edu:2000/?socketUrl=ws://www.carta.edu:3000

OR

(continues on next page)

2.6. Command line startup 13


(continued from previous page)

192.168.1.312:2000/?socketUrl=ws://192.168.1.312:3000

Press ctrl+c to exit

Tip: When using remote mode, an image may be opened directly using a modified URL. For example, if wewanted to open a remote image file “/home/acdc/CARTA/Images/jet.fits”, we would append

&folder=/home/acdc/CARTA/Images&file=jet.fits

to the end of the URL (e.g., http://www.carta.edu:2000/?socketUrl=ws://www.carta.edu:3000). In this exampleour full URL is

http://www.carta.edu:2000/?socketUrl=ws://www.carta.edu:3000&folder=/home/acdc/→˓CARTA/Images&file=jet.fits

Please note that it is necessary to give full path. Tilde (~) is not allowed.

• initialize a remote CARTA backend service with customized frontend (e.g., 5678) and backend (e.g., 1234)ports:

carta --remote --port=1234 --fport=5678

=========== what you may see after hitting return key ===========Starting CARTA in remote mode

To access CARTA, please enter either of the following URLs in your local web→˓browser:

www.carta.edu:5678/?socketUrl=ws://www.carta.edu:1234

OR

192.168.1.312:5678/?socketUrl=ws://192.168.1.312:1234

Press ctrl+c to exit

For CARTA-server administration, the following advanced keyword arguments may be adopted.

• to set a limit of the file list scope:

carta --remote --root=/lustre/users/bob # user cannot navigate up to /lustre/→˓users

# --root defaults to "/"

• to set a number of threads for the CARTA backend service:

carta --remote --threads=24 # set 24 threads for the CARTA backend service# --threads defaults to number of cores on your

→˓system

An online user manual regarding all the above mentioned keyword arguments is also available.


http://www.carta.edu:2000/?socketUrl=ws://www.carta.edu:3000


carta --help # show all available keyword arguments with explanations.

usage: carta [] CARTA file browser will default to the current path.[<path>] CARTA file browser will default to the specified

path <path> e.g. carta ~/CARTA/Images

[<image>] CARTA will directly open the image named <image>e.g. carta aJ.fits or carta ~/CARTA/Images/aJ.fits

[--folder=<path>] Optional: An alternative way to define thedefault CARTA file browser path.Note: Not for directly opening an image.

[--help] View this help output

Remote mode flags[--remote] start CARTA in 'remote' mode. For accessing CARTA's

frontend through your webrowser rather than the→˓standard

Electron interface. A free websocket port and a→˓frontend

port will be chosen automatically.

[--port=<number>] Optional: Manually choose a websocket port for thebackend. CARTA will check if the port is availableand issue a warning if not. A typical value isbetween 1025-65535.

[--fport=<number>] Optional: Manually choose a frontend port for theCARTA web interface. CARTA will check if the portis available and issue a warning if not. A typicalvalue is between 1025-65535.

Advanced usage flags[--root=<path>] Define the lowest path the file browser can

navigate to. e.g. carta --root /home/bob means thethe file browser can not access anything in /homeNote: --root can not be set inside --folder.

[--threads=<number>] Set the number of threads. It controls how manytasks CARTA handles simultaneosuly. The defaultvalue is set as 4

[--omp_threads=<number>] Set the number of OpenMP threads. It controlshow trivially parallelisable tasks are splitby CARTA. The default value is theautomatically detected number of cores onyour system; usually 4 or 8 on a typcialdesktop or laptop.

2.7 Troubleshooting

In this section, we provide common issues we have experienced so far and provide solutions. If none of the solutionswork, please do contact CARTA Helpdesk for help.

• I see a blank image. . .

2.7. Troubleshooting 15



If you are using vnc:

Tip: The following is a tip for VNC users.

If your VNC connection passes through an intermediate or ‘gate’ machine, e.g.

<local machine> - <gate machine> - <remote machine>,

you may need to do an additional port mapping step.

Assuming you have successfully connected to <remote machine> and have started the CARTA remote serverthere, you will see the CARTA URL with two unique port numbers e.g.

<remote machine>:<1st port number>/?socketUrl=ws://<remote machine>:<2nd port→˓number>

On your local machine, open a new terminal and enter the following command:

ssh -L 1234:<remote machine>:<1st port number> -L 5678:<remote machine>:<2nd port→˓number> <username>@<gate machine>

You can now enter

<local machine>:1234/?socketUrl=ws://<local machine>:5678

in your local machine’s web browser to connect to CARTA remote server running on the remote machine (1234and 5678 are given as an example. You may choose different port numbers if you wish).

<remote machine> can either be the machine’s hostname or IP address.

Tip: If you are running the RedHat7 AppImage version on a VNC server but loaded images appear blank,please use the following prefix when starting the AppImage:

LIBGL_ALWAYS_INDIRECT=1 ./CARTA.AppImage

Loaded images should now render correctly.

• After copy-and-paste a CARTA URL, I see the CARTA GUI is not initialized. . .

Check your browser version. It needs to support “wasm” streaming and be enabled. More information aboutbrowser support of WebAssembly can be found at https://caniuse.com/#search=WebAssembly

CARTA utilises WebAssembly and that was introduced in version 52 of Firefox. Some RedHat6 and RedHat7distributions may have versions of Firefox earlier than version 52. If that is the case, we highly recommend thatyou update to a more recent Firefox version with “sudo yum update firefox”.

Other RedHat7 distributions may have Firefox 52 ESR which although having WebAssembly support, it isdeactivated by default. We still recommend updating to a newer version of Firefox, but if you can not, you cantry activating WebAssembly as follows:

1) Open a new tab and enter “about:config” in the URL bar.

2) A warning message will appear. Click the button to continue.

3) In the search box enter “wasm” and the list will filter down to a few results.

4) Double click each line related to “javascript.options.wasm” so that the “Value” column shows them as“true”.


https://caniuse.com/#search=WebAssembly

about:config


5) Then simply close the “about:config” tab and the CARTA frontend should now load properly.

As for the Chrome browser, Webassembly support was introduced in Chrome version 51, but versions 51 to 56have it deactivated by default. To activate WebAssembly in Chrome 51 to 56 enter “chrome://flags” in the URLbar, type WebAssembly in the search box that appears, and change each WebAssembly option to “Enabled”. Ifyou have Chrome version 57 or newer, WebAssembly should be activated by default.

• CARTA does not launch. . .

Check if there is existing “carta_backend” process running. The port number may conflict.

• The RedHat7 AppImage does not open and it prints a message suggesting to extract the AppImage using the“–appimage-extract” flag.

This error is due to lack of FUSE (File System in Userspace) support. We suspect that FUSE support in RedHat7systems may be disabled in some institute environments for security reasons. If that is the case, we recommendusing the ‘remote’ version of CARTA instead.

• “backspace” does not delete a region. . .

If using CARTA remote mode in Firefox on MacOS, you may find the “backspace” key navigates back a pageinstead of removing a region. This behaviour can be prevented by modifying your Firefox web browser settings:

1. Enter about:config in the address bar.

2. Click “I accept the risk!”

3. A search bar appears at the top of a long list of preferences. Search for “browser.backspace_action”

4. It will likely have a value of 0. Double click it, and then modify it to a value of “2”.

5. Close the about:config tab and now backspace will no longer navigate back a page.

2.7. Troubleshooting 17

about:config

about:config

about:config

CHAPTER 3

Graphical user interface

The graphical user interface (GUI) of CARTA is designed to be flexible and user friendly to support most of use cases,such as continuum image analysis, or spectral line cube analysis, etc. In this section, we introduce the GUI and provideexamples to guide users to get familiar with configuring layouts via mouse interactions. Examples on how to interactwith regions and charts are provided as well.

3.1 Components

The GUI of CARTA is classified into different components:

• main window

• menu bar

• widget bar

• dialogue bar

• tool bar

• panel (docked widget)

• floating widget

• tab

• dialogue

• status icon

The main window consists of a set of panels and each panel may contain multiple docked widgets as tabs. For example,in the above figure there are five panels in the main window and there are two docked widgets as tabs in the bottom-left panel. A tab or a docked widget may be detached to become a floating widget. The menu bar provides controloptions, such as image input/output, launching widgets, getting helps, etc. The widget bar provides widgets to viewor to analyze images. The dialogue bar provides dialogues for configurations. The icon at the top-right corner of themain window is an indicator of server (backend) status. A dialogue provides options to configure compoments, such

19


as image layout, or region properties, etc. A tool bar provides tools for a widget, such as zoom buttons for the imageviewer widget or the export options for the spectral profile widget, etc.

3.2 Quickstart guide

In this section, basic instructions on how to interact with CARTA through the graphical user interface (GUI) areintroduced. A summary of the full set of controls and shortcuts can be found via the “Help” -> “Controls and Shortcuts”menu or via “shift”+”?” keys.

3.2.1 Image viewing interactions

To zoom an image

• use mouse wheel to scroll

• use buttons at the bottom-left corner of image viewer

To pan an image

• use mouse to drag on image (default)

• hold “command” (mac) / “ctrl” (linux) key then mouse click

To pan inside a region

• hold “command” (mac) / “ctrl” (linux) key then mouse click

• mouse middle click

3.2.2 Region of interest interactions

To enable region creation mode

• press “C” key

To create symmetric regions (circle or square)

• hold “shift” key then mouse drag

To create / modify a region (rectangle or ellipse) with the alternative mode (center-to-corner or corner-to-corner).

• hold “command” (mac) / “ctrl” (linux) key then mouse drag

To configure a region

• double mouse click on the region list

• double mouse click inside a region in image viewer

To lock/unlock a region

• press “L” key

• press “shift” + “L” key to unlock all locked regions

• click the lock icon in the region list widget

• click the lock icon in the region configuration dialogue.

To delete a region

• press “delete” key

20 Chapter 3. Graphical user interface


• press “backspace” key

3.2.3 Cursor update

To freeze/unfreeze cursor position update in the image viewer

• press “F” key

3.2.4 Chart interactions

Focused zoom

• use mouse wheel to scroll

Horizontal zoom

• hold-and-drag in horizontal direction

Vertical zoom

• hold-and-drag in vertical direction

Box zoom

• hold-and-drag in diagonal direction

Reset zoom

• double mouse click

Horizontal pan

• hold “shift” key then mouse drag horizontally

3.3 Getting help

This online user manual can be accessed via “Help” -> “Online manual”. A new browser window will be launchedand show the CARTA user manual. In addition, in-app help (no internet is required) can be accessed via the “?” iconat the top-right corner of a panel. The help content will be displayed in a drawer.

3.4 Configuring the layout

The layout configuration can be changed by mouse operations, such as click or drag-and-drop. The drag-and-dropaction is guided on the GUI with a semi-transparent guider. Various operations are demonstrated below.

3.4.1 Resizing a panel

As shown in the example below, a panel can be resized by dragging its borders. After a panel is resized, nearby panelsare resized automatically to fit the new layout. Note that the appearance of the UI elements is adaptive to the size ofthe panel, as seen in the render configuration widget or the animator widget in the example.

3.3. Getting help 21


3.4.2 Relocating a tab as a new panel

A tab can be relocated by dragging its title to a desired new panel. The target location is visualized with a semi-transparent box, as shown in the example below.

3.4.3 Relocating a tab to another panel

A tab can be moved to other existing panel by dragging its title to the upper boarder of the target panel, as shown inthe example below.

3.4.4 Maximizing and restoring a panel

By clicking the maximize icon at the top-right corner of a panel, the panel (including all tabs) will be maximized tothe main window. By clicking the restore icon, the panel will be restored to its original location.

3.4.5 Detaching and attaching a tab

By clicking the detach (unpin) icon at the top-right corner of a panel, the activated tab will be detached to become afloating widget. By dragging the attach (pin) icon, a floating widget will be attached to an existing panel or as a newpanel.

3.4.6 Creating a widget as a floating widget or as a tab

A widget is activated as a floating widget by clicking the button in the widget bar. Alternatively, a widget can beactivated as a tab by dragging the button in the widget bar directly to a desired location.

3.4.7 Light and dark theme

CARTA supports a light (default) and dark theme. The theme can be changed using the View -> Interface menu item,or the shortcut shift + D.

3.4.8 Custom layout, save, and restore

CARTA has a set of preset layouts sutiable for different kinds of image analysis. These layouts are accessible via themenu Layout -> Layouts -> Existing layouts -> Presets.

Users may further customize a preset layout or make a new layout from scratch for different purposes and save it forthe future. To save a custom layout, use the menu Layout -> Layouts -> Save layout. A name is required when savinga layout (e.g., “my layout 01” in the above example).

A saved layout can be restored via the menu Layout -> Layouts -> Existing layouts. The currently activated layout ishighlighted in blue (“Default” in the above example). Saved layouts can be removed via the menu Layout -> Layouts-> Delete layout.

By deafult, CARTA will load the “Default” preset layout when initialized. Which layout, including user customizedlayouts, should be loaded can be further defined via the preferences dialogue File -> Preferences. The initial layoutcan be set via Global -> Initial layout.



3.5 User preferences

CARTA provides a number of preferences for users to customize the GUI, including layouts. The preferences arepersistent so that next time when users launch CARTA, all the preferences and a layout are restored. The preferencesdialogue is accessible via the menu File -> Preferences. Preferences are effective after CARTA reloads, except fewthat are effective immediately. Below we summarize the options of all preferences.

• Global

– Theme: to adopt light or dark theme of the GUI (default: light) [effective immediately]

– Auto-launch file browser: to launch the file browser or not when CARTA is initialized (default: yes)

– Initial layout: the layout to adopt when CARTA is initialized (default: “Default”)

– Initial cursor position: to fix the cursor position on the image or not when CARTA is initialized. If it isfixed, a cross will be shown at the image center. Use “F” key to switch to the tracking mode (default:Tracking)

– Initial zoom level: to select the initial zoom level of the image to be filling up the field of view or to bedisplayed as one image pixel to one screen pixel ratio (default: “Zoom to fit”)

– Zoom to: zoom with respect to cursor position or image viewer center

– Enable drag-to-pan: pan image by mouse drag or mouse click

– WCS matching on append: trigger WCS matching automatically for newly appended images

– Spectral matching: spectral convention adopted for spectral matching

• Render configuration

– Scaling: the scaling function of the color map (default: linear)

– Color map: the default color for the raster image (default: inferno)

– Percentile ranks: the default clip level for the color map (default: 99.9%)

– NaN color: color for rendering NaN pixels

• Contour configuration

– Generator type: tools for generating a set of contour levels to be calculated and rendered

– Smoothing mode: image smoothing mode before calculating contour vertices

– Default smoothing factor: kernel size in number of pixels for image smoothing

– Default contour levels: number of contour levels to be generated by the level generator

– Thickness: line thickness of contour rendering

– Default color mode: render contours with a constant color or a color map

– Default color map: color map for contour rendering

– Default color: constant color for contour rendering

• Overlay configuration

– AST color: the color for the WCS overlay, including border, grid line, ticks, labels, and title (default: blue)

– AST grid visible: to show grid line or not as default (default: yes)

– AST label visible: to show coordinate labels or not as default (default: yes)

3.5. User preferences 23


– WCS format: the format of the displayed world coordinate. The default is “automatic” which means forgalactic or ecliptic system, the world coordinate is displayed in decimal degrees, and for FK4, FK5, orICRS, the world coordinate is displayed in sexigesimal format. (default: automatic) [effective for newimages]

– Beam visible: show a spatial resolution element

– Beam color: color for rendering a spatial resolution element

– Beam type: styling for rendering a spatial resolution element

– Beam width: line width for rendering a spatial resolution element

• Region

– Color: the default color of a region (default: cyan) [effective for new regions]

– Line width (px): the default line width of a region (default: 2) [effective for new regions]

– Dash length (px): the default dash length of the line composing a region. The default is to show a regionin solid line (default: 0) [effective for new regions]

– Region type: the default selected region in the tool bar of the image viewer (default: rectangle)

– Creation mode: the method of how a rectange or an ellipse is created by mouse dragging. Two methodsare supplied: center-to-corner and corner-to-corner (default: center-to-corner) [effective for new regions]

• Performance

– Low bandwidth mode: reduce required image resolution by a factor of two and reduce the cursor respon-siveness to 400 ms

– Compression quality (image): a parameter (1~32) to control the image quality with lossy compression.The higher the number is, the better quality the images are. Choose with caution. (default: 11) [effectiveimmediately]

– Compression quality (animation): a parameter (1~32) to control the animation quality with lossy com-pression. The higher the number is, the better quality the images are. Choose with caution. (default: 9)[effective immediately]

– GPU tile cache size (number of tiles): the cache size of GPU for tiles (default: 512)

– System tile cache size (number of tiles): the cache size of system memory for tiles (default: 4096)

– Contour rounding factor: number of contour vertices per pixel

– Contour compression level: compression quality of contour image data

– Contour chunk size: chunk size of contour data streaming

– Contour control map resolution: control map resolution for reprojecting contour vertices to other coordi-nate system

– Stream image tiles while zooming: streaming image tiles for all sampled zoom levels

– Stop animation playback in: a timer to automatically stop animation playback for server resource manage-ment

• Log events

This is for debugging purpose. Normal users can skip this part. The client side and the server side of CARTAcommunicate through “protocal buffer” messages. For debugging purpose, advanced users can identify a set ofmessages in the list and launch browser’s Javascript console to see those messages.



3.6 Mouse interactions with images

3.6.1 Zooming

The image can be zoomed in by scrolling up and zoomed out by scrolling down.

3.6.2 Panning

The image can be panned by mouse drag-and-drop on the image.

If it is intended to pan inside a region, please hold command (mac) or ctrl (linux) key and click inside a region, orsimply use middle click. Single click on a region will change the region state to “selected”. With the same operation,users can center an image pixel (regardless it is inside a region or not) in the image viewer.

3.7 Mouse interactions with region of interest

3.7.1 Region creation

A region can be created by firstly entering the region creation mode then drawing on the image viewer. To enter theregion creation mode, click the region button at the bottom-right corner of the image viewer or press “C” key. Double-clicking the region icon brings up all available region types (rectangle, ellipse, polygon, and point, as of v1.3). Tocreate a point region, a single click will do. For rectangle or ellipse, it can be created in the “center-to-corner” mode orthe “corner-to-corner” mode, depending on the preference setting in the preference dialogue (File -> Preferences ->Default region settings). To temporarily switch to the other mode than the default, hold “command” (mac) or “ctrl”(linux) key then drag. “circle” and “square” regions are the special cases of ellipse and rectangle regions, respectively.These symmetric regions can be created by holding shift key then dragging.

To create a polygon region, start with a click followed by a series of clicks to define anchors of a desired polygonalshape and finish with a double click. CARTA detects “complex” polygon (polygon with intersections) and shows it inpink color. Spectral profiles, statistics, or histogram of a complex polygon can still be requested but please note thatthe results may be beyond users’ expectations since the actual pixel coverage depends on how a complex polygon iscreated.

3.7.2 Region selection and modification

Click on a region will change the region state to “selected” and the selected region will be highlighted in the regionlist widget. Alternatively, a region can be selected by clicking the region list. CARTA provides the flexibility to select“region in region” as demostrated in the following video. The layer order of regions is adjusted automatically basedon the region size. To de-select all regions, press “esc” key.

Double-click on a region or a region in the region list brings up the region property dialogue. The dialogue allowsusers to modify region’s name, location, shapes, and region cosmetics. Pressing “delete” or “backspace” key willremove the selected region.

Tip: “backspace” does not delete a region. . .

If using CARTA remote mode in Firefox on MacOS, you may find the “backspace” key navigates back a page insteadof removing a region. This behaviour can be prevented by modifying your Firefox web browser settings:



3.6. Mouse interactions with images 25

about:config





For a polygon region, new anchors can be added by clicking on the line segment. An anchor can be delected by doubleclicking on the anchor.

3.8 Mouse interactions with charts

3.8.1 Zooming

A chart (profiles and histograms) can be zoomed by wheel scrolling.

Alternatively, horizontal zoom, vertical zoom, and box zoom are supported.

3.8.2 Panning

Dragging while holding the shift key pans the chart.

3.8.3 Resetting range

Double-clicking on the chart resets the plotting range.

3.9 Controls and shortcuts

CARTA supports keyboard shortcuts to enable certain controls without using a mouse. A summary is accessible viathe menu Help -> Controls and Shortcuts, or the shortcut shift + ?. The shortcuts are slightly different dependingon the operating system in use. The shortcuts for each operating system are summarized in the following table.

Control macOS LinuxHelpControls and shortcuts shift + ? shift + ?NavigationPan image click clickPan image (inside region) cmd + click / middle-click ctrl + click / middle-clickZoom image mouse wheel mouse wheelRegionsRegion properties double-click double-clickDelete selected region del / backspace del / backspaceToggle region creation mode C CDeselect region esc escSwitch region creation mode cmd + drag ctrl + dragSymmetric region creation shift + drag shift + dragToggle current region lock L LUnlock all regions shift + L shift + LAppearance

Continued on next page


about:config


Table 1 – continued from previous pageControl macOS LinuxToggle light/dark theme shift + D shift + DCursorFreeze/unfreeze cursor F FFile controlsOpen image cmd + O ctrl + OAppend image cmd + L ctrl + LExport image cmd + E ctrl + EFrame controlsNext frame cmd + ] ctrl + ]Previous frame cmd + [ ctrl + [Next channel cmd + up ctrl + upPrevious channel cmd + down ctrl + downNext Stokes cmd + shift + up ctrl + shift + upPrevious Stokes cmd + shift + down ctrl + shift + down

3.9. Controls and shortcuts 27

CHAPTER 4

Image cube visualization

With version 1.3, CARTA provides the following widgets and dialogues for image cube visualization:

• Widget

– image viewer: to view raster images and contour images

– render configuration: to configure how a raster image is rendered

– animator: to navigate through different images, different channels, or different Stokes

– layer list: to configure image matching in world coordinates

• Dialogue

– file browser: to view image headers and to load or to append an image

– contour configuration: to configure how a contour image is rendered

– file information: to view image headers

– overlay settings: to configure the appearance of an image in the image viewer

4.1 Server-side status and session resume

As CARTA is fundamentally a client-server application, it would be good to know the status of the server side at theclient side. This is also useful for the desktop version to know if the application runs normally or not. The serverstatus is displayed as a circular icon at the top-right corner of the main window. The connection latency can be seenby hovering over the icon. There are three kinds of status:

• Green: this means that the server side is connected successfully.

• Orange: this means that the initial connection to the server side was broken (e.g., unstable internet) but has beenreconnected. Users will asked to resume the previous session or not.

• Red: this means that the server side is not accessible. CARTA is not functional in this case.

29


Note: If CARTA behaves abnormally or stops responding, please check the server-side status icon and connectionlatency. If it becomes red, the connection between the client side and the server side is interrupted. At this point,CARTA is not funtional. When the connection is re-established automatically, the status icon becomes orange anda prompt will be shown to ask users wheater or not to resume the previous CARTA session. By clicking the OKbutton, CARTA will try to resume the previous session if possible. If users choose not to resume the previous session,please reload CARTA to establish a new session. Interacting with CARTA when the status icon is orange may lead toabnormal behaviors.

4.2 File browser

File browser, accessible via the menu File -> Open image or the menu File -> Append image, provides informationof images supported by CARTA. Currently CARTA supports images in:

• CASA format

• HDF5 format (IDIA schema)

• FITS format

• MIRIAD format

Only the images matched these formats will be shown in the file list with image type and file size. When an image isselected, a brief summary of image properties is provided on the right side of the dialogue. Full header is also availablein the second tab. To view an image, click the Load button at the bottom-right corner. To view a new image and closeall the loaded images, use File -> Open image -> Load button. To view multiple images, use File -> Append image-> Append button.

File browser remembers the last path where an image was opened within one CARTA session and the path is displayed(breadcrumbs) at the top of the dialogue. Therefore, when the file browser is re-opened to load other images, a file listwill be displayed at the last path where the previous image was loaded. Users can use the breadcrumbs to navigate toone of the parent directories or click the home button to navigate to the base (i.e., initial) directory directly. To get anupdated file list from the server side, users can click the reload button.

For the CARTA-server application, the server administrator can limit the global directory access through the “root”keyword argument when launching the CARTA backend service.

exec carta_backend port=6002 base=/scratch/images/Orion root=/scratch/images

In the above example, users will see a list of images at the “base” directory “/scratch/images/Orion” when ac-cessing the file browser dialogue for the first time in a new session. Users can navigate to any other fold-ers inside “/scratch/images/Orion”. By clicking the home button, users will navigate to the “base” directory“/scratch/images/Orion” directly. Users can also navigate one level up to “/scratch/images”, but not beyond that(neither “/scratch” nor “/”) as limited by the “root” keyword.

Note: An image might be closed via File -> Close image. The image currently displayed in the image viewer will beclosed. If the image being closed is a WCS reference image, any other matched images to this reference image will beunmatched, thus they behave like individual images.

Note: Currently CARTA does not support the following types of images:

• integer image

• complex image

30 Chapter 4. Image cube visualization


• concatenated image

• boolean image

• componentlist image

• image with uv coordinates

• position-velocity image

• LEL image

Tip: When using remote mode, an image may be opened directly using a modified URL. For example, if we wantedto open a remote image file “/home/acdc/CARTA/Images/jet.fits”, we would append

&folder=/home/acdc/CARTA/Images&file=jet.fits

to the end of the URL (e.g., http://www.carta.edu:2000/?socketUrl=ws://www.carta.edu:3000). In this example ourfull URL is

http://www.carta.edu:2000/?socketUrl=ws://www.carta.edu:3000&folder=/home/acdc/CARTA/→˓Images&file=jet.fits

Please note that it is necessary to give full path. Tilde (~) is not allowed.

4.2.1 HDF5 (IDIA schema) image support

Except the CASA image format, the FITS format, and the MIRIAD format, CARTA also support images in the HDF5format under the IDIA schema. The IDIA schema is designed to ensure that efficient image visualization is retainedeven with extraordinary large image cubes (hundreds GB to a few TB). The HDF5 image file contains extra data toskip or to speed up expensive computations, such as per-cube histogram or spectral profile, etc. A brief outline of thecontent of an HDF5 image is provided below:

• XYZW dataset (spatial-spatial-spectral-Stokes): similar to the FITS format

• ZYXW dataset: rotated dataset

• per-channel statistics: basic statistics of the XY plane

• per-cube statistics: basic statistics of the XYZ cube

• per-channel histogram: histogram of the pixel values of the XY plane

• per-cube histogram: histogram of the XYZ cube

Additional tiled image data, which will speed up the process of loading very large images significantly, will be addedto the HDF5 image file in v1.4.

Note: Currently per-plane beam is not handled properly when converting a FITS image to the HDF5 format.

4.3 Image viewer

Starting from v1.3, CARTA can display images in differnt ways, such as:

1. a single raster image

4.3. Image viewer 31

http://www.carta.edu:2000/?socketUrl=ws://www.carta.edu:3000


2. a single raster image plus its own contours

3. a single raster image plus a set of contour images with matched world coordinates from other image files

4. a set of contour images without a background raster image

When an image is loaded in CARTA, it is shown as a raster image by default, such as the first example in the abovefigure. Users then could generate contour images (see Contour rendering) and enable WCS matching between differentimages (see Match images in world coordinates), such as the other three examples above.

Warning: If you are running a VNC session from a headless server, CARTA may fail to render images properly(they may appear as a solid color). This is due to the fact that CARTA renders images using WebGL which usesGPU to accelerate rendering process. Most headless servers have neither discrete nor dedicated GPUs. In suchcases, it is highly recommended to use the “remote” mode of CARTA (see Command line startup for instructions).

In addition to displaying images, the image viewer displays cursor information at the top and provides a set of toolbuttons at the bottom-right corner when hovering on the image.

The tool buttons allow users to:

• create region of interests

• perform zoom or pan actions

• trigger matching images in world coordinates

• change reference coordinate grid lines and labels

• export image as a png file

The aspect ratio of the image view is determined by the panel geometry. When the image viewer panel is resized, a tipwith a ratio in screen pixel will be displayed (c.f., Resizing a panel ).

4.4 Tiled rendering

CARTA utilizes an efficient approach, “tiled rendering”, to display a raster image. What users see in the image vieweris an ensemble of tiles (default 256 pixel by 256 pixel) processed in parallel. As an example shown in the figure below,if we have an image with 2048 pixels by 2048 pixels, tiles will be constructed in four layers with differnt downsamplefactors. The zero-th layer contains only one tile with a size of 256 pixels by 256 pixels. A downsample factor of 8 isapplied to the original image to create this tile. The first layer contains four tiles with each a size of 256 pixels by 256pixels. The downsample factor of 4 is applied to the original image to create these four tiles. This process continuesuntil no downsampling is required. In this case, the tiles of the third layer are not downsampled. As users changethe field of view, or the size of the image viewer, tile data of the right layer will be used. For example, if a user isinterested in the field of the blue box and the image viewer has a screen size of 512 pixels by 384 pixels, tiles of thelayer 2 will be used for rendering. In this case, nine tiles will be used. If the user pans a little bit around the blue box,no new tile data are required. If the user pans the view to the green box with the same viewer size, only the additionaltwo tiles of layer 2 are required and four tiles will be re-used for rendering. With this tiled rendering approach, tileswill be re-used for different zoom levels and different field of views to minimize the amount of data transfer whilekeeping the image sharp on screen. Effectively, users will see that the image becomes sharper and sharper at higherand higher zoom levels.

Below is a demonstration of tiled rendering in action. Note that the video clip is made under a special internet conditionin order for users to see the process clearly. Normally images are rendered much faster.

The performace of tiled rendering can be customized with the preferences dialogue, File -> Preferences -> Per-formance. The default values are chosen to assure raster images are displayed efficiently with sufficient accuracy.Advanced users may refine the setup if necessary. For example, when using the server version under poor internet



condition, compression quality might be lowered down a bit to make the tile data smaller. Note that a smaller com-pression quality might introduce noticible artifacts on the raster image. Please adjust with caution. Alternatively, usersmay enable the low bandwidth mode, which will reduce required image resolutions by a factor of 2 (so that image willlook a bit blurry) and cursor responsiveness from 200 ms to 400 ms (HDF5 images: from 100 ms to 400 ms). Undergood internet conditions, users may enable streaming image tiles while zooming to see progressive updates of imageresolutions at different zoom levels.

Warning: To make remote visualization of large images possible and efficient, CARTA adopts the above men-tioned tiled rendering approach together with an efficient image compression algorithm. At rare circumstance,artifacts may be seen on the images. A known issue is viewing an image with all pixels as zeros but one with avery high value. At low or default zoom level, some artifacts will be observed around that pixel. At higher zoomlevels, the artifacts may disappear. CARTA has been tuned to localize the artifacts within few screen pixels inorder to minimize the impact of scientific analysis on such special cases. The compression quality is adjustablevia the preferences dialogue, File -> Preferences -> Performance. Advanced users may need to chose a highercompression quality for those special cases with caution. Should this become a problem in any kinds of analysisof yours, please contact carta_helpdesk for help.

Note: CARTA image loading performance

The per-channel rendering approach helps to improve the performance of loading an image significantly. Traditionallywhen an image is loaded, the minimum and maximum of the entire image (cube) are computed first before imagerendering. This becomes a serious performance issue if the image (cube) size is extraordinary large (> several GB).In addition, applying the global minimum and maximum to render a raster image usually (if not often) results in apoorly rendered image if the dynamical range is high. Then users need to re-render the image repeatedly with refinedboundary values. Re-rendering such a large image repeatedly further deduces user experiences.

CARTA hopes to improve the image viewing experience by adopting GPU accelerated rendering with web browsertechnology. In addition, CARTA only renders an image with just enough image resolution (tiles and down-sampling).This combination results in a scalable and high-performance remote image viewer. The total file size is no longer abottleneck. The determinative factors are: 1) image size in x and y dimensions, 2) internet bandwidth, and 3) storageI/O, instead. For a laptop with 8 GB of RAM, the largest image it can load without swapping is about 40000 pixels by40000 pixels (assuming most of the RAM are free before loading image).

The approximated RAM usage of loading images with various spatial sizes is summarized below.

Image size (x, y) [pixel] RAM usage512 1 MB1024 4 MB2048 16 MB4096 64 MB8192 256 MB16384 1 GB32768 4 GB65536 16 GB

4.5 Render configuration of a raster image

The render configuration widget controls how a raster image is rendered in the image viewer. On the top, there is arow of buttons with different clip levels plus a custom button. Below there is a plot showing the per-channel histogram

4.5. Render configuration of a raster image 33



(in logarithmic scale) with a bin count equals to the geometric mean of the image size (x and y). The two vertical redbars indicate the two clip values of a colormap. The green dashed line marks the mean value and the green box marksthe range from mean - one standard deviation to mean + one standard deviation. Interaction with a chart, such as thehistogram, is demonstrated in the section Mouse interactions with charts. On the right, there is a column of options,such as histogram type, scaling function, color map, invert color map, clip values, and control parameter of a scalingfunction (if applicable). Extra options to configure the histogram plot are placed in the render configuration settingsdialogue enabled by the cog icon at the top-right corner of the render configuration widget. The histogram can beexported as a png image or a text file in tsv format.

By default, CARTA calculates per-channel histogram. When per-cube histogram is requested, a warning message anda progress dialogue will show up. Calculating a per-cube histogram can be time-consuming for large image cubes.Users may cancel the request at any time by pressing the cancel button in the progress dialogue. If the image is inthe HDF5 format (IDIA schema), the pre-calculated per-cube histogram will be loaded directly and displayed mostlyinstantly.

CARTA determines the boundary values of a colormap on per-channel basis by default. That is, a default “99.9%”clip level is applied to the per-channel histogram to look for the two clip values. Then apply the values in “linear” scaleto the default colormap “inferno” to render a raster image. This helps to inspect an image in detail without sufferingfrom improper image rendering in most of cases. Below is an example of this per-channel rendering approach.

However, when comparing images channel by channel, color scales need to be fixed. This can be easily achievedby dragging the two vertical red bars, or typing in the values. When this happens, the “custom” button is enabledautomatically and all frames will be rendered with the fixed boundary values. By clicking one of the clip buttons,CARTA switches back to the per-frame rendering mode if per-channel histogram is requested. Users may requestthe per-cube histogram to determine proper clip values. Below is an example of custom rendering with the per-cubehistogram.

CARTA provides a set of scaling functions, such as:

• linear: 𝑦 = 𝑥

• log: 𝑦 = log𝛼(𝛼𝑥+ 1)

• square root: 𝑦 =√𝑥

• squared: 𝑦 = 𝑥2

• gamma: 𝑦 = 𝑥𝛾

• power: 𝑦 = (𝛼𝑥− 1)/𝛼

A set of colormaps adopted from matplotlib is provided in CARTA.

The default scaling function, colormap, percentile rank, and a color for NaN pixels can be customized via the menuFile -> Preferences -> Render Configuration.

4.6 Contour rendering

In addition to raster rendering, CARTA supports contour rendering as well. A contour image layer can be created onthe same raster image or on a different raster image with world coordiantes properly matched. The contour generationprocess is achieved with the contour configuration dialogue which can be launched via the main tool bar.

Users may follow the following steps to generate a contour image:

1. Define contour levels. There are several ways to define a set of contour levels to be calculated at the server side:

a. by typing in individual level in the “Levels” field

b. by using the “Generator” to generate a series of levels


https://matplotlib.org/tutorials/colors/colormaps.html?highlight=colormap


c. by clicking directly on the histogram plot to create levels (right-click on an existing level to remove)

Note that the “Levels” field is editable even if a set of levels has been generated with the level generator.

2. (optional) Define a smooth scheme and a kernel size in the “Configuration” tab. The default is Gaussian smoothwith a kernel size of four pixels.

3. (optional) Define the appearance of contours to be rendered at the client side in the “Styling” tab. The appearanceof contours can be modified after a set of contours has been rendered without triggering new contour calculationsat the server side. This is the advantage of utilizing WebGL at the client side.

Once a set of levels has been defined, users can click the “Apply” button to visualize the contour image. Contourimage is rendered progressively.

In the above demostration, a contour image is generated on top of its raster image. If users would like to plot a contourimage on top of other raster image (e.g., velocity field as contour, integrated intensity image as raster), users need toenable WCS matching of the two raster images first (see Match images in world coordinates). Then users can generatethe contour image just like the above example. When the contour image is generated, use the layer list widget or theanimator widget to switch to the integrated intensity image. Users should see the velocity field image as contours ontop of the integrated intensity image as raster. In short, contour images are visible for raster images matched in worldcoordinates.

If there are multiple images loaded in append mode, users may use the “Data Source” dropdown to select an image asthe data source of contour calculations. If the state of the “lock” button is locked, image viewer will show the selectedimage as a raster image and the frame slider in the animator widget will be updated to the selected image too. Todisable this synchronization, click the “lock” button to set the state to unlock.

CARTA provides four different level geneators to assist users to construct a set of contour levels.

• “start-step-multiplier”

A set of “N” levels will be computed from “start” with a (variable) step. For example, if start = 1.0, step = 0.1, N= 5, and multiplier = 2, five levels will be generated as “1.0, 1.1, 1.3, 1.7, 2.5”. The function of the multiplier isto make the step increase per next new level. Default parameters derived from full image statistics (per-channel)are:

– start: mean + 5 * standard deviation

– step: 4 * standard deviation

– N: 5

– multiplier: 1

• “min-max-scaling”

A set of “N” levels will be calculated between “min” and “max” with a spacing according to the “scaling”function. For example, if min = 2, max = 10, N = 5, scaling = “linear”, five levels will be generated as “2, 4, 6,8, 10”. Default parameters derived from full image statistics (per-channel) are:

– min: lower bound of 99.9% clip

– max: upper bound of 99.9% clip

– N: 5

– scaling: “linear”

• “percentages-ref.value”

A set of “N” levels will be derived as the percentages (“Lower(%)” and “Upper(%)”) of the “reference” in linearspacing. For example, if reference = 1.0, N = 5, lower(%) = 20, upper(%) = 100, five levels will be generated as“0.2, 0.4, 0.6, 0.8, 1.0”.

– reference: upper 99.9% clip

4.6. Contour rendering 35


– N: 5

– lower(%): 20

– upper(%): 100

• “mean-sigma-list”

A set of “N” levels will be generated as “mean” plus multiples of “sigma” based on the “sigma list”. Forexample, if mean = 1, sigma = 0.1, and sigma list = [-5, 5, 10, 15, 20], five levels will be generated as “0.5, 1.5,2.0, 2.5, 3.0”. Default parameters derived from full image statistics (per-channel) are:

– mean: full image mean value

– sigma: full image standard deviation

– sigma list: [-5, 5, 9, 13, 17]

CARTA provides three different contour smoothing methods, including no smooth, Gaussian smooth, and blocksmooth, in the “Configuration” tab. The kernel for smoothing is in number of pixels. The default is to apply Gaussiansmooth with four pixels as the kernel size. Depending on science cases, users may choose different smooth methodsand differnt kernel sizes.

The appearance of contours can be customized in the “Styling” tab. As an example, users may use the options toplot contours like below. Iso-velocity contours are rendered in different colors to present Doppler shifts of the sourcekinematics.

4.7 Match images in world coordinates

When multiple images are loaded in the append mode, users may optionally trigger image matching based on theirworld coordinates. It is a common practice to compare images from different telescopes or even from the sametelescope with different spectral and spatial setups. Users can use the “Layer list widget” to trigger image matchingprocess,

or the tool button in the image viewer.

The layer list widget lists up all load images, including their:

• file name

• rendering type (“Type”): “R” means raster and “C” mean contour

• image matching state (“Matching”): “XY” means spatial domain and “Z” means spectral domain.

• channel index

• Stokes index

The first loaded image with valid spatial world coordinates serves as the spatial reference and is highlighted withan open black box (e.g., HD163296_CO_2_1.image.mom0). Similarly, the first loaded image with valid spectralcoordinates servers as the spectral reference and is highlighted with an open black box (e.g., HD163296_CO_2_1.fits).To match world coordinates of other loaded image, users can click “XY” to match in the spatial domain and click “Z”to match in the spectral domain.

Hint: Users may change spatial or spectral reference image by right-clicking a cell in the “Matching” column in thelayer list widget.

For raster images, matching in the spatial domain is achieved by applying translation, rotation, and scaling to imageswith respect to the reference image.



For contour images, matching in the spatial domain is achieved by reprojecting contour vertices to the raster image inthe view. Multiple contour images are displayed on top of a raster image if spatial matching is enabled.

For image cubes, matching in the spectral domain is achieved by nearest interpolation in radio velocity. When spectralmatching is enabled by clicking “Z”, the matched channel and Stokes indices are shown in the layer list widget.

Note: Projection effects of raster images

As raster images are matched spatially by applying translation, rotation, and scaling, projection effects between differ-ent images might be visible if images have wide field of view and/or images have very different projection schemes.In the following video, projection effects in raster images are demonstrated. However, projection effects of contourimages are properly handled in CARTA. Contours are reprojected with sufficient accuracy with respect to the rasterimage as seen by users in the image viewer.

Note: If spatial reference image or spectral reference image is closed via “File” -> “Close image”, all matchedimages will be unmatched and a new reference image will be automatically registered.

Warning: Animation playback does not work properly with spectrally matched cubes in v1.3. This will beimproved in v1.4.

Raster image or contour image may be hidden in the image viewer by clicking “R” or “C” in the layer list widget. Forexample, to create an image with contours only, users can click the “R” button to hide the raster image.

When multiple images are loaded in the append mode, their order determines the order in the frame slider of theanimator widget. With the layer list widget, this order can be changed by dragging an entry to a desired place.

4.8 Changing image view

CARTA provides different ways to change the image view. With a mouse, image zoom is achieved by scrollingup/down. Image pan is achieved by dragging or command+clicking (mac) or ctrl+clicking (linux). Alternatively,image can be changed to fit the image viewer, or to fit the screen resolution (i.e., screen resolution equals full imageresolution), by using the buttons at the bottom-right corner of the image viewer. Zoom in and zoom out buttons areprovided as well. To change to different frames, channels, or stokes, please refer to the section Animator.

When an image is zoomed in or out, the precision of the coordinate tick values is dynamically adjusted based on thezoom level.

4.9 Cursor information

When the cursor is on the image viewer, pixel information at the cursor position is shown at the top side of the image.The information includes:

• World coordinate of the current coordinate system.

• Image coordinate in pixel.

• Pixel value.

• Frequency, velocity, and reference frame (if applicable).

4.8. Changing image view 37


When the coordinate system is changed (e.g., ICRS to Galactic), the displayed world coordinate will be changedaccordingly. By default, they are displayed in decimal degrees for Galactic and Ecliptic systems, while for FK5, FK4,and ICRS systems, they are displayed in sexagesimal format. The precision of both formats is determined dynamicallybased on the image header and image zoom level.

The reference image coordinate (0,0) locates at the center of the bottom-left pixel of the image. Regardless thedisplayed image is down-sampled or not, the image coordinate always refers to full resolution image.

When cursor is moving, pixel value of the full resolution image is displayed. If image header provides sufficientinformation in the frequency/velocity domain, the frequency and velocity with the reference frame of the currentchannel will be shown.

To stop/resume cursor update, press “F” key. When the cursor stops updating, the cursor information bar, cursorspatial profiler, cursor spectral profiler will stop updating too.

4.10 Configuring an image plot

CARTA provides flexible options to configure the appearance of an image plot. The overlay settings are accessible via“View” -> “Overlay” -> “Customize”.

As an example, below is an image with default overlay settings.

And, this is a customized one. The coordinate system has been switched from FK5 to Galactic. Font type, size, andcolor are customized, as well as the axis border and grid lines.

The restoring beam is shown at the bottom-left corner, if applicable.

The image can be exported as a png image by clicking the “Export image” button at the bottom-right corner of theimage viewer, or by “File” -> “Export image”.

Note: Currently displaying beams of a cube with per-plane-beam is not supported.

4.11 Animator

The animator widget provides controls of image frames, channels, and stokes. When multiple images are loaded viaFile -> Append image, “Frame” slider will show up and allows users to switch between different loaded images. If animage file has multiple channels and/or stokes, “Channel” and/or “Stokes” slider will appear. The double slider rightbelow the “Channel” slider allows users to specify a range of channels for animation playback. On the top there is a setof animation control buttons such play, next, etc. Playback modes, including “forward”, “backward”, “Bouncing” and“Blink”, are supported. Playback action will be applied to the slider with the activated radio button. As an examplebelow, the action will be applied to the channel axis of the second stokes axis of the third image file, and the animationrange is from the second channel to the last channel.

The frame rate spin box controls the desired frame per second (fps). The actual frame rate depends on image size andinternet condition.

Note: Step for animation playback will be added in future releases. Currently the step is unity.

Warning: In v1.3, channel animation playback of spatially matched contour images is not supported. Onlyspatially matched raster image is supported. This limiiation will be removed in v1.4.


CHAPTER 5

Image cube analysis tools

With version 1.3, CARTA provides the following widgets for image cube analysis:

• Widget

– region list: to view and configure region properties

– spatial profiler: to view x and y spatial profiles at the cursor position

– spectral profiler: to view spectral profile from a region of interest

– histogram: to view histogram from a region of interest

– statistics: to view basic statistics from a region of interest

– Stokes analysis: to view basic polarization quantities

5.1 Region of interest

As of v1.3, CARTA supports the following region types:

• rectangle (rotatable)

• ellipse (rotatable)

• square (rotatable; as a special case of rectangle; “shift” key + drag)

• circle (as a special case of ellipse; “shift” key + drag)

• point

• polygon

The creation and modification of regions are demonstrated in the section Mouse interactions with region of interest.To create a region, use the region button at the bottom-right corner of the image viewer, then use cursor to draw aregion. CARTA allows regions to be created even if the region is outside the image. Keyboard shortcuts associatedwith regions are listed below.

39


macOS LinuxRegion properties double-click double-clickDelete selected region del / backspace del / backspaceToggle region creation mode C CDeselect region esc escSwitch region creation mode cmd + drag ctrl + dragSymmetric region creation shift + drag shift + dragPan image (inside region) cmd + click / middle-click ctrl + click / middle-clickToggle current region lock L LUnlock all regions shift + L shift + L

Tip: “backspace” does not delete a region. . .

If using CARTA remote mode in Firefox on MacOS, you may find the “backspace” key navigates back a page insteadof removing a region. This behaviour can be prevented by modifying your Firefox web browser settings:






All created regions are listed in the region list widget with basic region properties. To select a region (region statechanges to “selected”), simply click on the region in the image viewer, or click on the region in the region list widget.To modify the properties of a selected region, double-click on a region in the image viewer or a region in the regionlist widget. The color, line style, name, location, and shape, of a region are all configurable with the region propertydialogue. To de-select a region, press “esc” key. To delete a selected region, press “delete” or “backspace” key. Theactivated region can be locked by pressing “L” key or by clicking the “lock” icon in the region list widget or regionproperty dialogue. When a region is locked, it cannot be modified (resize, move, or delete) with mouse actions andthe “delete” or “backspace” key. A locked region, however, can still be modified or delected via the region propertydialogue. Locking a region could help the stituation when users want to modify overlapping regions, or could preventmodifying a region accidentally. The “eye” icon is to show the corresponding region at the center of image view.

CARTA checks if a polygon is simple or complex. If a polygon is detected as complex, its color will be in pink as awarning. Spectral profile, statistics, or histogram of a complex polygon can still be requested. However, the outcomemay be beyond users’ expectation. The enclosed pixels depend on how a complex polygon is constructed. Please usecomplex polygon with caution.

Region of interest enables practical image cube analysis through statistics, histogram, and spectral profiler widgets.When a region is selected, the region associated widgets will be highlighted with a persistent blue box as demonstratedbelow.

As of v1.3, CARTA supports basic region import and export capability. Regions, in world coordinate or in imagecoordinate, can be exported to a text file or imported from a text file. To import a region file, use the menu File ->Import regions.

To export regions to a region file, use the meun File -> Export regions. All regions, except cursor, will be exported.

As of v1.3, CASA region text format (.crtf) and ds9 region text formate (.reg) are supported with some limitations.Currently only the 2D region defination is supported. Other properties, such as spectral range, reference frame, ordecoration (line style, line width, etc.) will be supported in future releases.

The currently supported CRTF region syntax is summerized below:

40 Chapter 5. Image cube analysis tools

about:config

about:config


• Rectangle

– box[[x1, y1], [x2, y2]]

– centerbox[[x, y], [x_width, y_width]]

– rotbox[[x, y], [x_width, y_width], rotang]

• Ellipse

– circle[[x, y], r]

– ellipse[[x, y], [bmaj, bmin], pa]

• Polygon

– poly[[x1, y1], [x2, y2], [x3, y3], . . . ]

• Point

– symbol[[x, y], .]

Please refer to https://casa.nrao.edu/casadocs/casa-5.6.0/imaging/image-analysis/region-file-format for more detaileddescriptions about the CRTF syntax.

The currently supported ds9 region syntax is summerized below:

• Rectangle

– box x y width height angle

• Ellipse

– ellipse x y radius radius angle

– circle x y radius

• Polygon

– polygon x1 y1 x2 y2 x3 y3 . . .

• Point

– point x y

Please refer to http://ds9.si.edu/doc/ref/region.html for more detailed descriptions about the ds9 region syntax.

Warning: In v1.3, region is registered to individual image (just like v1.2) even if the image is matched to otherimages in world coordinates. This limitation will be removed in v1.4, so that users can request analytics data fromall matched images in the same region.

5.2 Spatial profiler

Spatial profiler provides the spatial profiles of the current image at the cursor position. When the cursor is movingon the image, profiles derived from the full resolution raster image are displayed. The “F” key will disable or enableprofile update. When cursor update is disabled, a marker “+” will be placed on the image to indicate the position ofthe profiles taken.

When displaying a spatial profile with the number of pixels more than the number of screen pixels of the spatial profilerwidget, a decimated profile will be derived and displayed to users as an enhancement of performance. Min/maxdecimation of a profile is adopted to ensure profile features are preserved. In other words, positive and negative peaksshould stay at the same screen pixels just like displaying the full resolution profile. When users keep zooming in the

5.2. Spatial profiler 41

https://casa.nrao.edu/casadocs/casa-5.6.0/imaging/image-analysis/region-file-format

http://ds9.si.edu/doc/ref/region.html


profile, decimation with narrower and narrower interval is applied dynamically. Full resolution profile is displayedwhen the number of screen pixels is more than the number of pixels of the profile to be displayed.

The interactions of the spatial profiler widget are demonstrated in the section Mouse interactions with charts. The redvertical bar indicates the pixel where the profile is taken. The bottom axis shows the image coordinate, while optionalworld coordinate is displayed on the top axis. Extra options to configure the profile plot are available in the spatialprofiler settings dialogue which is launched by clicking the “cog” icon at the top-right corner. The option “ShowMean/RMS” will adopt the data in the current view to derive a mean value and an rms value, and visualize the resultson the plot. Numerical values are also displayed at the bottom-left corner. The profile can be exported as a png imageor a text file in tsv format via the buttons at the bottom-right corner.

When the cursor is on the image in the image viewer, the pointed pixel value (pixel index and pixel value) will bedisplayed at the bottom-left corner of the spatial profiler. When the cursor is on the spatial profiler graph, the pointedprofile data will be displayed instead.

Note: In future release, the following features will be supported:

• More flexibilities on how mean and rms values are derived in the plot

• Profile fitting capability

• Profile along a line segment, polyline, or an arbitary curve

5.3 Spectral profiler

Spectral profiler provides the spectral profile of the current image cube at the selected region. The default region is setto “Cursor”. The “F” key will disable or enable cursor profile update. When cursor update is disabled, a marker “+”will be placed on the image to indicate the position of the profile taken.

When requesting a spectral profile, a common disappointing user experience is that users may have to wait for anunknown amount of time to see the final result if the image cube is large. As an improvement on this aspect, CARTAsupports progressive update of spectral profile. Partial profiles will be periodically delivered to users while the fullprofile calculations are still ongoing.

When the property of a region (cursor or a regular region) is modified while the profile of the original region is beingupdated, the partial profile will disappear and a new partial profile cooresponding to the new region will start updating.If users modify the request of a spectral profile via the spectral profile widget before it is fully delivered, the originalprofile calculations will be cancelled and new profile calculations will start. In short, now CARTA should just focuson calculating and showing the profiles that users pay attention to. If a profile is no longer needed to be shown on thescreen, the profile calculation will be cancelled immediately, instead of blocking and queueing up new profile requests.

When displaying a spectral profile with the number of channels more than the number of screen pixels of the spectralprofiler widget, a decimated profile will be derived and displayed to users as an enhancement of performance. Min/maxdecimation of a profile is adopted to ensure profile features are preserved. In other words, positive and negative peaksshould stay at the same screen pixels just like displaying the full resolution profile. When users keep zooming in theprofile, decimation with narrower and narrower interval is applied dynamically. Full resolution profile is displayedwhen the number of screen pixels is more than the number of pixels of the profile to be displayed.

When regions are created, the spectral profiler widget can be configured to display a profile from a specific region withthe “region” dropdown menu. The default of the “region” dropdown is “Active” which points to the current active(selected) region. If no region is active, it defaults to cursor region. Additional statistic types to compute the regionspectral profile are available with the “statistic” dropdown menu (default to mean). If the image cube has multipleStokes, the “Stokes” dropdown menu will be activated and defaulted to “current” which is synchronized with theselection in the animator. To view a specific Stokes, select with the “Stokes” dropdown menu.



Multiple spectral profile widgets can be configured to display different region spectral profiles. The widget with theselected region will be highlighted with a persistent blue box.

The interactions of the spectral profiler widget are demonstrated in the section Mouse interactions with charts. Thered vertical bar indicates the channel of the image displayed in the image viewer. Clicking directly on the spectralprofiler graph will change the displayed image to the clicked channel. Alternatively, the red vertical bar is draggableand acts just like the animator slider.

The bottom axis shows the spectral coordinate, Extra options to configure the profile plot are available in the spectralprofile settings dialogue which can be launched by clicking the “cog” icon in the top-right corner. In the dialogue,users may select a different spectral convention (e.g., optical velocity) and a different reference system (e.g., TOPO).The option “Show Mean/RMS” will adopt the data in the current view to derive a mean value and an rms value, andvisualize the results on the plot. Numerical values are also displayed at the bottom-left corner. When the cursor is onthe image in the image viewer, the pointed pixel value (frequency or velocity or channel index, and pixel value) willbe displayed at the bottom-left corner of the spectral profiler. When the cursor is on the spectral profiler graph, thepointed profile data will be displayed instead. The profile can be exported as a png image or a text file in tsv formatvia the buttons at the bottom-right corner.

Note: In future releases, the follow features will be supported:

• More flexibilities on how mean and rms values are derived

• Profile fitting

• Line identification toolkit

• Intensity unit conversion

5.4 Stokes analysis widget

Stokes analysis widget allows users to view basic polarization quantities of a multi-channel (number of channel > 1),multi-Stokes (IQU or IQUV) cube efficiently. The widget includes the following plots:

• Stokes Q intensity and Stokes U intensity over the spectral axis

• Linearly polarized intensity over the spectral axis

• Linear polarization angle over the spectral axis

• Stokes Q intensity versus Stokes U intensity

The profiles can be zoomed and panned with mouse similar to the spatial profile widget or the spectral profile widget(Mouse interactions with charts). The Stokes Q versus Stokes U scatter plot is color-encoded from red to blue withincreasing frequencies. The profiles can be requested at the cursor position (single pixel) or over a region of interest.Fractional polarization quantities are also supported. Examples are given in the following figures. The first one is fromreal ALMA data, while the second one is from an artifical Stokes cube.

When profiles are zoomed, the scatter plot will highlight those channels remaining in the profile view. Similarly, whenscatter plot is zoomed, the profile plot will highlight those channels remaining in the scatter plot view.

Additional options to customize the plots in the Stokes analysis widget are provided in the settings dialogue which canbe launched by clicking the “cog” icon at the top-right corner.

5.4. Stokes analysis widget 43


5.5 Statistics widget

Statistics widget allows users to see statistics with respect to a selected region. The “Region” dropdown menu can beused to select which region statistics to be displayed. The default is “Active” which means the current active (selected)region. If no region is active, it defaults to the entire image of the displayed channel to compute statistics. Multiplestatistics widgets can be created to display statistics of different regions as demonstrated below. The widget with theselected region will be highlighted with a persistent blue box.

5.6 Histogram widget

Histogram widget allows users to visualize data in a histogram with respect to a selected region. The “Region”dropdown menu can be used to select which region histogram to be displayed. The default is “Active” which meansthe current active (selected) region. If no region is active, it defaults to the entire image of the displayed channelto construct a histogram. Multiple histogram widgets can be created to display histograms of different regions asdemonstrated below. The widget with the selected region will be highlighted with a persistent blue box.

Additional options to customize the histogram in the histogram widget are provided in the settings dialogue which canbe launched by clicking the “cog” icon at the top-right corner.

Note: With v1.3, histogram bin width and bin count are automatically decided. Enhancement of the histogram widget,including histogram fitting, will be available in future releases.


CHAPTER 6

Appendix A: version history

6.1 Version 1.3.1

Released 5th May 2020

Bug fixes

• Truncated header values in HDF5 images.

• Crashes when creating a region on a single channel image while the spectral profiler is launched.

• Hanging when requesting statistics.

• Correct axes labeling in region widget.

• Swapped major/minor axes of ellipse when exporting as region file.

• Incorrect or inaccurate angular size of rectangle and ellipse regions in the region dialog.

• Server version database fix.

6.2 Version 1.3

Released 31th March 2020

• Contour rendering

• Matching images in world coordinates

• Support “Active” region type in analytics widgets

• Enhanced remote mode for desktop version

• Spectral conversion in the spectral profiler

• Tiled animation

• In-app help manual

45


Performance enhancement and bug fixes are included as well.

6.3 Version 1.2.2

Released 3rd January 2020

• Critical bug fix

6.4 Version 1.2.1

Released 30th October 2019

• Support region import/export in ds9 syntax

• Critical bug fix

6.5 Version 1.2

Released 28th August 2019

This release includes the following new features:

• New server authentication method

• User preferences and layouts

• Tiled rendering and animator enhancement

• support point and polygon regions

• support region import/export in crtf syntax

• introducing enhanced profile delivery strategies

• new Stokes analysis widget

• support HDF5 images under IDIA schema

Performance enhancement and bug fixes are included as well.

6.6 Version 1.1

Released 2nd May 2019.

Initial support of region of interest and the HDF5-IDIA image format.

This version enables the initial support of region of interest and relevant analysis tools (statistics, histogram, regionspectral profiler). Initial support of the HDF5-IDIA image format is implemented, which takes the advantage of pre-calculated data and rotated cube to speed up some time-consuming tasks. A basic server-side authentication modeland command line startup options are provided. Performance enhancement and bug fixes are included as well.

46 Chapter 6. Appendix A: version history


6.7 Version 1.0.1

Released 6th March 2019.

Patch release of version 1.0.

With version 1.0.1 patch release, CARTA futher provides enhanced file browser navigation capability, remote server(backend) status icon, improvements of file information and header, and displaying data values in the spatial and thespectral profilers.

6.8 Version 1.0

Released 29th December 2018.

Initial release.

This version provides basic image viewing capabilities, basic profile viewing capabilities in both spatial and spectraldomains, and basic per-frame or per-cube histogram viewing capabilities. Exporting images or charts in png formatand charts in plain text format are supported.

6.7. Version 1.0.1 47


48 Chapter 6. Appendix A: version history

CHAPTER 7

Appendix B: known issues

CARTA has the following known issues for the release v1.3. The CARTA development team will try to fix them incoming releases. The list is updated up to March 31, 2020.

7.1 Stability and performace

• cursor update for profiles stops during zoom (GitHub issue)

• performance impact of AST grid tolerance to wide field images (GitHub issue)

7.2 File browser

• Some FITS files with multiple HDUs can’t be opened in CARTA (GitHub issue)

• casacore processed headers when exceptions happen (GitHub issue)

• Regression: Opening certain files results in invalid WCS (GitHub issue)

• CARTA hangs in file info gathering step (GitHub issue)

• TabularCoordinate - start and end values in table must differ (GitHub issue)

• HDF5 files with a non-float main dataset are not supported (GitHub issue)

7.3 Animator

• frame label and other info out of sync with image change when animating between frames (GitHub issue)

• a flash with missing tiles then full image restored when we press stop to stop animation (GitHub issue)

• incomplete contour rendering when stop animating (GitHub issue)

• Synchronise contour and raster data when animating (GitHub issue)

49

https://github.com/CARTAvis/carta-frontend/issues/544


https://github.com/CARTAvis/carta-backend/issues/476











• no radio button is checked (GitHub issue)

• Req index and Current index in animator (GitHub issue)

• mis-aligned range index with current index in the animator (GitHub issue)

• backend keeps streaming image data repeatedly after animation has stopped (GitHub issue)

• backend stops responding when stop animating raster+contour images (GitHub issue)

7.4 Contour configuration

• contour level generator still generates levels when parameters are not properly set (GitHub issue)

7.5 Image viewer

• show empty sky if no tile is requested when switching between spatially matched images (GitHub issue)

• panning and zooming of spatially matched images is odd if image has very different FoV to reference (GitHubissue)

• Show correct beam for multi-beam images (GitHub issue)

• incorrect “AUTO” coordinate system when loading image as new (GitHub issue)

7.6 Spectral profiler

• unit of y axis in the spectral profile with different statistics (GitHub issue)

7.7 Stokes analysis

• missing grid lines when zooming the Q vs U scatter plot in the Stokes widget (GitHub issue)

7.8 Region of interest

• Render imported regions based on their color definitions if exist (GitHub issue)

• Cannot export regions when image has invalid or non-existent WCS headers (GitHub issue)

• symmetric creation/modification of a region with side anchor and shift key (GitHub issue)

• regions away from the reference pixel are distorted and give the wrong pixel count (GitHub issue)

• Cannot import/export regions when image has invalid or non-existent WCS headers (GitHub issue)

50 Chapter 7. Appendix B: known issues




















7.9 GUI

• reload get blank frontend layout when backend is lost (GitHub issue)

• keyboard event conflict between image viewer and drop down menu (GitHub issue)

• floating widget cannot be moved to new location if its content is updating (spectral profile) (GitHub issue)

• x range of profile widget (spatial/spectral) when open a new image (GitHub issue)

• Zooming in a profile in point style results in empty plot (GitHub issue)

• [dynamic layout] raster view turns black when switching layouts during animation (GitHub issue)

• draggable marker should be stopped when out of chart (GitHub issue)

7.9. GUI 51









52 Chapter 7. Appendix B: known issues

CHAPTER 8

Appendix C: development log

8.1 v1.2 -> v1.3

Frontend

• Closed issues

• Merged pull requests

Backend

• Closed issues


8.2 v1.1 -> v1.2

Frontend

• Closed issues


Backend

• Closed issues


8.3 v1.0 -> v1.1

Frontend

• Closed issues

53

https://github.com/CARTAvis/carta-frontend/issues?q=is%3Aissue+closed%3A2019-08-29..2020-03-31

https://github.com/CARTAvis/carta-frontend/issues?q=merged%3A2019-08-29..2020-03-31+

https://github.com/CARTAvis/carta-backend/issues?q=is%3Aissue+closed%3A2019-08-29..2020-03-31+

https://github.com/CARTAvis/carta-backend/issues?q=merged%3A2019-08-29..2020-03-31+



https://github.com/CARTAvis/carta-backend/issues?q=is%3Aissue+closed%3A2019-05-03..2019-08-28





Backend

• Closed issues


54 Chapter 8. Appendix C: development log


https://github.com/CARTAvis/carta-backend/issues?q=is%3Aissue+closed%3A2018-12-30..2019-05-02


Index

TTable of Content, 1

55

CARTA Documentation

Documents

Transcript of CARTA Documentation