carta package

carta.backend module

This module provides a backend object which corresponds to a CARTA backend process. It is used by the wrapper to manage a local or remote backend process directly when creating a headless browser session.

class carta.backend.Backend(params, executable_path='carta', remote_host=None, token=None, frontend_url_timeout=10, session_creation_timeout=0)

Bases: object

Helper class for managing a CARTA backend process.

You should not need to instantiate this directly; it is created on demand by a carta.browser.Browser object.

Parameters:

  • params (iterable) – Parameters to pass to the CARTA backend process. Example: ["--verbosity", 5, "--port", 3010]

  • executable_path (string) – The path to the backend executable. Default: "carta".

  • remote_host (string) – If this is set, an attempt will be made to start the backend over ssh on this host.

  • token (carta.token.BackendToken) – If this is set, this will be used as the security token and no attempt will be made to parse the token from the backend output.

  • frontend_url_timeout (integer) – How long to keep checking the output for the frontend URL. Default: 10 seconds.

  • session_creation_timeout (integer) – How long to keep checking the output for a default session ID. If this is set to zero (which is the default), no attempt is made to parse a session ID from the output. The calling function should set this to a non-zero value if parsing the session ID is required.

Variables:

  • proc (subprocess.Popen) – The backend subprocess object. Set by the carta.backend.Backend.start method.

  • frontend_url (string) – The URL of the running frontend, parsed from the output of the backend process. Set by the carta.backend.Backend.start method.

  • token (carta.token.BackendToken) – The security token of the running backend, either parsed from the output of the backend process and set by the carta.backend.Backend.start method, or overridden with a parameter.

  • debug_no_auth (boolean) – If this is set, the backend will accept HTTP connections with no authentication token. This is provided for debugging purposes only and should not be used under normal circumstances. This value is automatically detected from the provided backend parameters.

  • output (list of strings) – All output of the backend process, split into lines, terminated by newline characters.

  • errors (list of strings) – Error output of the backend process, split into lines, terminated by newline characters.

  • last_session_id (integer) – The ID of the last session connected to this backend process, parsed from the process output. This is likely to be the default session automatically created in the user’s browser on startup, if this functionality was not suppressed with the --no_browser flag. This value is used by the carta.session.Session.start_and_interact method, which connects to this default session. It is not used by the session creation methods which use a wrapper-controlled headless browser, as those parse the session ID from the browser session.

  • frontend_url_timeout (integer) – How long to keep checking the output for the frontend URL.

  • session_creation_timeout (integer) – How long to keep checking the output for a default session ID. If this is set to zero, no attempt is made to parse a session ID from the output.

Returns:

A backend object with a process which has not been started.

Return type:

carta.backend.Backend

FRONTEND_URL = re.compile('CARTA is accessible at (http://.*)')
SESSION_ID = re.compile('Session (\\d+) \\[[\\d.]+\\] Connected.')
start()

Start the backend process.

This method creates the subprocess object and parses the backend host and the frontend URL from the process output.

stop()

Stop the backend process.

This method terminates the backend process if it exists and is running.

carta.browser module

This module provides browser objects which can be used to create new sessions. It depends on the selenium library. The desired browser and its corresponding web driver also have to be installed.

class carta.browser.Browser(driver_class, **kwargs)

Bases: object

The top-level browser class.

Some common use cases are provided as subclasses, but you may instantiate this class directly to create a browser with custom configuration.

Parameters:

  • driver_class (a selenium web driver class) – The class to use for the browser driver.

  • **kwargs – Keyword arguments which will be passed to the driver class constructor.

Variables:

driver (selenium.webdriver.remote.webdriver.WebDriver) – The browser driver.

close()

Shut down the browser driver.

exit(msg)

Exit the browser with an error.

new_session_from_url(frontend_url, token=None, backend=None, timeout=10, debug_no_auth=False)

Create a new session by connecting to an existing backend.

You can use carta.session.Session.create, which wraps this method.

Parameters:

  • frontend_url (string) – The URL of the frontend.

  • token (carta.token.Token, optional) – The security token used by the CARTA instance. May be omitted if the URL contains a token.

  • backend (carta.backend.Backend) – The backend object associated with this session, if any. This is set if this method is called from carta.browser.Browser.new_session_with_backend.

  • timeout (number, optional) – The number of seconds to spend parsing the frontend for connection information. 10 seconds by default.

  • debug_no_auth (boolean) – Disable authentication. This should be set if the backend has been started with the --debug_no_auth option. This is provided for debugging purposes only and should not be used under normal circumstances.

Returns:

A session object connected to a new frontend session running in this browser.

Return type:

carta.session.Session

Raises:
new_session_with_backend(executable_path='carta', remote_host=None, params=(), timeout=10, token=None, frontend_url_timeout=10)

Create a new session after launching a new backend process.

You can use carta.session.Session.start_and_create, which wraps this method. This method starts a backend process, parses the frontend URL from the output, and calls carta.browser.Browser.new_session_from_url.

Parameters:

  • executable_path (string, optional) – A custom path to the CARTA backend executable. The default is "carta".

  • remote_host (string, optional) – A remote host where the backend process should be launched, which must be accessible through passwordless ssh. By default the backend process is launched on the local host.

  • params (iterable, optional) – Additional parameters to be passed to the backend process. By default scripting is enabled and the automatic browser is disabled. The parameters are appended to the end of the command, so a positional parameter for a data directory can be included. Example: ["--verbosity", 5, "--port", 3010]

  • timeout (number, optional) – The number of seconds to spend parsing the frontend for connection information. 10 seconds by default.

  • token (carta.token.BackendToken, optional) – The security token to use. Parsed from the backend output by default.

  • frontend_url_timeout (integer) – How long to keep checking the backend output for the frontend URL. Default: 10 seconds.

Returns:

A session object connected to a new frontend session running in this browser.

Return type:

carta.session.Session

Raises:
class carta.browser.Chrome(headless=True, browser_path=None, driver_path=None, options=())

Bases: Browser

Chrome or Chromium, optionally headless.

Parameters:

  • headless (boolean, optional) – Run the browser headless (this is the default).

  • browser_path (string, optional) – A path to a custom chrome or chromium executable.

  • driver_path (string, optional) – A path to a custom chromedriver executable.

  • options (iterable, optional) – Additional options. A list of strings, one per option (--option or --option=argument).

carta.constants module

This module provides a collection of enums corresponding to various enumerated types and other literal lists of options defined in the frontend. The members of these enums should be used in place of literal strings and numbers to represent these values; for example: Colormap.VIRIDIS rather than "viridis".

class carta.constants.Auto(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: StrEnum

Special value for parameters to be calculated automatically.

AUTO = 'Auto'
class carta.constants.BeamType(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: StrEnum

Beam types.

OPEN = 'open'
SOLID = 'solid'
class carta.constants.ColorbarPosition(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: StrEnum

Colorbar positions.

BOTTOM = 'bottom'
RIGHT = 'right'
TOP = 'top'
class carta.constants.Colormap(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: StrEnum

All available colormaps.

ACCENT = 'accent'
AFMHOT = 'afmhot'
AUTUMN = 'autumn'
BINARY = 'binary'
BLUES = 'Blues'
BONE = 'bone'
BRBG = 'BrBG'
BRG = 'brg'
BUGN = 'BuGn'
BUPU = 'BuPu'
BWR = 'bwr'
CMRMAP = 'CMRmap'
COOL = 'cool'
COOLWARM = 'coolwarm'
COPPER = 'copper'
CUBEHELIX = 'cubehelix'
DARK2 = 'dark2'
FLAG = 'flag'
GIST_EARTH = 'gist_earth'
GIST_GRAY = 'gist_gray'
GIST_HEAT = 'gist_heat'
GIST_NCAR = 'gist_ncar'
GIST_RAINBOW = 'gist_rainbow'
GIST_STERN = 'gist_stern'
GIST_YARG = 'gist_yarg'
GNBU = 'GnBu'
GNUPLOT = 'gnuplot'
GNUPLOT2 = 'gnuplot2'
GRAY = 'gray'
GREENS = 'greens'
GREYS = 'greys'
HOT = 'hot'
HSV = 'hsv'
INFERNO = 'inferno'
JET = 'jet'
MAGMA = 'magma'
NIPY_SPECTRAL = 'nipy_spectral'
OCEAN = 'ocean'
ORANGES = 'oranges'
ORRD = 'OrRd'
PAIRED = 'paired'
PASTEL1 = 'pastel1'
PASTEL2 = 'pastel2'
PINK = 'pink'
PIYG = 'PiYG'
PLASMA = 'plasma'
PRGN = 'PRGn'
PRISM = 'prism'
PUBU = 'PuBu'
PUBUGN = 'PuBuGn'
PUOR = 'PuOr'
PURD = 'PuRd'
PURPLES = 'purples'
RAINBOW = 'rainbow'
RDBU = 'RdBu'
RDGY = 'RdGy'
RDPU = 'RdPu'
RDYLBU = 'RdYlBu'
RDYLGN = 'RdYlGn'
REDS = 'reds'
SEISMIC = 'seismic'
SET1 = 'set1'
SET2 = 'set2'
SET3 = 'set3'
SPECTRAL = 'spectral'
SPRING = 'spring'
SUMMER = 'summer'
TAB10 = 'tab10'
TAB20 = 'tab20'
TAB20B = 'tab20b'
TAB20C = 'tab20c'
TERRAIN = 'terrain'
VIRIDIS = 'viridis'
WINTER = 'winter'
WISTIA = 'Wistia'
YLGN = 'YlGn'
YLGNBU = 'YlGnBu'
YLORBR = 'YlOrBr'
YLORRD = 'YlOrRd'
class carta.constants.ComplexComponent(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: StrEnum

Complex component.

AMPLITUDE = 'AMPLITUDE'
IMAG = 'IMAG'
PHASE = 'PHASE'
REAL = 'REAL'
class carta.constants.ContourDashMode(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: StrEnum

Contour dash modes.

DASHED = 'Dashed'
NEGATIVE_ONLY = 'NegativeOnly'
NONE = 'None'
class carta.constants.CoordinateSystem(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: StrEnum

Coordinate systems.

AUTO = 'AUTO'
ECLIPTIC = 'ECLIPTIC'
FK4 = 'FK4'
FK5 = 'FK5'
GALACTIC = 'GALACTIC'
ICRS = 'ICRS'
class carta.constants.FontFamily(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: IntEnum

Font family used in WCS overlay components.

ARIAL = 2
COURIER_NEW = 4
PALATINO = 3
SANS_SERIF = 0
TIMES = 1
class carta.constants.FontStyle(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: IntEnum

Font style used in WCS overlay components.

BOLD = 2
BOLD_ITALIC = 3
ITALIC = 1
NORMAL = 0
class carta.constants.GridMode(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: StrEnum

Grid modes.

DYNAMIC = 'dynamic'
FIXED = 'fixed'
class carta.constants.LabelType(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: StrEnum

Label types.

EXTERIOR = 'Exterior'
INTERIOR = 'Interior'
class carta.constants.NumberFormat(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: StrEnum

Number formats.

DEGREES = 'd'
DMS = 'dms'
HMS = 'hms'
class carta.constants.Overlay(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: StrEnum

WCS overlay elements.

Member values are paths to stores corresponding to these elements, relative to the WCS overlay store.

AXES = 'axes'
BEAM = 'beam.settingsForDisplay'
BORDER = 'border'
COLORBAR = 'colorbar'
GLOBAL = 'global'
GRID = 'grid'
LABELS = 'labels'
NUMBERS = 'numbers'
TICKS = 'ticks'
TITLE = 'title'
class carta.constants.PaletteColor(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: StrEnum

Palette colours used for WCS overlay elements.

Members of this enum class have additional attributes.

Variables:

  • rgb_light (string) – The RGB value of this palette colour in the light theme.

  • rgb_dark (string) – The RGB value of this palette colour in the dark theme.

BLACK = 'auto-black'
BLUE = 'auto-blue'
COBALT = 'auto-cobalt'
DARK_GRAY = 'auto-dark_gray'
FOREST = 'auto-forest'
GOLD = 'auto-gold'
GRAY = 'auto-gray'
GREEN = 'auto-green'
INDIGO = 'auto-indigo'
LIGHT_GRAY = 'auto-light_gray'
LIME = 'auto-lime'
ORANGE = 'auto-orange'
RED = 'auto-red'
ROSE = 'auto-rose'
SEPIA = 'auto-sepia'
TURQUOISE = 'auto-turquoise'
VERMILION = 'auto-vermilion'
VIOLET = 'auto-violet'
WHITE = 'auto-white'
class carta.constants.PanelMode(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: IntEnum

Panel modes.

MULTIPLE = 1
SINGLE = 0
class carta.constants.Polarization(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: IntEnum

Polarizations, corresponding to the POLARIZATIONS enum in the frontend.

I = 1
LL = -2
LR = -4
PANGLE = 17
PFLINEAR = 16
PFTOTAL = 15
PLINEAR = 14
PTOTAL = 13
Q = 2
RL = -3
RR = -1
U = 3
V = 4
XX = -5
XY = -7
YX = -8
YY = -6
class carta.constants.Scaling(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: IntEnum

Colormap scaling types.

GAMMA = 5
LINEAR = 0
LOG = 1
POWER = 4
SQRT = 2
SQUARE = 3
class carta.constants.SmoothingMode(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: IntEnum

Contour smoothing modes.

BLOCK_AVERAGE = 1
GAUSSIAN_BLUR = 2
NO_SMOOTHING = 0
class carta.constants.SpatialAxis(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: StrEnum

Spatial axes.

X = 'x'
Y = 'y'
class carta.constants.SpectralSystem(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: StrEnum

Spectral systems.

BARY = 'BARYCENT'
LSRD = 'LSRD'
LSRK = 'LSRK'
TOPO = 'TOPOCENT'
class carta.constants.SpectralType(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: StrEnum

Spectral types.

Members of this enum class have additional attributes.

Variables:
AWAV = 'AWAV'
FREQ = 'FREQ'
VOPT = 'VOPT'
VRAD = 'VRAD'
WAVE = 'WAVE'
class carta.constants.SpectralUnit(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: StrEnum

Spectral units.

ANGSTROM = 'Angstrom'
GHZ = 'GHz'
HZ = 'Hz'
KHZ = 'kHz'
KMS = 'km/s'
M = 'm'
MHZ = 'MHz'
MM = 'mm'
MS = 'm/s'
NM = 'nm'
UM = 'um'
class carta.constants.VectorOverlaySource(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: int, Enum

Vector overlay source.

COMPUTED = 1
CURRENT = 0
NONE = -1

carta.contours module

This module contains functionality for interacting with the contours of an image. The class in this module should not be instantiated directly. When an image object is created, a contours object is automatically created as a property.

class carta.contours.Contours(image)

Bases: BasePathMixin

Utility object for collecting image functions related to contours.

Parameters:

image (carta.image.Image object) – The image associated with this contours object.

Variables:
apply()

Apply the contour configuration.

clear()

Clear the contours.

configure(levels=None, smoothing_mode=None, smoothing_factor=None)

Configure contours.

Parameters:

  • levels (an iterable in which each element is a number or None) – The contour levels. This may be a numeric numpy array; e.g. the output of arange. If this is unset, the current configured levels will be used.

  • smoothing_mode (a member of carta.constants.SmoothingMode or None) – The smoothing mode. If this is unset, the frontend default will be used.

  • smoothing_factor (a number or None) – The smoothing kernel size in pixels. If this is unset, the frontend default will be used.

hide()

Hide the contours.

plot(levels=None, smoothing_mode=None, smoothing_factor=None, dash_mode=None, thickness=None, color=None, colormap=None, bias=None, contrast=None)

Configure contour levels, scaling, dash, and colour or colourmap; and apply contours; in a single step.

If both a colour and a colourmap are provided, the colourmap will be visible.

Parameters:

  • levels (an iterable in which each element is a number or None) – The contour levels. This may be a numeric numpy array; e.g. the output of arange. If this is unset, the current configured levels will be used.

  • smoothing_mode (a member of carta.constants.SmoothingMode or None) – The smoothing mode. If this is unset, the frontend default will be used.

  • smoothing_factor (a number or None) – The smoothing kernel size in pixels. If this is unset, the frontend default will be used.

  • dash_mode (a member of carta.constants.ContourDashMode or None) – The dash mode.

  • thickness (a number or None) – The thickness.

  • color (an HTML color specification or None) – The color. The default is green.

  • colormap (a member of carta.constants.Colormap or None) – The colormap. The default is carta.constants.Colormap.VIRIDIS.

  • bias (a number greater than or equal to -1 and smaller than or equal to 1 or None) – The colormap bias.

  • contrast (a number greater than or equal to 0 and smaller than or equal to 2 or None) – The colormap contrast.

set_bias_and_contrast(bias=None, contrast=None)

Set the contour bias and contrast.

Parameters:

  • bias (a number greater than or equal to -1 and smaller than or equal to 1 or None) – The colormap bias. The initial value is 0.

  • contrast (a number greater than or equal to 0 and smaller than or equal to 2 or None) – The colormap contrast. The initial value is 1.

set_color(color)

Set the contour color.

This automatically disables use of the contour colormap.

Parameters:

color (an HTML color specification) – The color. The default is green.

set_colormap(colormap)

Set the contour colormap.

This also automatically enables the colormap.

Parameters:

colormap (a member of carta.constants.Colormap) – The colormap. The default is carta.constants.Colormap.VIRIDIS.

set_dash_mode(dash_mode)

Set the contour dash mode.

Parameters:

dash_mode (a member of carta.constants.ContourDashMode) – The dash mode.

set_thickness(thickness)

Set the contour thickness.

Parameters:

thickness (a number) – The thickness.

set_visible(state)

Set the contour visibility.

Parameters:

state (a boolean) – The desired visibility state.

show()

Show the contours.

carta.image module

This module contains an image class which represents a single image open in the session.

Image objects should not be instantiated directly, and should only be created through methods on the carta.session.Session object.

class carta.image.Image(session, image_id)

Bases: BasePathMixin

This object corresponds to an image open in a CARTA frontend session.

This class should not be instantiated directly. Instead, use the session object’s methods for opening new images or retrieving existing images.

Parameters:

  • session (carta.session.Session) – The session object associated with this image.

  • image_id (integer) – The ID identifying this image within the session. This is a unique number which is not reused, not the index of the image within the list of currently open images.

Variables:
close()

Close this image.

property depth

The depth of the image. This value is transparently cached on the parent object.

Returns:

The depth.

Return type:

integer

property directory

The path to the directory containing the image. This value is transparently cached on the parent object.

Returns:

The directory path.

Return type:

string

property file_name

The name of the image. This value is transparently cached on the parent object.

Returns:

The image name.

Return type:

string

classmethod from_list(session, image_list)

Create a list of image objects from a list of open images retrieved from the frontend.

This method should not be used directly. It is wrapped by carta.session.Session.image_list.

Parameters:

  • session (carta.session.Session) – The session object.

  • image_list (list of dicts) – The JSON object representing frame names retrieved from the frontend.

Returns:

A list of new image objects.

Return type:

list of carta.image.Image

property header

The header of the image, parsed from the raw frontend data (see carta.metadata.parse_header). This value is transparently cached on the parent object.

Returns:

The header of the image, with field names as keys.

Return type:

dict of string to string, integer, float, boolean, None or list of strings

property height

The height of the image in pixels. This value is transparently cached on the parent object.

Returns:

The height.

Return type:

integer

property is_pv

Whether this is a spatial-spectral image. This value is transparently cached on the parent object.

Returns:

Whether this is a spatial-spectral image.

Return type:

boolean

make_active()

Make this the active image.

make_raster_scaling_reference()

Make this image the raster scaling reference.

make_spatial_reference()

Make this image the spatial reference.

make_spectral_reference()

Make this image the spectral reference.

property ndim

The number of dimensions of the image. This value is transparently cached on the parent object.

Returns:

The number of dimensions.

Return type:

integer

classmethod new(session, directory, file_name, hdu, append, image_arithmetic, make_active=True, update_directory=False)

Open or append a new image in the session and return an image object associated with it.

This method should not be used directly. It is wrapped by carta.session.Session.open_image, carta.session.Session.open_complex_image and carta.session.Session.open_LEL_image.

Parameters:

  • session (carta.session.Session) – The session object.

  • directory (string) – The directory containing the image file or the base directory for the LEL arithmetic expression, either relative to the session’s current directory or an absolute path relative to the CARTA backend’s root directory.

  • file_name (string) – The name of the image file, or a LEL arithmetic expression.

  • hdu (string) – The HDU to open.

  • append (boolean) – Whether the image should be appended.

  • image_arithmetic (boolean) – Whether the file name should be interpreted as a LEL expression.

  • make_active (boolean) – Whether the image should be made active in the frontend. This only applies if an image is being appended. The default is True.

  • update_directory (boolean) – Whether the starting directory of the frontend file browser should be updated to the directory provided. The default is False.

Returns:

A new image object.

Return type:

carta.image.Image

property num_polarizations

The number of polarizations of the image, excluding computed polarizations. This value is transparently cached on the parent object.

Returns:

The number of polarizations.

Return type:

integer

property polarizations

The available polarizations of the image. This value is transparently cached on the parent object.

This includes Stokes parameters, correlations, and computed components.

Returns:

The available polarizations.

Return type:

list of members of carta.constants.Polarization

set_center(x, y)

Set the center position, in image or world coordinates.

World coordinates are interpreted according to the session’s globally set coordinate system and any custom number formats. These can be changed using carta.session.set_coordinate_system and set_custom_number_format.

Coordinates must either both be image coordinates or match the current number formats. Numbers are interpreted as image coordinates, and numeric strings with no units are interpreted as degrees.

Parameters:

  • x (a number, a string in H:M:S or D:M:S format, or a numeric string with degree units) – The X position.

  • y (a number, a string in H:M:S or D:M:S format, or a numeric string with degree units) – The Y position.

Raises:

ValueError – If a mix of image and world coordinates is provided, if world coordinates are provided and the image has no valid WCS information, or if world coordinates do not match the session-wide number formats.

set_channel(channel, recursive=True)

Set the channel.

Parameters:

  • channel (a number greater than or equal to 0 and smaller than self.depth , in increments of 1, evaluated at runtime) – The desired channel.

  • recursive (a boolean) – Whether to perform the same change on all spectrally matched images. Defaults to True.

set_cube_matching(state)

Enable or disable spatial and spectral matching.

Parameters:

state (boolean) – The desired spatial and spectral matching state.

set_polarization(polarization, recursive=True)

Set the polarization.

Parameters:

  • polarization (one of *self.polarizations, evaluated at runtime) – The desired polarization.

  • recursive (a boolean) – Whether to perform the same change on all spectrally matched images. Defaults to True.

set_raster_scaling_matching(state)

Enable or disable raster scaling matching.

Parameters:

state (boolean) – The desired raster scaling matching state.

set_spatial_matching(state)

Enable or disable spatial matching.

Parameters:

state (boolean) – The desired spatial matching state.

set_spectral_coordinate(spectral_type, spectral_unit=None)

Set the coordinate type and unit used for the spectral axis in the image viewer.

This is only applicable to spatial-spectral images, such as position-velocity images or cubes with permuted axes like RA-FREQ-DEC.

Parameters:
Raises:

ValueError – If this is not a spatial-spectral image, or the type is not supported, or the unit is not supported.

set_spectral_matching(state)

Enable or disable spectral matching.

Parameters:

state (boolean) – The desired spectral matching state.

set_spectral_system(spectral_system)

Set the coordinate system used for the spectral axis in the image viewer.

This is only applicable to spatial-spectral images, such as position-velocity images or cubes with permuted axes like RA-FREQ-DEC.

Parameters:

spectral_system (a member of carta.constants.SpectralSystem) – The spectral system to use.

Raises:

ValueError – If this is not a spatial-spectral image, or the system is not supported.

set_zoom_level(zoom, absolute=True)

Set the zoom level.

TODO: explain this more rigorously.

Parameters:

  • zoom (a number) – The zoom level.

  • absolute (a boolean) – Whether the zoom level should be treated as absolute. By default it is adjusted by a scaling factor.

property shape

The shape of the image. This value is transparently cached on the parent object.

Returns:

The shape of the image; dimensions ordered with width last.

Return type:

list of integers

property spectral_coordinate_types_supported

The spectral coordinate types supported by this image. This value is transparently cached on the parent object.

Returns:

The supported spectral coordinate types.

Return type:

set of carta.constants.SpectralType

property spectral_systems_supported

The spectral systems supported by this image. This value is transparently cached on the parent object.

Returns:

The supported spectral systems.

Return type:

set of carta.constants.SpectralSystem

property valid_wcs

Whether the image contains valid WCS information. This value is transparently cached on the parent object.

Returns:

Whether the image has WCS information.

Return type:

boolean

property width

The width of the image in pixels. This value is transparently cached on the parent object.

Returns:

The width.

Return type:

integer

zoom_to_size(size, axis)

Zoom to the given size along the specified axis.

Numbers are interpreted as pixel sizes. Numeric strings with no units are interpreted as arcseconds.

Parameters:

  • size (a number or a numeric string with valid size units) – The size to zoom to.

  • axis (a member of carta.constants.SpatialAxis) – The spatial axis to use.

Raises:

ValueError – If an angular size is provided and the image has no valid WCS information.

carta.metadata module

This module provides a collection of helper objects for storing and accessing file metadata.

carta.metadata.parse_header(raw_header)

Parse raw image header entries from the frontend into a more user-friendly format.

Entries with T or F string values are automatically converted to booleans.

HISTORY, COMMENT and blank keyword entries are aggregated into single entries with list values and with 'HISTORY', 'COMMENT' and '' as keys, respectively. An entry in the history list which begins with '>' will be concatenated with the previous entry.

Adjacent COMMENT entries are not concatenated automatically.

Any other header entries with no values are given values of None.

Parameters:

raw_header (dict) – The raw header entries received from the frontend.

Returns:

The header of the image, with field names as keys.

Return type:

dict of string to string, integer, float, boolean, None or list of strings

carta.preferences module

This module contains functionality for interacting with the CARTA UI preferences. The class in this module should not be instantiated directly. When a session object is created, a preferences object is automatically created as a property.

class carta.preferences.Preferences(session)

Bases: BasePathMixin

This class is a low-level interface to the CARTA UI preferences.

No validation is performed on any of the preference names or values passed as parameters to the functions in this class.

Parameters:

session (carta.session.Session) – The session object associated with this component.

Variables:

session (carta.session.Session) – The session object associated with this component.

get(name)

Get the value of a preference.

Parameters:

name (a string) – The name of the preference.

Returns:

The value of the preference.

Return type:

any value

set(name, value)

Set the value of a preference.

Parameters:

  • name (a string) – The name of the preference.

  • value (any value) – The new value for the preference.

carta.protocol module

This module provides classes and functions used to send HTTP requests to a backend or a controller.

class carta.protocol.AuthType

Bases: object

The type of authentication used to connect to the backend or controller.

BACKEND = 0
CONTROLLER = 1
NONE = 2
class carta.protocol.Protocol(frontend_url, token=None, debug_no_auth=False)

Bases: object

This object manages connections to a backend or controller instance, including any required authentication.

It should not be instantiated directly; it is created on demand when a carta.session.Session object is created using one of the convenience class methods provided.

Parameters:

  • frontend_url (string) – The URL of the frontend.

  • token (carta.token.Token, optional) – The security token used by the CARTA instance. May be omitted if the URL contains a token. If this is a controller token, it will be assumed to be a refresh token, and controller authentication will be enabled. If it’s a backend token, backend authentication will be enabled.

  • debug_no_auth (boolean) – Disable authentication. This should be set if the backend has been started with the --debug_no_auth option. This is provided for debugging purposes only and should not be used under normal circumstances.

Variables:
Raises:
ACTION_PATH = '/api/scripting/action'
REFRESH_TOKEN_PATH = '/api/auth/login'
SCRIPTING_TOKEN_PATH = '/api/auth/refresh'
property backend_auth

Is backend authentication enabled?

Returns:

Whether backend authentication is enabled.

Return type:

boolean

check_refresh_token()

Check whether the refresh token has expired.

Raises:

CartaBadToken – If the refresh token has expired.

property controller_auth

Is controller authentication enabled?

Returns:

Whether controller authentication is enabled.

Return type:

boolean

cookie()

The refresh token in the form of a cookie.

property domain

The domain extracted from the frontend URL.

Returns:

The domain.

Return type:

string

property no_auth

Is authentication disabled?

Returns:

Whether authentication is disabled.

Return type:

boolean

classmethod request_refresh_token(frontend_url, username, path=None)

Request a refresh token from a controller and optionally save it to a file.

This function must be run interactively. It securely prompts the user to enter a password.

Parameters:

  • frontend_url (string) – The URL of the frontend.

  • username (string) – The username to use to authenticate with the controller.

  • path (string, optional) – A path to a file where the refresh token should be saved.

Returns:

The token object created using the returned refresh token.

Return type:

carta.token.ControllerToken object

Raises:
request_scripting_action(session_id, path, *args, **kwargs)

Call an action on the frontend through the backend’s scripting interface.

Parameters:

  • path (string) – The full dot-separated path to a frontend action.

  • *args – A variable-length list of parameters to pass to the action. carta.util.Macro objects may be used to refer to frontend objects which will be evaluated dynamically. This parameter list will be serialized into a JSON string with carta.util.CartaEncoder.

  • **kwargs – Arbitrary keyword arguments. At present only three are used: async (boolean) is passed to indicate that the request should return a response as soon as the action is called, without waiting for the action to complete. response_expected (boolean) indicates that the action should return a JSON object. This is set automatically if return_path is set. return_path specifies a subobject of the action’s response which should be returned instead of the whole response. timeout (boolean) is the maximum time in seconds to wait for an action request to complete (the default is 10).

Returns:

If the action returns a JSON object, this method will return that response deserialized into a Python object.

Return type:

None or an object

Raises:
request_scripting_token()

Request a scripting token from the controller and cache it on this object.

Raises:

carta.raster module

This module contains functionality for interacting with the raster component of an image. The class in this module should not be instantiated directly. When an image object is created, a raster object is automatically created as a property.

class carta.raster.Raster(image)

Bases: BasePathMixin

Utility object for collecting image functions related to the raster component.

Parameters:

image (carta.image.Image object) – The image associated with this raster component.

Variables:
hide()

Hide the raster component.

set_bias_and_contrast(bias=None, contrast=None)

Set the raster bias and contrast.

Parameters:
set_clip(rank=None, min=None, max=None)

Set the raster clip options.

Parameters:

  • rank (a number greater than or equal to 0 and smaller than or equal to 100 or None) – The clip percentile rank. If this is set, min and max are ignored, and will be calculated automatically.

  • min (a number or None) – Custom clip minimum. Only used if both min and max are set. Ignored if rank is set.

  • max (a number or None) – Custom clip maximum. Only used if both min and max are set. Ignored if rank is set.

set_colormap(colormap, invert=False)

Set the raster colormap.

Parameters:

  • colormap (a member of carta.constants.Colormap) – The colormap.

  • invert (a boolean) – Whether the colormap should be inverted. This is false by default.

set_scaling(scaling=None, alpha=None, gamma=None)

Set the raster colormap scaling options.

Parameters:

  • scaling (a member of carta.constants.Scaling or None) – The scaling type.

  • alpha (a number greater than or equal to 0.1 and smaller than or equal to 1000000 or None) – The alpha value (only applicable to LOG and POWER scaling types, but set regardless of the scaling parameter provided).

  • gamma (a number greater than or equal to 0.1 and smaller than or equal to 2 or None) – The gamma value (only applicable to the GAMMA scaling type, but set regardless of the scaling parameter provided).

set_visible(state)

Set the raster component visibility.

Parameters:

state (a boolean) – The desired visibility state.

show()

Show the raster component.

class carta.raster.SessionRaster(session)

Bases: object

Utility object for collecting global raster image settings.

Parameters:

session (carta.session.Session object) – The session associated with these settings.

Variables:

session (carta.session.Session object) – The session associated with these settings.

hide_pixel_grid()

Hide the pixel grid.

property pixel_grid_color

The pixel grid color.

Returns:

The color.

Return type:

a member of carta.constants.color.PaletteColor

property pixel_grid_visible

Whether the pixel grid is visible.

Returns:

The visibility.

Return type:

boolean

set_pixel_grid(visible=None, color=None)

Set the pixel grid properties.

Parameters:

  • visible (a boolean or None) – Whether the pixel grid should be visible.

  • color (a member of carta.constants.PaletteColor or None) – The pixel grid color.

set_pixel_grid_color(color)

Set the color of the pixel grid.

Parameters:

color (a member of carta.constants.PaletteColor) – The color.

set_pixel_grid_visible(visible)

Set the visibility of the pixel grid.

Parameters:

visible (a boolean) – Whether the pixel grid should be visible.

show_pixel_grid()

Show the pixel grid.

carta.session module

This is the main module of the CARTA Python wrapper. It contains a session class which represents a CARTA frontend session.

The user can interact with an existing CARTA session open in their browser by creating a session object using the carta.session.Session.interact classmethod.

Alternatively, the user can create a new session which runs in a headless browser controlled by the wrapper. The user can connect to an existing CARTA backend instance (using the carta.session.Session.connect classmethod), or first start a new CARTA backend instance which is also controlled by the wrapper (using the carta.session.Session.new classmethod). The backend can be started either on the local host or on a remote host which the user can access with passwordless SSH.

class carta.session.Session(session_id, protocol, browser=None, backend=None)

Bases: object

This object corresponds to a CARTA frontend session.

This class provides the core generic method for calling actions on the frontend (through the backend), as well as convenience methods which wrap this generic method and provide a more intuitive and user-friendly interface to frontend functionality associated with the session as a whole.

This class should not be instantiated directly. Four class methods are provided for creating different types of sessions with all the appropriate parameters set:

The session object can be used to create image objects, which provide analogous convenience methods for functionality associated with individual images.

Parameters:
Variables:
active_frame()

Return the currently active image.

Returns:

The currently active image.

Return type:

carta.image.Image

call_action(path, *args, **kwargs)

Call an action on the frontend through the backend’s scripting interface.

This method is the core of the session class, and provides a generic interface for calling any action on the frontend. This is exposed as a public method to give developers the option of writing experimental functionality; wherever possible script writers should instead use the more user-friendly methods on the session and image objects which wrap this method.

Parameters:

  • path (string) – The full dot-separated path to a frontend action.

  • *args – A variable-length list of parameters to pass to the action. carta.util.Macro objects may be used to refer to frontend objects which will be evaluated dynamically. This parameter list will be serialized into a JSON string with carta.util.CartaEncoder.

  • **kwargs – Arbitrary keyword arguments. At present only three are used: async (boolean) is passed to indicate that the request should return a response as soon as the action is called, without waiting for the action to complete. response_expected (boolean) indicates that the action should return a JSON object. This is set automatically if return_path is set. return_path specifies a subobject of the action’s response which should be returned instead of the whole response. timeout (boolean) is the maximum time in seconds to wait for an action request to complete (the default is 10).

Returns:

If the action returns a JSON object, this method will return that response deserialized into a Python object.

Return type:

None or an object

Raises:
cd(path)

Change the current directory.

This function changes the frontend file browser’s starting directory.

Parameters:

path (string) – The path to the new directory, which may be relative to the current directory or absolute (relative to the CARTA backend root).

clear_raster_scaling_reference()

Clear the raster scaling reference.

clear_spatial_reference()

Clear the spatial reference.

clear_spectral_reference()

Clear the spectral reference.

close()

Close any browser sessions and backend processes controlled by this session object.

If this session opened a CARTA frontend session in a headless browser, this method will close the browser together with that session. If this session is interacting with a session running in an external browser, that browser session will be unaffected. This includes the new CARTA frontend session which is started automatically when carta.session.Session.start_and_interact is used: that frontend session is opened in the user’s browser, which is not controlled by this object.

If this session started a new backend process, this method will stop that process. If this session is interacting with an externally started backend process, that process will be unaffected.

classmethod create(browser, frontend_url, token=None, timeout=10, debug_no_auth=False)

Connect to an existing CARTA backend or CARTA controller instance and create a new session.

Parameters:

  • browser (carta.browser.Browser) – The browser to use to open the frontend.

  • frontend_url (string) – The frontend URL of the CARTA instance.

  • token (carta.token.Token, optional) – The security token used by the CARTA instance. You may omit this if the URL contains a token.

  • timeout (integer, optional) – The number of seconds to spend retrying parsing connection information from the frontend (default: 10).

  • debug_no_auth (boolean, optional) – Disable authentication. Set this if the backend has been started with the --debug_no_auth option. This is provided for debugging purposes only and should not be used under normal circumstances.

Returns:

A session object connected to a new frontend session running in the browser provided.

Return type:

carta.session.Session

Raises:
get_value(path, return_path=None)

Get the value of an attribute from a frontend store.

Like the carta.session.Session.call_action method, this is exposed in the public API but is not intended to be used directly under normal circumstances.

Parameters:

  • path (string) – The full path to the attribute.

  • return_path (string, optional) – Specifies a subobject of the attribute value which should be returned instead of the whole object.

Returns:

The value of the attribute, deserialized from a JSON string.

Return type:

object

image_by_id(image_id)

Return an image object with the specified ID.

This is a helper function which constructs a carta.image.Image object with the specified ID, without checking whether an image with that ID is currently open. It is the caller’s responsibility to ensure this.

Parameters:

image_id (integer) – The ID of the image to return.

Returns:

The image with the specified ID.

Return type:

carta.image.Image

image_list()

Return the list of currently open images.

Returns:

The list of images open in this session.

Return type:

list of carta.image.Image objects

classmethod interact(frontend_url, session_id, token=None, debug_no_auth=False, backend=None)

Interact with an existing CARTA frontend session.

Parameters:

  • frontend_url (string) – The frontend URL of the CARTA instance.

  • session_id (integer) – The ID of an existing CARTA frontend session. You may supply this as a string of digits; it will be converted to an integer automatically.

  • token (carta.token.Token, optional) – The security token used by the CARTA instance. You may omit this if the URL contains a token.

  • debug_no_auth (boolean, optional) – Disable authentication. Set this if the backend has been started with the --debug_no_auth option. This is provided for debugging purposes only and should not be used under normal circumstances.

  • backend (carta.backend.Backend) – The backend object associated with this session, if any. This is set if this method is called from carta.session.Session.start_and_interact.

Returns:

A session object associated with the frontend session provided.

Return type:

carta.session.Session

Raises:
ls()

The current directory listing.

Returns:

The list of files and subdirectories in the frontend file browser’s current starting directory.

Return type:

list

next_page()

Go to next page in viewer.

open_LEL_image(expression, directory='.', append=False, make_active=True, update_directory=False)

Open or append a new image via the Lattice Expression Language (LEL) interface.

Parameters:

  • expression (a string) – The LEL arithmetic expression.

  • directory (a string) – The base directory for the LEL expression, either relative to the session’s current directory or an absolute path relative to the CARTA backend’s root directory. Defaults to the session’s current directory.

  • append (a boolean) – Whether the image should be appended to existing images. By default this is False and any existing open images are closed.

  • make_active (a boolean) – Whether the image should be made active in the frontend. This only applies if an image is being appended. The default is True.

  • update_directory (a boolean) – Whether the starting directory of the frontend file browser should be updated to the base directory of the LEL expression. The default is False.

Returns:

The opened image.

Return type:

carta.image.Image

open_complex_image(path, component=ComplexComponent.AMPLITUDE, append=False, make_active=True, update_directory=False)

Open or append a new complex-valued image.

Parameters:

  • path (a string) – The path to the complex-valued image file, either relative to the session’s current directory or an absolute path relative to the CARTA backend’s root directory.

  • component (a member of carta.constants.ComplexComponent) – The complex component to select when opening the image. The default is carta.constants.ComplexComponent.AMPLITUDE.

  • append (a boolean) – Whether the image should be appended to existing images. By default this is False and any existing open images are closed.

  • make_active (a boolean) – Whether the image should be made active in the frontend. This only applies if an image is being appended. The default is True.

  • update_directory (a boolean) – Whether the starting directory of the frontend file browser should be updated to the parent directory of the image. The default is False.

Returns:

The opened image.

Return type:

carta.image.Image

open_hypercube(image_paths, append=False)

Open multiple images merged into a polarization hypercube.

Parameters:

  • image_paths (an iterable with at least 2 elements in which each element is a string or a dictionary with at least 2 elements in which each key is a member of carta.constants.Polarization and each value is a string) – The image paths, either relative to the session’s current directory or absolute paths relative to the CARTA backend’s root directory. If this is a list of paths, the polarizations will be deduced from the image headers or names. If this is a dictionary, the polarizations must be used as keys.

  • append (a boolean) – Whether the hypercube should be appended to existing images. By default this is False and any existing open images are closed.

Returns:

The opened hypercube.

Return type:

carta.image.Image

Raises:

ValueError – If explicit polarizations are not provided, and cannot be deduced from the image headers or names.

open_image(path, hdu='', append=False, make_active=True, update_directory=False)

Open or append a new image.

Parameters:

  • path (a string) – The path to the image file, either relative to the session’s current directory or an absolute path relative to the CARTA backend’s root directory.

  • hdu (a string matching \d*) – The HDU to select inside the file.

  • append (a boolean) – Whether the image should be appended to existing images. By default this is False and any existing open images are closed.

  • make_active (a boolean) – Whether the image should be made active in the frontend. This only applies if an image is being appended. The default is True.

  • update_directory (a boolean) – Whether the starting directory of the frontend file browser should be updated to the parent directory of the image. The default is False.

Returns:

The opened image.

Return type:

carta.image.Image

open_images(image_paths, append=False)

Open multiple images

This is a utility function for adding multiple images in a single command. It assumes that the images are not complex-valued or LEL expressions, and that the default HDU can be used for each image. For more complicated use cases, the methods for opening individual images should be used.

Parameters:

  • image_paths (an iterable in which each element is a string) – The image paths, either relative to the session’s current directory or absolute paths relative to the CARTA backend’s root directory.

  • append (a boolean) – Whether the images should be appended to existing images. By default this is False and any existing open images are closed.

Returns:

The list of opened images.

Return type:

list of carta.image.Image objects

previous_page()

Go to previous page in viewer.

pwd()

The current directory.

This is the frontend file browser’s currently saved starting directory. Whenever an image file is opened with the frontend’s file browser (which may happen if the wrapper is connected to an interactive session), this directory is changed to the file’s parent directory. By default, this directory is not changed if an image is opened through the wrapper (which bypasses the file browser).

Returns:

The session’s current directory.

Return type:

string

rendered_view_data(background_color=None)

Get the decoded data of the rendered active image.

Parameters:

background_color (an HTML color specification or None) – The background color. By default the background will be transparent.

Returns:

The decoded PNG image data.

Return type:

bytes

rendered_view_url(background_color=None)

Get a data URL of the rendered active image.

Parameters:

background_color (an HTML color specification or None) – The background color. By default the background will be transparent.

Returns:

A data URL for the rendered image in PNG format, base64-encoded.

Return type:

string

resolve_file_path(path)

Convert a file path to an absolute path.

This function prepends the session’s current directory to a relative path, and normalizes the path to remove redundant separators and references.

Parameters:

path (string) – The file path, which may be absolute or relative to the current directory.

Returns:

The absolute file path, relative to the CARTA backend’s root.

Return type:

string

save_rendered_view(file_name, background_color=None)

Save the decoded data of the rendered active image to a file.

Parameters:

  • file_name (a string) – The name of the file.

  • background_color (an HTML color specification or None) – The background color. By default the background will be transparent.

set_cursor(x, y)

Set the curson position.

TODO: this is a precursor to making z-profiles available, but currently the relevant functionality is not exposed by the frontend.

Parameters:

  • x (a number) – The X position.

  • y (a number) – The Y position.

set_viewer_grid(rows, columns, grid_mode=GridMode.FIXED)

Set number of columns and rows in viewer grid.

Parameters:

  • rows (a number greater than or equal to 1 and smaller than or equal to 10 , in increments of 1) – Number of rows.

  • columns (a number greater than or equal to 1 and smaller than or equal to 10 , in increments of 1) – Number of columns.

  • grid_mode (a member of carta.constants.GridMode) – The grid mode to adopt. The default is carta.constants.GridMode.FIXED.

set_viewer_mode(panel_mode)

Switch between single-panel mode and multiple-panel mode.

Parameters:

panel_mode (a member of carta.constants.PanelMode) – The panel mode to adopt.

classmethod start_and_create(browser, executable_path='carta', remote_host=None, params=(), timeout=10, token=None, frontend_url_timeout=10)

Start a new CARTA backend instance and create a new session. This method cannot be used with a CARTA controller instance (which already starts and stops backend instances for the user on demand).

Parameters:

  • browser (carta.browser.Browser) – The browser to use to open the frontend.

  • executable_path (string, optional) – A custom path to the CARTA backend executable. The default is "carta".

  • remote_host (string, optional) – A remote host where the backend process should be launched, which must be accessible through passwordless ssh. By default the backend process is launched on the local host.

  • params (iterable, optional) – Additional parameters to be passed to the backend process. By default scripting is enabled and the automatic browser is disabled. The parameters are appended to the end of the command, so a positional parameter for a data directory can be included. Example: ["--verbosity", 5, "--port", 3010]

  • timeout (integer, optional) – The number of seconds to spend parsing the frontend for connection information. 10 seconds by default.

  • token (carta.token.Token, optional) – The security token to use. Parsed from the backend output by default.

  • frontend_url_timeout (integer) – How long to keep checking the backend output for the frontend URL. Default: 10 seconds.

Returns:

A session object connected to a new frontend session running in the browser provided.

Return type:

carta.session.Session

Raises:
classmethod start_and_interact(executable_path='carta', remote_host=None, params=(), token=None, frontend_url_timeout=10, session_creation_timeout=10)

Start a new CARTA backend instance and interact with the default CARTA frontend session which is created automatically in the user’s browser. This method cannot be used with a CARTA controller instance.

Parameters:

  • executable_path (string, optional) – A custom path to the CARTA backend executable. The default is "carta".

  • remote_host (string, optional) – A remote host where the backend process should be launched, which must be accessible through passwordless ssh. By default the backend process is launched on the local host.

  • params (iterable, optional) – Additional parameters to be passed to the backend process. By default scripting is enabled. The parameters are appended to the end of the command, so a positional parameter for a data directory can be included. Example: ["--verbosity", 5, "--port", 3010]

  • token (carta.token.Token, optional) – The security token to use. Parsed from the backend output by default.

  • frontend_url_timeout (integer) – How long to keep checking the backend output for the frontend URL. Default: 10 seconds.

  • session_creation_timeout (integer) – How long to keep checking the output for a default session ID. Default: 10 seconds.

Returns:

A session object associated with the frontend session provided.

Return type:

carta.session.Session

Raises:

  • CartaBadID – If a valid ID cannot be obtained from the backend process output.

  • CartaBadToken – If a valid token cannot be obtained from the backend process output, or the provided token is invalid.

  • CartaBadUrl – If a valid URL cannot be obtained from the backend process output.

  • CartaBadSession – If the session object could not be created.

carta.token module

This module provides classes and functions for managing backend and controller tokens.

class carta.token.BackendToken(string)

Bases: Token

An object representing a security token used by the backend. These tokens are strings with no additional meaning, and may be generated automatically or overridden by the user with a fixed value.

Parameters:

string (string) – The token string.

static split_token_from_url(url)

Extract a backend token from a frontend URL.

Parameters:

url (string) – The URL of the frontend.

Returns:

  • string – The URL with the backend token removed.

  • carta.token.BackendToken object or None – The object representing the backend token.

Raises:

CartaBadUrl – If an invalid URL was provided.

class carta.token.ControllerToken(string)

Bases: Token

An object representing a security token used by the controller. These tokens are JWTs (JSON Web Tokens) which encode additional information such as an expiration date. The controller uses multiple types of tokens. This interface makes use of long-lived refresh tokens (used to log into the controller and to obtain scripting tokens) and short-lived scripting tokens (used to make scripting requests).

Parameters:

string (string) – The token string.

Create a cookie from this refresh token.

Parameters:

domain (string) – The domain to use in the cookie.

Returns:

The cookie as a dictionary of string keys and values.

Return type:

dict

Raises:

CartaBadToken – If the token string is not a valid JWT or if this is not a refresh token.

property expires

The expiration date of this token.

Returns:

The expiration date.

Return type:

datetime.datetime object

Raises:

CartaBadToken – If the token string is not a vaild JWT.

classmethod from_file(path)

Load a controller token from a file.

Parameters:

path (string) – The path to the file.

Returns:

The controller token.

Return type:

carta.token.ControllerToken

property refresh

Is this a refresh token?

Returns:

Whether this is a refresh token.

Return type:

boolean

Raises:

CartaBadToken – If the token string is not a vaild JWT.

save(path)

Save this token to a file.

Parameters:

path (string) – The path to the file where the token should be saved.

property scripting

Is this a scripting token?

Returns:

Whether this is a scripting token.

Return type:

boolean

Raises:

CartaBadToken – If the token string is not a vaild JWT.

property username

The username encoded in this token.

Returns:

The username.

Return type:

string

Raises:

CartaBadToken – If the token string is not a vaild JWT.

valid()

Is this token valid?

Returns:

Whether this token is valid.

Return type:

boolean

Raises:

CartaBadToken – If the token string is not a vaild JWT.

class carta.token.Token(string)

Bases: object

The parent token class. This should not be instantiated directly.

Parameters:

string (string) – The token string.

Variables:

string (string) – The token string.

carta.units module

This module provides helper objects for unit conversion.

class carta.units.AngularSize(value)

Bases: object

An angular size.

This class provides methods for parsing angular sizes with any known unit, and should not be instantiated directly. Child classes can be used directly if the unit is known.

Child class instances have a string representation in a normalized format which can be parsed by the frontend.

FORMATS = {'': <class 'carta.units.ArcsecSize'>, '"': <class 'carta.units.ArcsecSize'>, "'": <class 'carta.units.ArcminSize'>, 'amin': <class 'carta.units.ArcminSize'>, 'arcmin': <class 'carta.units.ArcminSize'>, 'arcminute': <class 'carta.units.ArcminSize'>, 'arcminutes': <class 'carta.units.ArcminSize'>, 'arcsec': <class 'carta.units.ArcsecSize'>, 'arcsecond': <class 'carta.units.ArcsecSize'>, 'arcseconds': <class 'carta.units.ArcsecSize'>, 'asec': <class 'carta.units.ArcsecSize'>, 'deg': <class 'carta.units.DegreesSize'>, 'degree': <class 'carta.units.DegreesSize'>, 'degrees': <class 'carta.units.DegreesSize'>, 'mas': <class 'carta.units.MilliarcsecSize'>, 'microarcsec': <class 'carta.units.MicroarcsecSize'>, 'microarcsecond': <class 'carta.units.MicroarcsecSize'>, 'microarcseconds': <class 'carta.units.MicroarcsecSize'>, 'milliarcsec': <class 'carta.units.MilliarcsecSize'>, 'milliarcsecond': <class 'carta.units.MilliarcsecSize'>, 'milliarcseconds': <class 'carta.units.MilliarcsecSize'>, 'uas': <class 'carta.units.MicroarcsecSize'>, 'µas': <class 'carta.units.MicroarcsecSize'>, '′': <class 'carta.units.ArcminSize'>, '″': <class 'carta.units.ArcsecSize'>}
NAME = 'angular size'
SYMBOL_UNIT_REGEX = '^(\\d+(?:\\.\\d+)?)(|"|′|″|\')$'
WORD_UNIT_REGEX = '^(\\d+(?:\\.\\d+)?)\\s*(arcminute|microarcsecond|milliarcseconds|degree|µas|degrees|arcsec|arcsecond|deg|arcmin|arcminutes|mas|uas|amin|microarcseconds|microarcsec|milliarcsec|arcseconds|asec|milliarcsecond)$'
classmethod from_string(value)

Construct an angular size object from a string.

A number without a unit is assumed to be in arcseconds. Permitted unit strings and their mappings to normalized units are stored in subclasses of carta.util.AngularSize. Whitespace is permitted after the number and before a unit which is a word, but not before a single-character unit.

This method may also be used from child classes if a specific format is required.

Parameters:

value (string) – The string representation of the angular size.

Returns:

The angular size object.

Return type:

carta.util.AngularSize

Raises:

ValueError – If the angular size string is not in a recognized format.

classmethod valid(value)

Whether the input string is a numeric value followed by an angular size unit.

A number without a unit is assumed to be in arcseconds. Permitted unit strings and their mappings to normalized units are stored in subclasses of carta.util.AngularSize. Whitespace is permitted after the number and before a unit which is a word, but not before a single-character unit.

This method may also be used from child classes if a specific format is required.

Parameters:

value (string) – The input string.

Returns:

Whether the input string is an angular size.

Return type:

boolean

class carta.units.ArcminSize(value)

Bases: AngularSize

An angular size in arcminutes.

FACTOR = 1
INPUT_UNITS = {"'", 'amin', 'arcmin', 'arcminute', 'arcminutes', '′'}
NAME = 'arcminute'
OUTPUT_UNIT = "'"
SYMBOL_UNIT_REGEX = "^(\\d+(?:\\.\\d+)?)(′|')$"
WORD_UNIT_REGEX = '^(\\d+(?:\\.\\d+)?)\\s*(amin|arcminute|arcmin|arcminutes)$'
class carta.units.ArcsecSize(value)

Bases: AngularSize

An angular size in arcseconds.

FACTOR = 1
INPUT_UNITS = {'', '"', 'arcsec', 'arcsecond', 'arcseconds', 'asec', '″'}
NAME = 'arcsecond'
OUTPUT_UNIT = '"'
SYMBOL_UNIT_REGEX = '^(\\d+(?:\\.\\d+)?)(|"|″)$'
WORD_UNIT_REGEX = '^(\\d+(?:\\.\\d+)?)\\s*(arcseconds|arcsec|arcsecond|asec)$'
class carta.units.DMSCoordinate(hours_or_degrees, minutes, seconds)

Bases: SexagesimalCoordinate

A world coordinate in DMS format.

FMT = 'dms'
REGEX = {'COLON': '^(-?\\d+)?:([0-5]?\\d)?:([0-5]?\\d(?:\\.\\d+)?)?$', 'LETTER': '^(?:(-?\\d+)d)?(?:([0-5]?\\d)m)?(?:([0-5]?\\d(?:\\.\\d+)?)s)?$'}
classmethod from_string(value, axis)

Construct a world coordinate object in DMS format from a string.

Coordinates may be provided in DMS format with colons or letters as separators. The value range will be validated for the provided spatial axis.

Parameters:
Returns:

The coordinate object.

Return type:

carta.util.DMSCoordinate

class carta.units.DegreesCoordinate(degrees)

Bases: WorldCoordinate

A world coordinate in decimal degree format.

DEGREE_UNITS = {'deg', 'degree', 'degrees'}
FMT = 'd'
REGEX = {'DECIMAL': '^-?\\d+(\\.\\d+)?$', 'DEGREE_UNIT': '^-?(\\d+(?:\\.\\d+)?)\\s*(degrees|deg|degree)$'}
classmethod from_string(value, axis)

Construct a world coordinate object in decimal degree format from a string.

Coordinates may be provided with or without an explicit unit. Permitted degree unit strings are stored in carta.util.DegreesCoordinate.DEGREE_UNITS.

Parameters:
Returns:

The coordinate object.

Return type:

carta.util.DegreesCoordinate

class carta.units.DegreesSize(value)

Bases: AngularSize

An angular size in degrees.

FACTOR = 1
INPUT_UNITS = {'deg', 'degree', 'degrees'}
NAME = 'degree'
OUTPUT_UNIT = 'deg'
SYMBOL_UNIT_REGEX = '^(\\d+(?:\\.\\d+)?)()$'
WORD_UNIT_REGEX = '^(\\d+(?:\\.\\d+)?)\\s*(degrees|deg|degree)$'
class carta.units.HMSCoordinate(hours_or_degrees, minutes, seconds)

Bases: SexagesimalCoordinate

A world coordinate in HMS format.

FMT = 'hms'
REGEX = {'COLON': '^(-?(?:\\d|[01]\\d|2[0-3]))?:([0-5]?\\d)?:([0-5]?\\d(?:\\.\\d+)?)?$', 'LETTER': '^(?:(-?(?:\\d|[01]\\d|2[0-3]))h)?(?:([0-5]?\\d)m)?(?:([0-5]?\\d(?:\\.\\d+)?)s)?$'}
classmethod from_string(value, axis)

Construct a world coordinate object in HMS format from a string.

Coordinates may be provided in HMS format with colons or letters as separators. The value range will be validated for the provided spatial axis.

Parameters:
Returns:

The coordinate object.

Return type:

carta.util.HMSCoordinate

class carta.units.MicroarcsecSize(value)

Bases: AngularSize

An angular size in microarcseconds.

FACTOR = 1e-06
INPUT_UNITS = {'microarcsec', 'microarcsecond', 'microarcseconds', 'uas', 'µas'}
NAME = 'microarcsecond'
OUTPUT_UNIT = '"'
SYMBOL_UNIT_REGEX = '^(\\d+(?:\\.\\d+)?)()$'
WORD_UNIT_REGEX = '^(\\d+(?:\\.\\d+)?)\\s*(microarcseconds|microarcsec|microarcsecond|µas|uas)$'
class carta.units.MilliarcsecSize(value)

Bases: AngularSize

An angular size in milliarcseconds.

FACTOR = 0.001
INPUT_UNITS = {'mas', 'milliarcsec', 'milliarcsecond', 'milliarcseconds'}
NAME = 'milliarcsecond'
OUTPUT_UNIT = '"'
SYMBOL_UNIT_REGEX = '^(\\d+(?:\\.\\d+)?)()$'
WORD_UNIT_REGEX = '^(\\d+(?:\\.\\d+)?)\\s*(milliarcseconds|milliarcsec|mas|milliarcsecond)$'
class carta.units.SexagesimalCoordinate(hours_or_degrees, minutes, seconds)

Bases: WorldCoordinate

A world coordinate in sexagesimal format.

This class contains common functionality for parsing the HMS and DMS formats.

as_tuple()

The tuple representation of this coordinate.

classmethod from_string(value, axis)

Construct a world coordinate object in sexagesimal format from a string.

Coordinates may be provided in HMS or DMS format with colons or letters as separators. The value range will be validated for the provided spatial axis.

Parameters:
Returns:

The coordinate object.

Return type:

carta.util.SexagesimalCoordinate

class carta.units.WorldCoordinate

Bases: object

A world coordinate.

FMT = None
FORMATS = {NumberFormat.DEGREES: <class 'carta.units.DegreesCoordinate'>, NumberFormat.DMS: <class 'carta.units.DMSCoordinate'>, NumberFormat.HMS: <class 'carta.units.HMSCoordinate'>}
classmethod from_string(value, axis)

Construct a world coordinate object from a string.

This is implemented in subclasses corresponding to different formats.

Parameters:
Returns:

The coordinate object.

Return type:

carta.util.WorldCoordinate

classmethod valid(value)

Whether the input string is a world coordinate string in any of the recognised formats.

Coordinates may be provided in HMS or DMS format (with colons or letters as separators), or in degrees (with or without an explicit unit). Permitted degree unit strings are stored in carta.util.DegreesCoordinate.DEGREE_UNITS.

Parameters:

value (string) – The input string.

Returns:

Whether the input string is a valid world coordinate.

Return type:

boolean

classmethod with_format(fmt)

Return the subclass of carta.util.WorldCoordinate corresponding to the specified format.

carta.util module

This module provides miscellaneous utility classes and functions used by the wrapper.

class carta.util.BasePathMixin

Bases: object

A mixin which provides call_action and get_value methods which prepend the object’s base path to the path before calling the corresponding carta.session.Session methods.

It also provides a macro method which prepends the path when creating a carta.util.Macro.

A class inheriting from this mixin must define a _base_path attribute (the string prefix) and a session attribute (a carta.session.Session object).

call_action(path, *args, **kwargs)

Convenience wrapper for the session object’s generic action method.

This method calls carta.session.Session.call_action after prepending this object’s base path to the path parameter.

Parameters:

  • path (string) – The path to an action relative to this object’s store.

  • *args – A variable-length list of parameters. These are passed unmodified to the session method.

  • **kwargs – Arbitrary keyword parameters. These are passed unmodified to the session method.

Returns:

The unmodified return value of the session method.

Return type:

object or None

get_value(path, return_path=None)

Convenience wrapper for the session object’s generic method for retrieving attribute values.

This method calls carta.session.Session.get_value after prepending this object’s base path to the path parameter.

Parameters:

  • path (string) – The path to an attribute relative to this object’s store.

  • return_path (string, optional) – Specifies a subobject of the attribute value which should be returned instead of the whole object.

Returns:

The unmodified return value of the session method.

Return type:

object

macro(target, variable)

Convenience wrapper for creating a carta.util.Macro for an object property.

This method prepends this object’s base path to the target parameter. If target is the empty string, the base path will be substituted.

Parameters:

  • target (str) – The target frontend object.

  • variable (str) – The variable on the target object.

Returns:

A placeholder for a variable which will be evaluated dynamically by the frontend.

Return type:

obj:carta.util.Macro

exception carta.util.CartaActionFailed

Bases: CartaScriptingException

An action request received a failure response from the CARTA frontend.

exception carta.util.CartaBadID

Bases: CartaScriptingException

A session ID is invalid.

exception carta.util.CartaBadRequest

Bases: CartaScriptingException

A request sent to the CARTA backend was rejected.

exception carta.util.CartaBadResponse

Bases: CartaScriptingException

An action request received an unexpected response from the CARTA frontend.

exception carta.util.CartaBadSession

Bases: CartaScriptingException

A session could not be constructed.

exception carta.util.CartaBadToken

Bases: CartaScriptingException

A token has expired or is invalid.

exception carta.util.CartaBadUrl

Bases: CartaScriptingException

An URL is invalid.

class carta.util.CartaEncoder(*, skipkeys=False, ensure_ascii=True, check_circular=True, allow_nan=True, sort_keys=False, indent=None, separators=None, default=None)

Bases: JSONEncoder

A custom encoder to JSON which correctly serialises custom objects with a json method, and numpy arrays.

default(obj)

This method is overridden from the parent class and performs the substitution.

exception carta.util.CartaRequestFailed

Bases: CartaScriptingException

A request received a failure response from the CARTA backend.

exception carta.util.CartaScriptingException

Bases: Exception

The top-level exception for all scripting errors.

exception carta.util.CartaValidationFailed

Bases: CartaScriptingException

Invalid parameters were passed to a function with a carta.validation.validate decorator.

class carta.util.Macro(target, variable)

Bases: object

A placeholder for a target and a variable which will be evaluated dynamically by the frontend.

Parameters:

  • target (str) – The target frontend object.

  • variable (str) – The variable on the target object.

Variables:

  • target (str) – The target frontend object.

  • variable (str) – The variable on the target object.

UNDEFINED = Macro('', 'undefined')
json()

The JSON serialization of this object.

carta.util.cached(func)

A decorator which transparently caches the return value of the decorated method on the parent object.

This should only be used on methods with return values which are not expected to change for the lifetime of the object.

carta.util.camel(*parts)

Convert an iterable of strings to a camel case string.

carta.util.snake(*parts)

Convert an iterable of strings to a snake case string.

carta.util.split_action_path(path)

Extracts a path to a frontend object store and an action from a combined path.

carta.validation module

This module provides a collection of descriptors of the permitted types and values of parameters passed to carta.session.Session and carta.image.Image methods. They are associated with methods through a decorator which performs the validation at runtime and also injects parameter descriptions into the methods’ docstrings.

class carta.validation.Any

Bases: Parameter

Any value. This class is used to skip validation for a specific parameter.

property description

A human-readable description of this parameter descriptor.

Returns:

The description.

Return type:

string

validate(value, parent)

Always pass.

See carta.validation.Parameter.validate for general information about this method.

class carta.validation.Attr

Bases: str

A wrapper for arguments to be passed to the carta.validation.Evaluate descriptor. These arguments are string names of properties on the parent object of the decorated method, which will be evaluated at runtime.

class carta.validation.Attrs

Bases: str

A wrapper for arguments to be passed to the carta.validation.Evaluate descriptor. These arguments are string names of properties on the parent object of the decorated method, which will be evaluated at runtime. Unlike carta.validation.Attr, the wrapped property is assumed to be an iterable which should be unpacked.

class carta.validation.Boolean

Bases: Parameter

A boolean parameter.

property description

A human-readable description of this parameter descriptor.

Returns:

The description.

Return type:

string

validate(value, parent)

Check if the value is boolean. It may be expressed as a numeric 1 or 0 value.

See carta.validation.Parameter.validate for general information about this method.

class carta.validation.Color

Bases: Union

Any valid HTML color specification: a 3- or 6-digit hex triplet, an RBG(A) or HSL(A) tuple, or one of the 147 named colors.

class carta.validation.Constant(clazz, exclude=())

Bases: OneOf

A parameter which must be a member of the given enum class. For consistency and compatibility, a parameter will be accepted if it evaluates as equal to a member of the enum. Intended for use with the string and integer constants defined in carta.constants.

Parameters:

  • clazz (enum class) – The parameter must be a member of this enum class or have the same value as a member of this enum class.

  • exclude (iterable, optional) – An iterable of members to exclude.

Variables:

  • options (iterable) – An iterable of the permitted options.

  • clazz (enum class) – The parameter must be a member of this enum class or have the same value as a member of this enum class.

  • exclude (iterable) – An iterable of members which are excluded.

property description

A human-readable description of this parameter descriptor.

Returns:

The description.

Return type:

string

class carta.validation.Coordinate

Bases: Union

A representation of a world coordinate or image coordinate. Can be a number, a string in H:M:S or D:M:S format, or a numeric string with degree units. A number is assumed to be a pixel value. Validates strings using carta.util.WorldCoordinate.

class WorldCoordinate(regex=None, flags=0)

Bases: String

Helper validator class which uses carta.util.WorldCoordinate to validate strings.

validate(value, parent)

Check if the value can be parsed as a world coordinate.

See carta.validation.Parameter.validate for general information about this method.

class carta.validation.Evaluate(paramclass, *args, **kwargs)

Bases: Parameter

A descriptor which is constructed at runtime using properties of the parent object of the decorated method.

Parameters:

  • paramclass (a carta.validation.Parameter class) – The class of the parameter descriptor to construct.

  • *args (iterable) – Positional arguments to pass to the constructor; either literals or carta.validation.Attr objects which will be evaluated from properties on the parent object at runtime.

  • **kwargs (iterable) – Keyword arguments to pass to the constructor; either literals or carta.validation.Attr objects which will be evaluated from properties on the parent object at runtime.

Variables:

  • paramclass (a carta.validation.Parameter class) – The class of the parameter descriptor to construct.

  • args (iterable) – Positional arguments to pass to the constructor.

  • kwargs (iterable) – Keyword arguments to pass to the constructor.

property description

A human-readable description of this parameter descriptor.

Returns:

The description.

Return type:

string

validate(value, parent)

Validate the value after constructing the parameter descriptor object.

See carta.validation.Parameter.validate for general information about this method.

class carta.validation.InstanceOf(types)

Bases: Parameter

A parameter which is an instance of the provided type or tuple of types.

This validator uses isinstance, and has the same behaviour. An instance of a child class is also an instance of a parent class.

Parameters:

types (type or tuple of types)

property description

A human-readable description of this parameter descriptor.

Returns:

The description.

Return type:

string

validate(value, parent)

Check if the value is an instance of the provided type or types.

See carta.validation.Parameter.validate for general information about this method.

class carta.validation.IterableOf(param, min_size=None, max_size=None)

Bases: Parameter

An iterable of values which must match the given descriptor.

Parameters:

  • param (carta.validation.Parameter) – The parameter descriptor.

  • min_size (integer, optional) – The minimum size.

  • max_size (integer, optional) – The maximum size.

Variables:

  • param (carta.validation.Parameter) – The parameter descriptor.

  • min_size (integer, optional) – The minimum size.

  • max_size (integer, optional) – The maximum size.

property description

A human-readable description of this parameter descriptor.

Returns:

The description.

Return type:

string

validate(value, parent)

Check if each element of the iterable can be validated with the given descriptor.

See carta.validation.Parameter.validate for general information about this method.

class carta.validation.MapOf(key_param, value_param, min_size=None, max_size=None)

Bases: IterableOf

A dictionary of keys and values which must match the given descriptors.

Parameters:

value_param (carta.validation.Parameter) – The value parameter descriptor.

Variables:

value_param (carta.validation.Parameter) – The value parameter descriptor.

property description

A human-readable description of this parameter descriptor.

Returns:

The description.

Return type:

string

validate(value, parent)

Check if each element of the iterable can be validated with the given descriptor.

See carta.validation.Parameter.validate for general information about this method.

class carta.validation.NoneOr(*options, description=None)

Bases: Union

A union of other parameter descriptors as well as None.

In the most common use case, this is used with a single other parameter type for optional parameters which are None by default. In more complex cases this can be used as shorthand in place of a carta.validation.Union with an explicit carta.validation.NoneParameter option. Also see carta.validation.all_optional for a less verbose way to specify multiple sequential optional parameters.

Parameters:

  • *options (iterable of carta.validation.Parameter objects) – An iterable of valid descriptors for this parameter, in addition to None.

  • description (str, optional) – A custom description. The default is generated from the descriptions of the provided options.

Variables:

options (iterable of carta.validation.Parameter objects) – An iterable of valid descriptors for this parameter, in addition to None.

class carta.validation.NoneParameter

Bases: Parameter

A parameter which must be None. This is not intended to be used directly; it is used together with carta.validation.Union for optional parameters with a default value of None.

property description

A human-readable description of this parameter descriptor.

Returns:

The description.

Return type:

string

validate(value, parent)

Check if the value is None.

See carta.validation.Parameter.validate for general information about this method.

class carta.validation.Number(min=None, max=None, interval=3, step=None, offset=None)

Bases: Parameter

An integer or floating point scalar numeric parameter.

Parameters:

  • min (number, optional) – The lower bound.

  • max (number, optional) – The upper bound.

  • interval (int) – A bitmask which describes whether the bounds are included or excluded. The constant attributes defined on this class should be used. By default both bounds are included.

  • step (number, optional) – A step size to which the value must conform. May be a fractional value. If this is unset, any value within the range is permitted.

  • offset (number, optional) – A step offset. Ignored if a step size is not set. By default permitted values are aligned with the lower bound if it is set, otherwise with zero.

Variables:

  • min (number) – The lower bound.

  • max (number) – The upper bound.

  • min_included (bool) – Whether the lower bound is included.

  • max_included (bool) – Whether the upper bound is included.

  • step (number, optional) – The step size.

  • offset (number, optional) – The step offset.

EXCLUDE = 0
ID = <carta.validation.Number object>
INCLUDE = 3
INCLUDE_MAX = 2
INCLUDE_MIN = 1
PERCENTAGE = <carta.validation.Number object>
POSITIVE = <carta.validation.Number object>
property description

A human-readable description of this parameter descriptor.

Returns:

The description.

Return type:

string

validate(value, parent)

Check if the value is a number and falls within any bounds that were provided.

We check the type by attempting to convert the value to float. We do this instead of comparing types directly to support compatible numeric types from e.g. the numpy library without having to anticipate and check for them explicitly and without introducing import dependencies.

See carta.validation.Parameter.validate for general information about this method.

class carta.validation.OneOf(*options, normalize=None)

Bases: Parameter

A parameter which must be one of several discrete values.

Parameters:

  • *options (iterable) – An iterable of permitted values.

  • normalize (function, optional) – A function for applying a transformation to the value before the comparison: for example, lambda x: x.lower().

Variables:

  • options (iterable) – An iterable of permitted values.

  • normalize (function, optional) – A function for applying a transformation to the value before the comparison.

property description

A human-readable description of this parameter descriptor.

Returns:

The description.

Return type:

string

validate(value, parent)

Check if the value is equal to one of the provided options. If a normalization function is given, this is first used to transform the value.

See carta.validation.Parameter.validate for general information about this method.

class carta.validation.Parameter

Bases: object

The top-level class for parameter validation.

property description

A human-readable description of this parameter descriptor.

Returns:

The description.

Return type:

string

validate(value, parent)

Validate the value provided.

Parameters:

  • value – The value to be validated.

  • parent – The object which owns the decorated method.

Raises:

  • TypeError – If the value provided is not of the correct type.

  • ValueError – If the value provided is of the correct type but has an invalid value.

  • AttributeError – If the check depends on an attribute on the parent object of the decorated method, and it does not exist.

class carta.validation.Size

Bases: Union

A representation of an angular size or a size in pixels. Can be a number or a numeric string with valid size units. A number is assumed to be a pixel value. Validates strings using carta.util.AngularSize.

class AngularSize(regex=None, flags=0)

Bases: String

Helper validator class which uses carta.util.AngularSize to validate strings.

validate(value, parent)

Check if the value can be parsed as an angular size.

See carta.validation.Parameter.validate for general information about this method.

class carta.validation.String(regex=None, flags=0)

Bases: Parameter

A string parameter.

Parameters:

  • regex (str, optional) – A regular expression string which the parameter must match.

  • flags (int, optional) – The flags to use when matching the regular expression. Set to zero (no flags) by default.

Variables:

  • regex (str) – A regular expression string which the parameter must match.

  • flags (int) – The flags to use when matching the regular expression.

property description

A human-readable description of this parameter descriptor.

Returns:

The description.

Return type:

string

validate(value, parent)

Check if the value is a string and if it matches a regex if one was provided.

See carta.validation.Parameter.validate for general information about this method.

class carta.validation.TupleColor

Bases: Parameter

An HTML color tuple. Not intended to be used directly; you probably want carta.validation.Color instead.

property description

A human-readable description of this parameter descriptor.

Returns:

The description.

Return type:

string

validate(value, parent)

Check if the value can be parsed as a color tuple, and validate the tuple elements.

See carta.validation.Parameter.validate for general information about this method.

class carta.validation.Union(*options, description=None)

Bases: Parameter

A union of other parameter descriptors.

Parameters:

  • *options (iterable of carta.validation.Parameter objects) – An iterable of valid descriptors for this parameter.

  • description (str, optional) – A custom description. The default is generated from the descriptions of the provided options.

Variables:

options (iterable of carta.validation.Parameter objects) – An iterable of valid descriptors for this parameter.

property description

A human-readable description of this parameter descriptor.

Returns:

The description.

Return type:

string

validate(value, parent)

Check if the value can be validated with one of the provided descriptors. The descriptors are evaluated in the order that they are given, and the function exits after the first successful validation.

See carta.validation.Parameter.validate for general information about this method.

carta.validation.all_optional(*vargs)

Wrapper to make all parameters in an iterable optional.

For improved legibility in functions with many sequential optional parameters. Can also enable reuse of validation parameters in functions which call other functions.

Parameters:

*vargs (iterable of carta.validation.Parameter objects)

Returns:

The same parameters in the same order, but with all non-optional parameters made optional (that is, wrapped in a obj:carta.validation.NoneOr parameter).

Return type:

iterable of carta.validation.Parameter objects

carta.validation.validate(*vargs)

The function which returns the decorator used to validate method parameters.

It is assumed that the function to be decorated is an object method and the first parameter is self; this parameter is therefore ignored by the decorator. The remaining positional parameters are validated in order using the provided descriptors. The descriptors are also combined pairwise with the parameter names in the signature of the original function to create a dictionary for validating keyword parameters.

Functions with *args or **kwargs are not currently supported: use iterables and explicit keyword parameters instead.

The decorator inserts the descriptions of the parameters into the docstring of the decorated function, if placeholders have been left for them in the original docstring. The descriptions are passed as positional parameters to str.format.

The self parameter is passed into the validation method of each descriptor, so that checks can depend on properties to be evaluated at runtime (this is currently used by carta.validation.Evaluate).

The decorated function raises a carta.util.CartaValidationFailed if one of the parameters fails to validate.

Parameters:

*vargs (iterable of carta.validation.Parameter objects) – Descriptors to be used to validate the function parameters, in the same order as the parameters.

Returns:

The decorator function.

Return type:

function

carta.validation.vargs(*functions)

Helper function for extracting validation parameters from functions.

For improved legibility in functions which reuse validation parameters from other functions.

Parameters:

*functions (iterable of functions)

Returns:

The validation parameters of the given functions, in order, unpacked into a 1D sequence.

Return type:

iterable of carta.validation.Parameter objects

carta.vector_overlay module

This module contains functionality for interacting with the vector overlay of an image. The class in this module should not be instantiated directly. When an image object is created, a vector overlay object is automatically created as a property.

class carta.vector_overlay.VectorOverlay(image)

Bases: BasePathMixin

Utility object for collecting image functions related to the vector overlay.

Parameters:

image (carta.image.Image object) – The image associated with this vector overlay.

Variables:
apply()

Apply the vector overlay configuration.

clear()

Clear the vector overlay configuration.

configure(angular_source=None, intensity_source=None, pixel_averaging_enabled=None, pixel_averaging=None, fractional_intensity=None, threshold_enabled=None, threshold=None, debiasing=None, q_error=None, u_error=None)

Configure vector overlay.

All parameters are optional. For each option that is not provided, the value currently set in the frontend will be preserved. Initial frontend settings are noted below.

We deduce some boolean options. For example, providing an explicit pixel averaging width with the pixel_averaging parameter will automatically enable pixel averaging unless pixel_averaging_enabled is also explicitly set to False. To disable pixel averaging, explicitly set pixel_averaging_enabled to False.

Parameters:

  • angular_source (a member of carta.constants.VectorOverlaySource or None) – The angular source. This is initially set to computed PA if the image contains Stokes information, otherwise to the current image.

  • intensity_source (a member of carta.constants.VectorOverlaySource or None) – The intensity source. This is initially set to computed PI if the image contains Stokes information, otherwise to the current image.

  • pixel_averaging_enabled (a boolean or None) – Enable pixel averaging. This is initially enabled if the pixel averaging width is positive.

  • pixel_averaging (a number or None) – The pixel averaging width in pixels. The initial value can be configured in the frontend preferences (the default is 4).

  • fractional_intensity (a number or None) – Enable fractional polarization intensity. The initial value can be configured in the frontend preferences. By default this is disabled and the absolute polarization intensity is used.

  • threshold_enabled (a boolean or None) – Enable threshold. Initially the threshold is disabled.

  • threshold (a number or None) – The threshold in Jy/pixels. The initial value is zero.

  • debiasing (a boolean or None) – Enable debiasing. This is initially disabled.

  • q_error (a number or None) – The Stokes Q error in Jy/beam. Set both this and u_error to enable debiasing. Initially set to zero.

  • u_error (a number or None) – The Stokes U error in Jy/beam. Set both this and q_error to enable debiasing. Initially set to zero.

hide()

Hide the vector overlay.

plot(angular_source=None, intensity_source=None, pixel_averaging_enabled=None, pixel_averaging=None, fractional_intensity=None, threshold_enabled=None, threshold=None, debiasing=None, q_error=None, u_error=None, thickness=None, intensity_min=None, intensity_max=None, length_min=None, length_max=None, rotation_offset=None, color=None, colormap=None, bias=None, contrast=None)

Configure, style, and apply the vector overlay in a single step.

If both a color and a colormap are provided, the colormap will be enabled.

Parameters:

  • angular_source (a member of carta.constants.VectorOverlaySource or None) – The angular source. This is initially set to computed PA if the image contains Stokes information, otherwise to the current image.

  • intensity_source (a member of carta.constants.VectorOverlaySource or None) – The intensity source. This is initially set to computed PI if the image contains Stokes information, otherwise to the current image.

  • pixel_averaging_enabled (a boolean or None) – Enable pixel averaging. This is initially enabled if the pixel averaging width is positive.

  • pixel_averaging (a number or None) – The pixel averaging width in pixels. The initial value can be configured in the frontend preferences (the default is 4).

  • fractional_intensity (a number or None) – Enable fractional polarization intensity. The initial value can be configured in the frontend preferences. By default this is disabled and the absolute polarization intensity is used.

  • threshold_enabled (a boolean or None) – Enable threshold. Initially the threshold is disabled.

  • threshold (a number or None) – The threshold in Jy/pixels. The initial value is zero.

  • debiasing (a boolean or None) – Enable debiasing. This is initially disabled.

  • q_error (a number or None) – The Stokes Q error in Jy/beam. Set both this and u_error to enable debiasing. Initially set to zero.

  • u_error (a number or None) – The Stokes U error in Jy/beam. Set both this and q_error to enable debiasing. Initially set to zero.

  • thickness (a number or None) – The line thickness in pixels. The initial value is 1.

  • intensity_min (a number or a member of carta.constants.Auto or None) – The minimum value of intensity in Jy/pixel. Use carta.constants.Auto.AUTO to clear the custom value and calculate it automatically.

  • intensity_max (a number or a member of carta.constants.Auto or None) – The maximum value of intensity in Jy/pixel. Use carta.constants.Auto.AUTO to clear the custom value and calculate it automatically.

  • length_min (a number or None) – The minimum value of line length in pixels. The initial value is 0.

  • length_max (a number or None) – The maximum value of line length in pixels. The initial value is 20.

  • rotation_offset (a number or None) – The rotation offset in degrees. The initial value is 0.

  • color (an HTML color specification or None) – The color. The initial value value is #238551 (a shade of green).

  • colormap (a member of carta.constants.Colormap or None) – The colormap. The initial value is carta.constants.Colormap.VIRIDIS.

  • bias (a number greater than or equal to -1 and smaller than or equal to 1 or None) – The colormap bias. The initial value is 0.

  • contrast (a number greater than or equal to 0 and smaller than or equal to 2 or None) – The colormap contrast. The initial value is 1.

set_bias_and_contrast(bias=None, contrast=None)

Set the vector overlay bias and contrast.

Parameters:

  • bias (a number greater than or equal to -1 and smaller than or equal to 1 or None) – The colormap bias. The initial value is 0.

  • contrast (a number greater than or equal to 0 and smaller than or equal to 2 or None) – The colormap contrast. The initial value is 1.

set_color(color)

Set the vector overlay color.

This automatically disables the colormap.

Parameters:

color (an HTML color specification) – The color. The initial value is #238551 (a shade of green).

set_colormap(colormap)

Set the vector overlay colormap.

This also automatically enables the colormap.

Parameters:

colormap (a member of carta.constants.Colormap) – The colormap. The initial value is carta.constants.Colormap.VIRIDIS.

set_intensity_range(intensity_min=None, intensity_max=None)

Set the vector overlay intensity range.

Parameters:
set_length_range(length_min, length_max)

Set the vector overlay length range.

Parameters:

  • length_min (a number) – The minimum value of line length in pixels. The initial value is 0.

  • length_max (a number) – The maximum value of line length in pixels. The initial value is 20.

set_rotation_offset(rotation_offset)

Set the vector overlay rotation offset.

Parameters:

rotation_offset (a number) – The rotation offset in degrees. The initial value is 0.

set_thickness(thickness)

Set the vector overlay line thickness.

Parameters:

thickness (a number) – The line thickness in pixels. The initial value is 1.

set_visible(state)

Set the vector overlay visibility.

Parameters:

state (a boolean) – The desired visibility state.

show()

Show the vector overlay.

carta.wcs_overlay module

This module contains functionality for interacting with the WCS overlay. The classes in this module should not be instantiated directly. When a session object is created, an overlay object is automatically created as a property, and overlay component objects are created as its subproperties.

class carta.wcs_overlay.Axes(overlay)

Bases: HasCustomColor, HasVisibility, HasWidth, OverlayComponent

The WCS overlay axes configuration.

Variables:

session (carta.session.Session object) – The session object associated with this overlay component.

COMPONENT = 'axes'
class carta.wcs_overlay.Beam(overlay)

Bases: ImageWCSConnector, OverlayComponent

The WCS overlay beam configuration.

All beam settings are per-image. Through this object, settings can be retrieved or applied to a single image, all images, or a subset of images.

Variables:

session (carta.session.Session object) – The session object associated with this overlay component.

COMPONENT = 'beam.settingsForDisplay'
color(image_ids=None)

The color of this component.

Parameters:

image_ids (an iterable in which each element is a number greater than or equal to 0 , in increments of 1 or None) – The images to query. By default, values will be returned for all images.

Returns:

The colors of the beam in the specified images.

Return type:

tuple of members of carta.constants.color.PaletteColor

hide(image_ids=None)

Hide this component.

Parameters:

image_ids (an iterable in which each element is a number greater than or equal to 0 , in increments of 1 or None) – The images to configure. By default, the settings will be changed for all images.

position(image_ids=None)

The beam position.

Parameters:

image_ids (an iterable in which each element is a number greater than or equal to 0 , in increments of 1 or None) – The images to query. By default, values will be returned for all images.

Returns:

The X and Y beam positions of the specified images, in pixels.

Return type:

tuple of (number, number) tuples

set_color(color, image_ids=None)

Set the color of this component.

Parameters:

  • color (a member of carta.constants.PaletteColor) – The color.

  • image_ids (an iterable in which each element is a number greater than or equal to 0 , in increments of 1 or None) – The images to configure. By default, the settings will be changed for all images.

set_position(position_x=None, position_y=None, image_ids=None)

Set the beam position.

Parameters:

  • position_x (a number or None) – The X position, in pixels.

  • position_y (a number or None) – The Y position, in pixels.

  • image_ids (an iterable in which each element is a number greater than or equal to 0 , in increments of 1 or None) – The images to configure. By default, the settings will be changed for all images.

set_type(beam_type, image_ids=None)

Set the beam type.

Parameters:

  • beam_type (a member of carta.constants.BeamType) – The beam type.

  • image_ids (an iterable in which each element is a number greater than or equal to 0 , in increments of 1 or None) – The images to configure. By default, the settings will be changed for all images.

set_visible(state, image_ids=None)

Set the visibility of this component.

Parameters:

  • visible (a boolean) – Whether this component should be visible.

  • image_ids (an iterable in which each element is a number greater than or equal to 0 , in increments of 1 or None) – The images to configure. By default, the settings will be changed for all images.

set_width(width, image_ids=None)

Set the width of this component.

Parameters:

  • width (a number greater than 0) – The width.

  • image_ids (an iterable in which each element is a number greater than or equal to 0 , in increments of 1 or None) – The images to configure. By default, the settings will be changed for all images.

show(image_ids=None)

Show this component.

Parameters:

image_ids (an iterable in which each element is a number greater than or equal to 0 , in increments of 1 or None) – The images to configure. By default, the settings will be changed for all images.

type(image_ids=None)

The beam type.

Parameters:

image_ids (an iterable in which each element is a number greater than or equal to 0 , in increments of 1 or None) – The images to query. By default, values will be returned for all images.

Returns:

The beam types of the specified images.

Return type:

tuple of members of carta.constants.BeamType

visible(image_ids=None)

The visibility of this component.

Parameters:

image_ids (an iterable in which each element is a number greater than or equal to 0 , in increments of 1 or None) – The images to query. By default, values will be returned for all images.

Returns:

Whether the beam is visible in the specified images.

Return type:

tuple of boolean

width(image_ids=None)

The width of this component.

Parameters:

image_ids (an iterable in which each element is a number greater than or equal to 0 , in increments of 1 or None) – The images to query. By default, values will be returned for all images.

Returns:

The width of the beam in the specified images.

Return type:

tuple of boolean

class carta.wcs_overlay.Border(overlay)

Bases: HasCustomColor, HasVisibility, HasWidth, OverlayComponent

The WCS overlay border configuration.

Variables:

session (carta.session.Session object) – The session object associated with this overlay component.

COMPONENT = 'border'
class carta.wcs_overlay.Colorbar(overlay)

Bases: HasCustomColor, HasVisibility, HasWidth, OverlayComponent

The WCS overlay colorbar configuration.

This component has subcomponents which are configured separately through properties on this object.

Variables:
COMPONENT = 'colorbar'
property interactive

Whether the colorbar is interactive.

Returns:

Whether the colorbar is interactive.

Return type:

boolean

property offset

The colorbar offset.

Returns:

The offset, in pixels.

Return type:

number

property position

The colorbar position.

Returns:

The position.

Return type:

a member of carta.constants.ColorbarPosition

set_interactive(state)

Set whether the colorbar should be interactive.

Parameters:

state (a boolean) – Whether the colorbar should be interactive.

set_offset(offset)

Set the colorbar offset.

Parameters:

offset (a number greater than or equal to 0) – The offset, in pixels.

set_position(position)

Set the colorbar position.

Parameters:

offset (a member of carta.constants.ColorbarPosition) – The position.

class carta.wcs_overlay.ColorbarBorder(colorbar)

Bases: HasVisibility, HasWidth, HasCustomColor, ColorbarComponent

The WCS overlay colorbar border configuration.

Variables:

colorbar (carta.wcs_overlay.Colorbar object) – The colorbar object associated with this colorbar component.

PREFIX = 'border'
class carta.wcs_overlay.ColorbarComponent(colorbar)

Bases: object

Base class for components of the WCS overlay colorbar.

Variables:
call_action(path, *args, **kwargs)

Convenience wrapper for the colorbar object’s generic action method.

This method calls carta.wcs_overlay.Colorbar.call_action after inserting this subcomponent’s name prefix into the path parameter. It assumes that the action name starts with a lowercase word, and that the prefix should be inserted after this word with a leading capital letter.

Parameters:

  • path (string) – The path to an action relative to the colorbar object’s store, with this subcomponent’s name prefix omitted.

  • *args – A variable-length list of parameters. These are passed unmodified to the colorbar method.

  • **kwargs – Arbitrary keyword parameters. These are passed unmodified to the colorbar method.

Returns:

The unmodified return value of the colorbar method.

Return type:

object or None

get_value(path, return_path=None)

Convenience wrapper for the colorbar object’s generic method for retrieving attribute values.

This method calls carta.wcs_overlay.Colorbar.get_value after inserting this subcomponent’s name prefix into the path parameter. It assumes that the attribute name starts with a lowercase letter, that the prefix should be inserted before it, and that the first letter of the original name should be capitalised.

Parameters:

  • path (string) – The path to an attribute relative to the colorbar object’s store, with this subcomponent’s name prefix omitted.

  • return_path (string, optional) – Specifies a subobject of the attribute value which should be returned instead of the whole object.

Returns:

The unmodified return value of the colorbar method.

Return type:

object

class carta.wcs_overlay.ColorbarGradient(colorbar)

Bases: HasVisibility, ColorbarComponent

The WCS overlay colorbar gradient configuration.

Variables:

colorbar (carta.wcs_overlay.Colorbar object) – The colorbar object associated with this colorbar component.

PREFIX = 'gradient'
class carta.wcs_overlay.ColorbarLabel(colorbar)

Bases: HasVisibility, HasCustomColor, HasCustomText, HasFont, HasRotation, ImageWCSConnector, ColorbarComponent

The WCS overlay colorbar label configuration.

Variables:

colorbar (carta.wcs_overlay.Colorbar object) – The colorbar object associated with this colorbar component.

PREFIX = 'label'
set_text(label_text, image_ids=None)

Set the custom colorbar label text for the specified images.

This also automatically enables custom title text for all images. It can be disabled with carta.wcs_overlay.Title.set_custom_text.

Parameters:

  • label_text (a string) – The custom colorbar label text for the specified images.

  • image_ids (an iterable in which each element is a number greater than or equal to 0 , in increments of 1 or None) – The images to configure.

text(image_ids=None)

The custom colorbar label text for the specified images.

Parameters:

image_ids (an iterable in which each element is a number greater than or equal to 0 , in increments of 1 or None) – The images to query.

Returns:

The colorbar label text of the specified images.

Return type:

tuple of string

class carta.wcs_overlay.ColorbarNumbers(colorbar)

Bases: HasVisibility, HasCustomPrecision, HasCustomColor, HasFont, HasRotation, ColorbarComponent

The WCS overlay colorbar numbers configuration.

Variables:

colorbar (carta.wcs_overlay.Colorbar object) – The colorbar object associated with this colorbar component.

PREFIX = 'number'
class carta.wcs_overlay.ColorbarTicks(colorbar)

Bases: HasVisibility, HasWidth, HasCustomColor, ColorbarComponent

The WCS overlay colorbar ticks configuration.

Variables:

colorbar (carta.wcs_overlay.Colorbar object) – The colorbar object associated with this colorbar component.

PREFIX = 'tick'
property density

The colorbar ticks density.

Returns:

The density.

Return type:

number

property length

The colorbar ticks length.

Returns:

The length.

Return type:

number

set_density(density)

Set the colorbar ticks density.

Parameters:

density (a number greater than 0) – The density.

set_length(length)

Set the colorbar ticks length.

Parameters:

length (a number greater than 0) – The length.

class carta.wcs_overlay.Global(overlay)

Bases: HasColor, OverlayComponent

The global WCS overlay configuration.

Variables:

session (carta.session.Session object) – The session object associated with this overlay component.

COMPONENT = 'global'
property coordinate_system

The coordinate system.

Returns:

The coordinate system.

Return type:

a member of carta.constants.CoordinateSystem

property labelling

The labelling (internal or external).

Returns:

The type of labelling.

Return type:

a member of carta.constants.LabelType

set_coordinate_system(coordinate_system)

Set the coordinate system.

Parameters:

coordinate_system (a member of carta.constants.CoordinateSystem) – The coordinate system.

set_labelling(labelling)

Set the type of labelling (internal or external).

Parameters:

labelling (a member of carta.constants.LabelType) – The type of labelling.

set_tolerance(tolerance)

Set the tolerance.

Parameters:

tolerance (a number greater than or equal to 0 and smaller than or equal to 100) – The tolerance, as a percentage.

property tolerance

The tolerance.

Returns:

The tolerance, as a percentage.

Return type:

number

class carta.wcs_overlay.Grid(overlay)

Bases: HasCustomColor, HasVisibility, HasWidth, OverlayComponent

The WCS overlay grid configuration.

Variables:

session (carta.session.Session object) – The session object associated with this overlay component.

COMPONENT = 'grid'
property custom_gap

Whether a custom gap is applied to this component.

Returns:

Whether a custom gap is applied.

Return type:

boolean

property gap

The gap.

Returns:

  • number – The X gap.

  • number – The Y gap.

set_custom_gap(state)

Set whether a custom gap should be applied to this component.

Parameters:

state (a boolean) – Whether a custom gap should be applied.

set_gap(gap_x, gap_y)

Set the gap.

This also automatically enables the custom gap.

Parameters:

  • gap_x (a number greater than 0 or None) – The X gap.

  • gap_y (a number greater than 0 or None) – The Y gap.

class carta.wcs_overlay.HasColor

Bases: object

Components which inherit this class have a palette color setting.

property color

The color of this component.

Returns:

The color.

Return type:

a member of carta.constants.color.PaletteColor

set_color(color)

Set the color of this component.

Parameters:

color (a member of carta.constants.PaletteColor) – The color.

class carta.wcs_overlay.HasCustomColor

Bases: HasColor

Components which inherit this class have a palette color setting and a custom color flag.

property custom_color

Whether a custom color is applied to this component.

Returns:

Whether a custom color is applied.

Return type:

boolean

set_color(color)

Set the color of this component.

This automatically enables the use of a custom color.

Parameters:

color (a member of carta.constants.PaletteColor) – The color.

set_custom_color(state)

Set whether a custom color should be applied to this component.

Parameters:

state (a boolean) – Whether a custom color should be applied to this component. By default the global color is applied.

class carta.wcs_overlay.HasCustomPrecision

Bases: object

Components which inherit this class have a precision setting and a custom precision flag.

property custom_precision

Whether a custom precision is applied to this component.

Returns:

Whether a custom precision is applied.

Return type:

boolean

property precision

The precision of this component.

Returns:

The precision.

Return type:

number

set_custom_precision(state)

Set whether a custom precision should be applied to this component.

Parameters:

state – Whether a custom precision should be applied.

set_precision(precision)

Set the precision of this component.

This also automatically enables the custom precision.

Parameters:

precision (a number greater than or equal to 0) – The precision.

class carta.wcs_overlay.HasCustomText

Bases: object

Components which inherit this class have a custom text flag. Different components have different text properties, which are set separately.

property custom_text

Whether custom text is applied to this component.

Returns:

Whether custom text is applied.

Return type:

boolean

set_custom_text(state)

Set whether custom text should be applied to this component.

Parameters:

state (a boolean) – Whether custom text should be applied to this component. By default the text is generated automatically.

class carta.wcs_overlay.HasFont

Bases: object

Components which inherit this class have a font setting.

property font

The font of this component.

Returns:

property font_size

The font size of this component.

Returns:

The font size, in pixels.

Return type:

number

set_font(font_family, font_style)

Set the font of this component.

Parameters:
set_font_size(font_size)

Set the font size of this component.

Parameters:

font_size (a number) – The font size, in pixels.

class carta.wcs_overlay.HasRotation

Bases: object

Components which inherit this class have a rotation setting.

property rotation

The rotation of this component.

Returns:

The rotation in degrees.

Return type:

number

set_rotation(rotation)

Set the rotation of this component.

Parameters:

rotation (a number greater than or equal to -90 and smaller than or equal to 90 , in increments of 90) – The rotation in degrees.

class carta.wcs_overlay.HasVisibility

Bases: object

Components which inherit this class have a visibility setting, including show and hide aliases.

hide()

Hide this component.

set_visible(state)

Set the visibility of this component.

Parameters:

visible (a boolean) – Whether this component should be visible.

show()

Show this component.

property visible

The visibility of this component.

Returns:

Whether this component is visible.

Return type:

boolean

class carta.wcs_overlay.HasWidth

Bases: object

Components which inherit this class have a width setting.

set_width(width)

Set the width of this component.

Parameters:

width (a number greater than 0) – The width.

property width

The width of this component.

Returns:

The width.

Return type:

boolean

class carta.wcs_overlay.ImageWCSConnector

Bases: object

This is a helper mixin with functions which let a session WCS component delegate calls to image WCS components.

ANY_IDS = <carta.validation.NoneOr object>
class carta.wcs_overlay.ImageWCSOverlay(image)

Bases: BasePathMixin

Utility object for collecting functions related to the WCS overlay settings for individual images. These functions are grouped in subcomponents, which can be accessed directly by name or looked up in a mapping by carta.constants.Overlay enum.

This object is only used to access WCS settings that are applied per-image. Global WCS settings are accessed through the carta.wcs_overlay.SessionWCSOverlay object.

Parameters:

image (carta.image.Image object) – The image object associated with this overlay object.

Variables:
class ImageBeam(image)

Bases: HasColor, HasVisibility, HasWidth, BasePathMixin

The image WCS overlay beam configuration.

Variables:

  • image (carta.image.Image object) – The image object associated with this overlay component.

  • session (carta.session.Session object) – The session object associated with this overlay component.

property position

The beam position.

Returns:

  • number – The X beam position, in pixels.

  • number – The Y beam position, in pixels.

set_position(position_x=None, position_y=None)

Set the beam position.

Parameters:

  • position_x (a number or None) – The X position, in pixels.

  • position_y (a number or None) – The Y position, in pixels.

set_type(beam_type)

Set the beam type.

Parameters:

beam_type (a member of carta.constants.BeamType) – The beam type.

property type

The beam type.

Returns:

The beam type.

Return type:

a member of carta.constants.BeamType

class ImageColorbar(image)

Bases: object

The image WCS overlay title configuration.

Variables:

label (carta.wcs_overlay.ImageWCSOverlay.ImageColorbar.ImageColorbarLabel object) – The label subcomponent.

class ImageColorbarLabel(image)

Bases: object

The image WCS overlay colorbar label configuration.

Variables:

image (carta.image.Image object) – The image object associated with this overlay component.

set_text(label_text)

Set the custom colorbar label text for this image.

This also automatically enables custom colorbar label text for all images. It can be disabled with carta.wcs_overlay.ColorbarLabel.set_custom_text.

Parameters:

label_text ({0}) – The custom colorbar label text.

property text

The custom colorbar label text for this image.

Returns:

The title text.

Return type:

string

class ImageTitle(image)

Bases: object

The image WCS overlay title configuration.

Variables:

image (carta.image.Image object) – The image object associated with this overlay component.

set_text(title_text)

Set the custom title text for this image.

This also automatically enables custom title text for all images. It can be disabled with carta.wcs_overlay.Title.set_custom_text.

Parameters:

title_text (a string) – The custom title text.

property text

The custom title text for this image.

Returns:

The title text.

Return type:

string

class carta.wcs_overlay.Labels(overlay)

Bases: HasCustomColor, HasCustomText, HasFont, HasVisibility, OverlayComponent

The WCS overlay labels configuration.

Variables:

session (carta.session.Session object) – The session object associated with this overlay component.

COMPONENT = 'labels'
set_text(label_x=None, label_y=None)

Set the label text.

This also automatically enables the custom label text.

Parameters:

  • label_x (a string or None) – The X-axis label text.

  • label_y (a string or None) – The Y-axis label text.

property text

The label text.

If a custom label text has not been set, these values will be blank.

Returns:

  • string – The X label text.

  • string – The Y label text.

class carta.wcs_overlay.Numbers(overlay)

Bases: HasCustomColor, HasFont, HasVisibility, HasCustomPrecision, OverlayComponent

The WCS overlay numbers configuration.

Variables:

session (carta.session.Session object) – The session object associated with this overlay component.

COMPONENT = 'numbers'
property custom_format

Whether a custom format is applied to the numbers.

Returns:

Whether a custom format is applied.

Return type:

boolean

property format

The X and Y number format.

If the image has no WCS information, both the X and Y formats will be None.

If a custom number format is not set, this returns the default format set by the coordinate system.

Returns:

set_custom_format(state)

Set whether a custom format should be applied to the numbers.

Parameters:

state (a boolean) – Whether a custom format should be applied.

set_format(format_x=None, format_y=None)

Set the X and/or Y number format.

This also automatically enables the custom number format, if either of the format parameters is set. If only one format is provided, the other will be set to the last previously used custom format, or to the system default.

Parameters:
class carta.wcs_overlay.OverlayComponent(overlay)

Bases: BasePathMixin

A single WCS overlay component.

Variables:

session (carta.session.Session object) – The session object associated with this overlay component.

CLASS = {Overlay.AXES: <class 'carta.wcs_overlay.Axes'>, Overlay.BEAM: <class 'carta.wcs_overlay.Beam'>, Overlay.BORDER: <class 'carta.wcs_overlay.Border'>, Overlay.COLORBAR: <class 'carta.wcs_overlay.Colorbar'>, Overlay.GLOBAL: <class 'carta.wcs_overlay.Global'>, Overlay.GRID: <class 'carta.wcs_overlay.Grid'>, Overlay.LABELS: <class 'carta.wcs_overlay.Labels'>, Overlay.NUMBERS: <class 'carta.wcs_overlay.Numbers'>, Overlay.TICKS: <class 'carta.wcs_overlay.Ticks'>, Overlay.TITLE: <class 'carta.wcs_overlay.Title'>}

Mapping of carta.constants.Overlay enums to component classes. This mapping is used to select the appropriate subclass when an overlay component object is constructed in the wrapper.

class carta.wcs_overlay.SessionWCSOverlay(session)

Bases: BasePathMixin

Utility object for collecting functions related to the global WCS overlay settings for the session. Most functions are additionally grouped in subcomponents, which can be accessed directly by name or looked up in a mapping by carta.constants.Overlay enum.

Parameters:

session (carta.session.Session object) – The session object associated with this overlay object.

Variables:
get(component)

Access an overlay component subobject by name.

Parameters:

component (a member of carta.constants.Overlay) – The component to access.

Returns:

The overlay component object.

Return type:

A member of carta.wcs_overlay.OverlayComponent

palette_to_rgb(color)

Convert a palette colour to RGB.

The RGB value depends on whether the session is using the light theme or the dark theme.

Parameters:

color (a member of carta.constants.PaletteColor) – The colour to convert.

Returns:

The RGB value of the palette colour in the session’s current theme, as a 6-digit hexadecimal with a leading #.

Return type:

string

set_view_area(width, height)

Set the dimensions of the view area.

Parameters:

  • width (a number) – The new width, in pixels, divided by the device pixel ratio.

  • height (a number) – The new height, in pixels, divided by the device pixel ratio.

class carta.wcs_overlay.Ticks(overlay)

Bases: HasCustomColor, HasWidth, OverlayComponent

The WCS overlay ticks configuration.

Variables:

session (carta.session.Session object) – The session object associated with this overlay component.

COMPONENT = 'ticks'
property custom_density

Whether a custom density is applied to the ticks.

Returns:

Whether a custom density is applied.

Return type:

boolean

property density

The density.

Returns:

  • number – The X density.

  • number – The Y density.

property draw_on_all_edges

Whether the ticks are drawn on all edges.

Returns:

Whether the ticks are drawn on all edges.

Return type:

boolean

property major_length

The major tick length.

Returns:

The major length, as a percentage.

Return type:

number

property minor_length

The minor tick length.

Returns:

The minor length, as a percentage.

Return type:

number

set_custom_density(state)

Set whether a custom density should be applied to the ticks.

Parameters:

state (a boolean) – Whether a custom density should be applied.

set_density(density_x=None, density_y=None)

Set the density.

This also automatically enables the custom density.

set_draw_on_all_edges(state)

Set whether the ticks should be drawn on all edges.

Parameters:

state (a boolean) – Whether the ticks should be drawn on all edges.

set_major_length(length)

Set the major tick length.

Parameters:

length (a number greater than or equal to 0 and smaller than or equal to 100) – The major tick length, as a percentage.

set_minor_length(length)

Set the minor tick length.

Parameters:

length (a number greater than or equal to 0 and smaller than or equal to 100) – The minor tick length, as a percentage.

class carta.wcs_overlay.Title(overlay)

Bases: HasCustomColor, HasCustomText, HasFont, HasVisibility, ImageWCSConnector, OverlayComponent

The WCS overlay title configuration.

Variables:

session (carta.session.Session object) – The session object associated with this overlay component.

COMPONENT = 'title'
set_text(title_text, image_ids=None)

Set the custom title text for the specified images.

This also automatically enables custom title text for all images. It can be disabled with carta.wcs_overlay.Title.set_custom_text.

Parameters:

  • title_text (a string) – The custom title text for the specified images.

  • image_ids (an iterable in which each element is a number greater than or equal to 0 , in increments of 1 or None) – The images to configure.

text(image_ids=None)

The custom title text for the specified images.

Parameters:

image_ids (an iterable in which each element is a number greater than or equal to 0 , in increments of 1 or None) – The images to query.

Returns:

The title text of the specified images.

Return type:

tuple of string