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:

• CartaBadToken – If an invalid token was provided.

• CartaBadUrl – If an invalid URL was provided.

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

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:

• CartaBadToken – If an invalid token was provided.

• CartaBadUrl – If an invalid URL was provided.

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

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.AnnotationFont(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: StrEnum

Fonts which may be used in annotations.

COURIER = 'Courier'

HELVETICA = 'Helvetica'

TIMES = 'Times'

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

Bases: StrEnum

Font styles which may be used in annotations.

BOLD = 'Bold'

BOLD_ITALIC = 'Italic Bold'

ITALIC = 'Italic'

NORMAL = 'Normal'

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.CoordinateType(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: IntEnum

Coordinate types corresponding to the protobuf enum.

PIXEL = 0

WORLD = 1

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

Bases: IntEnum

File types corresponding to the protobuf enum.

CASA = 0

CRTF = 1

DS9_REG = 2

FITS = 3

HDF5 = 4

MIRIAD = 5

UNKNOWN = 6

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.PointShape(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: IntEnum

Point annotation shapes corresponding to the protobuf enum.

BOX = 1

CIRCLE = 2

CIRCLE_LINED = 3

CROSS = 6

DIAMOND = 4

DIAMOND_LINED = 5

SQUARE = 0

X = 7

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.RegionType(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: IntEnum

Region types corresponding to the protobuf enum.

ANNCOMPASS = 16

ANNELLIPSE = 11

ANNLINE = 8

ANNPOINT = 7

ANNPOLYGON = 12

ANNPOLYLINE = 9

ANNRECTANGLE = 10

ANNRULER = 14

ANNTEXT = 15

ANNVECTOR = 13

ELLIPSE = 4

LINE = 1

POINT = 0

POLYGON = 6

POLYLINE = 2

RECTANGLE = 3

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:

• description (string) – The human-readable description of this type.

• units (set of carta.constants.SpectralUnit) – The units supported for this type.

• default_unit (carta.constants.SpectralUnit) – The default unit for this type.

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.TextPosition(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: IntEnum

Text annotation positions corresponding to the protobuf enum.

BOTTOM = 6

CENTER = 0

LEFT = 7

LOWER_LEFT = 3

LOWER_RIGHT = 4

RIGHT = 8

TOP = 5

UPPER_LEFT = 1

UPPER_RIGHT = 2

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:

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

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

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:

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

• image_id (integer) – The ID identifying this image within the session.

• raster (carta.raster.Raster) – Sub-object with functions related to the raster image.

• contours (carta.contours.Contours) – Sub-object with functions related to the contours.

• vectors (carta.vector_overlay.VectorOverlay) – Sub-object with functions related to the vector overlay.

• wcs (carta.wcs_overlay.ImageWCSOverlay) – Sub-object with functions related to the WCS overlay.

• regions (carta.region.RegionSet object) – Functions for manipulating regions associated with this image.

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

from_angular_size(size, axis)

Convert angular size to pixel size.

Parameters:

• size (a string) – The angular size.

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

Returns:

The pixel size.

Return type:

float

from_angular_size_points(points)

Convert angular size points to pixel size points.

The points must have string values which can be parsed as angular sizes.

Parameters:

points (an iterable in which each element is a pair of size strings) – Points with string values which are valid angular sizes.

Returns:

Points with numeric values which are pixel sizes.

Return type:

iterable of numeric points

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

from_world_coordinate_points(points)

Convert world coordinate points to image coordinate points.

The points must have string values which can be parsed as world coordinates using the current globally set coordinate system (and any custom number formats).

Parameters:

points (an iterable in which each element is a pair of coordinate strings) – Points with string values which are valid world coordinates.

Returns:

Points with numeric values which are image coordinates.

Return type:

iterable of numeric points

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:

• spectral_type (a member of carta.constants.SpectralType) – The spectral type to use.

• spectral_unit (a member of carta.constants.SpectralUnit or None) – The spectral unit to use. If this is omitted, the default unit for the type will be used.

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

to_angular_size_points(points)

Convert pixel size points to angular size points.

The points must be numeric.

Parameters:

points (an iterable in which each element is a pair of numbers) – Points with numeric values which are valid image coordinates.

Returns:

Points with string values which are angular sizes.

Return type:

iterable of angular size points

to_world_coordinate_points(points)

Convert image coordinate points to world coordinate points.

The points must be numeric.

Parameters:

points (an iterable in which each element is a pair of numbers) – Points with numeric values which are valid image coordinates.

Returns:

Points with string values which are world coordinates.

Return type:

iterable of string coordinate points

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:

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

• base_url (string) – The base frontend URL (with the token parameter, if any, removed).

• auth (integer) – The authentication type. One of carta.protocol.AuthType.BACKEND, carta.protocol.AuthType.CONTROLLER or carta.protocol.AuthType.NONE.

• refresh_token (carta.token.ControllerToken, optional) – The controller refresh token. Will be set to the token parameter if it is a controller token.

• backend_token (carta.token.BackendToken, optional) – The backend token. Will be set to the token parameter if it is a backend token. If the token parameter is omitted, and a token string can be parsed from the URL, it will be created from that string.

Raises:

• CartaBadToken – If an invalid token was provided.

• CartaBadUrl – If an invalid URL was provided.

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:

• CartaBadRequest – If the request was invalid.

• CartaRequestFailed – If the request failed.

• CartaBadResponse – If the response could not be decoded.

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:

• CartaBadRequest – If the request was invalid.

• CartaRequestFailed – If the backend could not send the request to the frontend.

• CartaActionFailed – If the action failed.

• CartaBadResponse – If a request which was expected to have a JSON response did not have one, or if a JSON response could not be decoded.

request_scripting_token()

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

Raises:

• CartaBadRequest – If the request was invalid.

• CartaRequestFailed – If the request failed.

• CartaBadResponse – If the response could not be decoded.

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:

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

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

hide()

Hide the raster component.

set_bias_and_contrast(bias=None, contrast=None)

Set the raster bias and contrast.

Parameters:

• bias (a number greater than or equal to -1 and smaller than or equal to 1 or a member of carta.constants.Auto or None) – A custom bias. Use carta.constants.Auto.AUTO to reset the bias to the frontend default of 0.

• contrast (a number greater than or equal to 0 and smaller than or equal to 2 or a member of carta.constants.Auto or None) – A custom contrast. Use carta.constants.Auto.AUTO to reset the contrast to the frontend default of 1.

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.region module

This module contains region classes which represent single regions or annotations loaded in the session, and a region set class which represents all regions and annotations associated with an image.

Region and annotation objects should not be instantiated directly, and should only be created through methods on the carta.region.RegionSet object.

class carta.region.CompassAnnotation(region_set, region_id)

Bases: HasFontMixin, HasPointerMixin, HasSizeMixin, Region

A compass annotation.

REGION_TYPES = (RegionType.ANNCOMPASS,)

The region types corresponding to this class.

property arrowheads_visible

The visibility of the north and east arrowheads.

Returns:

• boolean – Whether the north arrowhead is visible.

• boolean – Whether the east arrowhead is visible.

property label_offsets

The offsets of the north and east labels.

Returns:

• tuple of two numbers – The offset of the north label, in pixels.

• tuple of two numbers – The offset of the east label, in pixels.

property labels

The north and east labels.

Returns:

• string – The north label.

• string – The east label.

property point_length

The length of the compass points, in pixels.

Returns:

The length of the compass points.

Return type:

number

set_arrowhead_visible(north=None, east=None)

Set the north and east arrowhead visibility.

All parameters are optional. Omitted properties will be left unmodified.

Parameters:

• north (a boolean or None) – Whether the north arrowhead should be visible.

• east (a boolean or None) – Whether the east arrowhead should be visible.

set_label(north_label=None, east_label=None)

Set the north and east labels.

All parameters are optional. Omitted properties will be left unmodified.

Parameters:

• north_label (a string or None) – The north label.

• east_label (a string or None) – The east label.

set_label_offset(north_offset=None, east_offset=None)

Set the north and east label offsets.

All parameters are optional. Omitted properties will be left unmodified.

Parameters:

• north_offset (a pair of numbers or None) – The north label offset, in pixels.

• east_offset (a pair of numbers or None) – The east label offset, in pixels.

set_point_length(length, spatial_axis=None)

Set the length of the compass points.

If the length is provided in angular size units, a spatial axis must also be provided in order for the angular size to be converted to pixels.

Parameters:

• length (a number or a numeric string with valid size units) – The length, in pixels or angular size units.

• spatial_axis (a member of carta.constants.SpatialAxis or None) – The spatial axis which should be used to convert angular size units. This parameter is ignored if the length is provided in pixels.

Raises:

ValueError – If the length is in angular size units, but no spatial axis is provided.

set_size(size)

Set the size.

Both pixel and angular sizes are accepted, but both values must match.

The width and height of this annotation cannot be set independently. If two different values are provided, the smaller value will be used (after conversion to pixel units).

This function is provided for compatibility. Also see carta.region.CompassAnnotation.set_point_length for a more convenient way to resize this annotation.

Parameters:

size (a pair of numbers or size strings) – The new size.

class carta.region.EllipticalRegion(region_set, region_id)

Bases: HasRotationMixin, HasSizeMixin, Region

An elliptical region or annotation.

REGION_TYPES = (RegionType.ELLIPSE, RegionType.ANNELLIPSE)

The region types corresponding to this class.

as_polygon(num_vertices=None, density=10, delete=False)

Create a new polygonal region with the same dimensions and style as this elliptical region or annotation, approximating the shape of the ellipse.

This function does not delete the original region by default. Also see carta.region.EllipticalRegion.to_polygon.

By default, the number of vertices to use for the approximation is derived from the angular size of the ellipse circumference and the configured number of vertices per degree, with a minimum of 12. Vertices will be distributed more densely near the major axis and more sparsely near the minor axis.

Parameters:

• num_vertices (a number greater than or equal to 4 or None) – The number of vertices to use. If this parameter is not provided, the number is calculated dynamically from the configured density and the region size.

• density (a number greater than 0 or None) – The approximate number of vertices to add per degree of the ellipse circumference (the default is 10). This parameter is ignored if an exact number of vertices is provided.

• delete (a boolean or None) – Whether to delete the original region.

Returns:

A new region object.

Return type:

carta.region.PolygonRegion object

property semi_axes

The semi-axes, in pixels.

The north-south semi-axis is equal to half of the height, and the east-west semi-axis is equal to half of the width.

Returns:

• number – The north-south semi-axis, in pixels.

• number – The east-west semi-axis, in pixels.

set_semi_axes(semi_axes)

Set the semi-axes.

Both pixel and angular sizes are accepted, but both values must match.

Parameters:

size (a pair of numbers or size strings) – The new north-south and east-west semi-axes, in that order.

set_size(size)

Set the size.

The width and height will be used to calculate the semi-axes: the north-south semi-axis is equal to half of the height, and the east-west semi-axis is equal to half of the width.

Both pixel and angular sizes are accepted, but both values must match.

Parameters:

size (a pair of numbers or size strings) – The new width and height, in that order.

property size

The size, in pixels.

The width is equal to twice the east-west semi-axis, and the height is equal to twice the north-south semi-axis.

Returns:

• number – The width.

• number – The height.

to_polygon(num_vertices=None, density=10, delete=True)

Create a new polygonal region with the same dimensions and style as this elliptical region or annotation, approximating the shape of the ellipse.

This function is a convenience wrapper around carta.region.EllipticalRegion.as_polygon that deletes the original region by default.

By default, the number of vertices to use for the approximation is derived from the angular size of the ellipse circumference and the configured number of vertices per degree, with a minimum of 12. Vertices will be distributed more densely near the major axis and more sparsely near the minor axis.

Parameters:

• num_vertices (a number greater than or equal to 4 or None) – The number of vertices to use. If this parameter is not provided, the number is calculated dynamically from the configured density and the region size.

• density (a number greater than 0 or None) – The approximate number of vertices to add per degree of the ellipse circumference (the default is 10). This parameter is ignored if an exact number of vertices is provided.

• delete (a boolean or None) – Whether to delete the original region.

Returns:

A new region object.

Return type:

carta.region.PolygonRegion object

property wcs_semi_axes

The semi-axes, in angular size units.

The north-south semi-axis is equal to half of the height, and the east-west semi-axis is equal to half of the width.

Returns:

• string – The north-south semi-axis, in angular size units.

• string – The east-west semi-axis, in angular size units.

property wcs_size

The size, in angular size units.

The width is equal to twice the east-west semi-axis, and the height is equal to twice the north-south semi-axis.

Returns:

• string – The width.

• string – The height.

class carta.region.HasEndpointsMixin

Bases: object

This is a mixin class for regions which are defined by two endpoints. It assumes that the region has two control points and both should be interpreted as coordinates.

property endpoints

The endpoints, in image coordinates.

This is an alias of carta.region.Region.control_points.

Returns:

The endpoints.

Return type:

iterable containing two tuples of two numbers

property length

The Euclidean distance between the endpoints, in pixels.

Returns:

The length.

Return type:

float

set_endpoints(start=None, end=None)

Update the endpoints.

Both parameters are optional. If an endpoint is omitted, it will not be modified.

Both image and world coordinates are accepted, but both values in each point must match.

Parameters:

• start (a pair of numbers or coordinate strings or None) – The new start position, in image or world coordinates.

• end (a pair of numbers or coordinate strings or None) – The new end position, in image or world coordinates.

set_length(length)

Update the length.

Parameters:

length (a number or a numeric string with valid size units) – The new length, in pixels or angular size units.

property wcs_endpoints

The endpoints, in world coordinates.

Returns:

The endpoints.

Return type:

iterable containing two tuples of two strings

property wcs_length

The Euclidean distance between the endpoints, in angular size units.

Returns:

The length.

Return type:

float

class carta.region.HasFontMixin

Bases: object

This is a mixin class for annotations which have font properties.

property font

The font.

Returns:

The font.

Return type:

carta.constants.AnnotationFont

property font_size

The font size.

Returns:

The font size, in pixels.

Return type:

number

property font_style

The font style.

Returns:

The font style.

Return type:

carta.constants.AnnotationFontStyle

set_font(font=None, font_size=None, font_style=None)

Set the font properties.

All parameters are optional. Omitted properties will be left unmodified.

Parameters:

• font (a member of carta.constants.AnnotationFont or None) – The font face.

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

• font_style (a member of carta.constants.AnnotationFontStyle or None) – The font style.

class carta.region.HasPointerMixin

Bases: object

This is a mixin class for annotations which have a pointer style.

property pointer_length

The pointer length.

Returns:

The pointer length, in pixels.

Return type:

number

property pointer_width

The pointer width.

Returns:

The pointer width, in pixels.

Return type:

number

set_pointer_style(pointer_width=None, pointer_length=None)

Set the pointer style.

All parameters are optional. Omitted properties will be left unmodified.

Parameters:

• pointer_width (a number or None) – The pointer width, in pixels.

• pointer_length (a number or None) – The pointer length, in pixels.

class carta.region.HasRotationMixin

Bases: object

This is a mixin class for regions which can be rotated natively.

rotate(rotation)

Rotate this region anticlockwise by the angle provided.

The rotation provided will be added to the current rotation of the region.

Parameters:

rotation (a number) – The rotation to apply, in degrees.

property rotation

The rotation, in degrees.

Returns:

The rotation.

Return type:

number

set_rotation(angle)

Set the rotation.

Parameters:

angle (a number) – The new rotation, in degrees.

class carta.region.HasSizeMixin

Bases: object

This is a mixin class for regions which have a size (all of them except for point regions and annotations). These regions also have a line style.

Subclasses which have size functions partially implemented natively should use this mixin and override unimplemented functions as appropriate.

property dash_length

The dash length.

Returns:

The dash length, in pixels.

Return type:

number

property line_width

The line width.

Returns:

The line width, in pixels.

Return type:

number

scale(factor)

Scale by the factor provided.

The sign will be ignored; only the magnitude of the value will be used.

Parameters:

factor (a number) – The scaling factor to apply to the region.

set_line_style(line_width=None, dash_length=None)

Set the line style.

All parameters are optional. Omitted properties will be left unmodified.

To set the line color, see carta.region.Region.set_color.

Parameters:

• line_width (a number or None) – The new line width, in pixels.

• dash_length (a number or None) – The new dash length, in pixels.

set_size(size)

Set the size.

Both pixel and angular sizes are accepted, but both values must match.

Signs will be ignored; only the magnitudes of the values will be used.

Parameters:

size (a pair of numbers or size strings) – The new size.

property size

The size, in pixels.

Returns:

• number – The width.

• number – The height.

property wcs_size

The size, in angular size units.

Returns:

• string – The width.

• string – The height.

class carta.region.HasVerticesMixin

Bases: object

This is a mixin class for regions which are defined by an arbitrary number of vertices (polygons and polylines). It assumes that all control points of the region should be interpreted as coordinates.

property center

The geometric center, in image coordinates.

This overrides the native behaviour of the frontend (which returns the center point of the region bounding box).

Returns:

• number – The X coordinate of the geometric center.

• number – The Y coordinate of the geometric center.

rotate(rotation)

Rotate this region anticlockwise by the angle provided.

Polygonal and polyline regions do not store a separate rotation property, and cannot be rotated natively. The rotation provided will be applied to each vertex relative to the geometric center of the region.

Parameters:

rotation (a number) – The rotation to apply, in degrees.

set_center(center)

Set the geometric center.

Each vertex in the region will be translated by the difference between the current geometric center and the position provided, so that the relative positions of the vertices are preserved.

Both image and world coordinates are accepted, but both values must match.

Parameters:

center (a pair of numbers or coordinate strings) – The new center position.

set_size(size)

Set the size.

The size of a polygon or polyline region is computed as the size of its bounding box.

The region will be scaled to the size provided, with the geometric center preserved.

Both pixel and angular sizes are accepted, but both values must match.

Signs will be ignored; only the magnitudes of the values will be used.

This function will have no effect if any component of either the existing size or the provided size is zero.

Parameters:

size (a pair of numbers or size strings) – The new width and height, in that order.

set_vertex(index, point)

Update the value of a single vertex.

Parameters:

• index (a number) – The index of the vertex to update.

• point (a pair of numbers or coordinate strings) – The new value for the vertex, in image or world coordinates.

set_vertices(points)

Update all the vertices.

Both image and world coordinates are accepted, but all values must match.

Parameters:

points (an iterable with at least 3 elements in which each element is a pair of numbers or an iterable with at least 3 elements in which each element is a pair of coordinate strings) – The new vertices, in image or world coordinates.

property vertices

The vertices, in image coordinates.

This is an alias of carta.region.Region.control_points.

Returns:

The vertices.

Return type:

iterable of tuples of two numbers

property wcs_vertices

The vertices, in world coordinates.

Returns:

The vertices.

Return type:

iterable of tuples of two strings

class carta.region.LineRegion(region_set, region_id)

Bases: HasEndpointsMixin, HasRotationMixin, HasSizeMixin, Region

A line region or annotation.

REGION_TYPES = (RegionType.LINE, RegionType.ANNLINE)

The region types corresponding to this class.

as_polyline(oversampling=False, density=10, delete=False)

Create a new polyline region with the same dimensions and style as this line region or annotation.

This function does not delete the original region by default. Also see carta.region.LineRegion.to_polyline.

Parameters:

• oversampling (a boolean or None) – Whether to add more vertices to the polyline, using the configured per-degree density. By default the polyline will only have three vertices: the endpoints and the center.

• density (a number greater than 0 or None) – The approximate number of vertices to add per degree of the line length (the default is 10). Vertices will divide the line into equal segments. This parameter is ignored if oversampling is disabled.

• delete (a boolean or None) – Whether to delete the original region.

Returns:

A new region object.

Return type:

carta.region.PolylineRegion object

to_polyline(oversampling=False, density=10, delete=True)

Create a new polyline region with the same dimensions and style as this line region or annotation.

This function is a convenience wrapper around carta.region.LineRegion.as_polyline that deletes the original region by default.

Parameters:

• oversampling (a boolean or None) – Whether to add more vertices to the polyline, using the configured per-degree density. By default the polyline will only have three vertices: the endpoints and the center.

• density (a number greater than 0 or None) – The approximate number of vertices to add per degree of the line length (the default is 10). Vertices will divide the line into equal segments. This parameter is ignored if oversampling is disabled.

• delete (a boolean or None) – Whether to delete the original region.

Returns:

A new region object.

Return type:

carta.region.PolylineRegion object

class carta.region.PointAnnotation(region_set, region_id)

Bases: Region

A point annotation.

REGION_TYPES = (RegionType.ANNPOINT,)

The region types corresponding to this class.

property point_shape

The point shape.

Returns:

The point shape.

Return type:

carta.constants.PointShape object

property point_width

The point width.

Returns:

The point width, in pixels.

Return type:

number

set_point_style(point_shape=None, point_width=None)

Set the point style.

All parameters are optional. Omitted properties will be left unmodified.

Parameters:

• point_shape (a member of carta.constants.PointShape or None) – The point shape.

• point_width (a number or None) – The point width, in pixels.

class carta.region.PolygonRegion(region_set, region_id)

Bases: HasVerticesMixin, HasSizeMixin, Region

A polygonal region or annotation.

REGION_TYPES = (RegionType.POLYGON, RegionType.ANNPOLYGON)

The region types corresponding to this class.

class carta.region.PolylineRegion(region_set, region_id)

Bases: HasVerticesMixin, HasSizeMixin, Region

A polyline region or annotation.

REGION_TYPES = (RegionType.POLYLINE, RegionType.ANNPOLYLINE)

The region types corresponding to this class.

class carta.region.RectangularRegion(region_set, region_id)

Bases: HasRotationMixin, HasSizeMixin, Region

A rectangular region or annotation.

REGION_TYPES = (RegionType.RECTANGLE, RegionType.ANNRECTANGLE)

The region types corresponding to this class.

as_polygon(oversampling=False, density=10, delete=False)

Create a new polygonal region with the same dimensions and style as this rectangular region or annotation.

This function does not delete the original region by default. Also see carta.region.RectangularRegion.to_polygon.

Parameters:

• oversampling (a boolean or None) – Whether to add vertices to the sides of the rectangle, using the configured per-degree density. By default the polygon will only have four vertices at the corners.

• density (a number greater than 0 or None) – The approximate number of vertices to add per degree of the rectangle perimeter (the default is 10). Vertices will divide each face into equal segments. This parameter is ignored if oversampling is disabled.

• delete (a boolean or None) – Whether to delete the original region.

Returns:

A new region object.

Return type:

carta.region.PolygonRegion object

property corners

The corner positions, in image coordinates.

Returns:

The bottom-left and top-right corner positions, in image coordinates.

Return type:

iterable containing two tuples of two numbers

set_corners(bottom_left=None, top_right=None)

Update the corner positions.

Both parameters are optional. If a position is omitted, it will not be modified.

The corner positions will be used to calculate the updated center position and size.

Both image and world coordinates are accepted, but both values in each point must match.

Parameters:

• bottom_left (a pair of numbers or coordinate strings or None) – The new bottom-left corner position, in image or world coordinates.

• top_right (a pair of numbers or coordinate strings or None) – The new top-right corner position, in image or world coordinates.

to_polygon(oversampling=False, density=10, delete=True)

Create a new polygonal region with the same dimensions and style as this rectangular region or annotation.

This function is a convenience wrapper around carta.region.RectangularRegion.as_polygon that deletes the original region by default.

Parameters:

• oversampling (a boolean or None) – Whether to add vertices to the sides of the rectangle, using the configured per-degree density. By default the polygon will only have four vertices at the corners.

• density (a number greater than 0 or None) – The approximate number of vertices to add per degree of the rectangle perimeter (the default is 10). Vertices will divide each face into equal segments. This parameter is ignored if oversampling is disabled.

• delete (a boolean or None) – Whether to delete the original region.

Returns:

A new region object.

Return type:

carta.region.PolygonRegion object

property wcs_corners

The corner positions, in world coordinates.

Returns:

The bottom-left and top-right corner positions, in world coordinates.

Return type:

iterable containing two tuples of two strings

class carta.region.Region(region_set, region_id)

Bases: BasePathMixin

Utility object which provides access to one region associated with an image.

# TODO find out what happens to region IDs when you match/unmatch or delete.

Parameters:

• region_set (carta.region.RegionSet object) – The region set containing this region.

• region_id (integer) – The ID of this region.

Variables:

• region_set (carta.region.RegionSet object) – The region set containing this region.

• region_id (integer) – The ID of this region.

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

CUSTOM_CLASS = {RegionType.LINE: <class 'carta.region.LineRegion'>, RegionType.POLYLINE: <class 'carta.region.PolylineRegion'>, RegionType.RECTANGLE: <class 'carta.region.RectangularRegion'>, RegionType.ELLIPSE: <class 'carta.region.EllipticalRegion'>, RegionType.POLYGON: <class 'carta.region.PolygonRegion'>, RegionType.ANNPOINT: <class 'carta.region.PointAnnotation'>, RegionType.ANNLINE: <class 'carta.region.LineRegion'>, RegionType.ANNPOLYLINE: <class 'carta.region.PolylineRegion'>, RegionType.ANNRECTANGLE: <class 'carta.region.RectangularRegion'>, RegionType.ANNELLIPSE: <class 'carta.region.EllipticalRegion'>, RegionType.ANNPOLYGON: <class 'carta.region.PolygonRegion'>, RegionType.ANNVECTOR: <class 'carta.region.VectorAnnotation'>, RegionType.ANNRULER: <class 'carta.region.RulerAnnotation'>, RegionType.ANNTEXT: <class 'carta.region.TextAnnotation'>, RegionType.ANNCOMPASS: <class 'carta.region.CompassAnnotation'>}

Mapping of carta.constants.RegionType types to region and annotation classes. This mapping is used to select the appropriate subclass when a region or annotation object is constructed in the wrapper.

property center

The center position, in image coordinates.

Returns:

• number – The X coordinate of the center position.

• number – The Y coordinate of the center position.

property color

The color.

Returns:

The color.

Return type:

string

property control_points

The control points.

Returns:

The control points, in pixels.

Return type:

iterable of tuples of two numbers

delete()

Delete this region.

classmethod existing(region_type, region_set, region_id)

Create a region object corresponding to an existing region.

This is an internal helper method which should not be used directly.

Parameters:

• region_type (a member of carta.constants.RegionType) – The region type.

• region_set (an instance of carta.region.RegionSet) – The region set containing the region.

• region_id (a number) – The ID of the region.

Returns:

The region object.

Return type:

carta.region.Region object

export_to(path, coordinate_type=CoordinateType.WORLD, file_type=FileType.CRTF)

Export this region into a file.

Parameters:

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

• coordinate_type (a member of carta.constants.CoordinateType) – The coordinate type to use (world coordinates by default).

• file_type (one of 1, 2) – The region file type to use (CRTF by default).

focus()

Center the image view on this region.

classmethod from_list(region_set, region_list)

Create region objects corresponding to a list of existing regions in a single region set.

This is an internal helper method which should not be used directly.

Parameters:

• region_set (an instance of carta.region.RegionSet) – The region set which contains these regions.

• region_list (an iterable in which each element is a dictionary in which each key is a string and each value is a number) – A list of dictionaries containing region types and IDs.

Returns:

The region objects.

Return type:

iterable of carta.region.Region objects

lock()

Lock this region.

property name

The name.

Returns:

The name.

Return type:

string

classmethod new(region_set, region_type, points, rotation=0, name='')

Create a new region.

This is an internal helper method which should not be used directly.

Parameters:

• region_set (an instance of carta.region.RegionSet) – The region set in which to create this region.

• region_type (a member of carta.constants.RegionType) – The region type.

• points (an iterable in which each element is a pair of numbers) – The control points, in pixels. These may be coordinates or sizes; how they are interpreted depends on the region type.

• rotation (a number) – The rotation, in degrees. Defaults to zero.

• name (a string) – The name. Defaults to the empty string.

Returns:

The region object.

Return type:

carta.region.Region object

classmethod region_class(region_type)

The region class associated for this type.

Not every type maps to a specific class; some types have no specific functionality and use the default carta.region.Region class.

Parameters:

region_type (a member of carta.constants.RegionType) – The region type.

Returns:

The region class.

Return type:

class object

property region_type

The region type. This value is transparently cached on the parent object.

Returns:

The type.

Return type:

carta.constants.RegionType object

set_center(center)

Set the center position.

Both image and world coordinates are accepted, but both values must match.

Parameters:

center (a pair of numbers or coordinate strings) – The new center position.

set_color(color)

Set the color.

Parameters:

color (an HTML color specification) – The new color.

set_control_point(index, point)

Update the value of a single control point.

Parameters:

• index (a number) – The index of the control point to update.

• point (a pair of numbers) – The new value for the control point, in pixels.

set_control_points(points)

Update all the control points.

Parameters:

points (an iterable in which each element is a pair of numbers) – The new control points, in pixels.

set_name(name)

Set the name.

Parameters:

name (a string) – The new name.

translate(delta)

Translate the region by the measurement provided.

Both pixel and angular measurements are accepted, but both values must match.

Parameters:

delta (a pair of numbers or size strings) – The translation distance.

unlock()

Unlock this region.

property wcs_center

The center position, in world coordinates.

Returns:

• string – The X coordinate of the center position.

• string – The Y coordinate of the center position.

class carta.region.RegionSet(image)

Bases: BasePathMixin

Utility object for collecting region-related image functions.

Parameters:

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

Variables:

• image (carta.image.Image object) – The image associated with this region set.

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

add_compass(center, length, name='')

Add a new compass annotation to this image.

Parameters:

• center (a pair of numbers or coordinate strings) – The origin position of the compass.

• length (a number) – The length of the compass points, in pixels.

• name (a string) – The name. Defaults to the empty string.

Returns:

A new region object.

Return type:

carta.region.CompassAnnotation object

add_ellipse(center, semi_axes, rotation=0, annotation=False, name='')

Add a new elliptical region or elliptical annotation to this image with the center point and semi-axes provided.

Parameters:

• center (a pair of numbers or coordinate strings) – The center position.

• semi_axes (a pair of numbers or size strings) – The semi-axes. The two values will be interpreted as the north-south and east-west axes, respectively.

• rotation (a number) – The rotation, in degrees. Defaults to zero.

• annotation (a boolean) – Whether this region should be an annotation. Defaults to False.

• name (a string) – The name. Defaults to the empty string.

Returns:

A new region object.

Return type:

carta.region.EllipticalRegion object

add_ellipse_from_corners(bottom_left, top_right, rotation=0, annotation=False, name='')

Add a new elliptical region or elliptical annotation to this image with the bottom-left and top-right corners provided.

Parameters:

• bottom_left (a pair of numbers or coordinate strings) – The bottom-left corner position.

• top_right (a pair of numbers or size strings) – The top-right corner position.

• rotation (a number) – The rotation, in degrees. Defaults to zero.

• annotation (a boolean) – Whether this region should be an annotation. Defaults to False.

• name (a string) – The name. Defaults to the empty string.

Returns:

A new region object.

Return type:

carta.region.EllipticalRegion object

add_ellipse_from_size(center, size, rotation=0, annotation=False, name='')

Add a new elliptical region or elliptical annotation to this image with the center point and size provided.

The width and height will be used to calculate the semi-axes: the north-south semi-axis is equal to half of the height, and the east-west semi-axis is equal to half of the width.

Parameters:

• center (a pair of numbers or coordinate strings) – The center position.

• size (a pair of numbers or size strings) – The size. The two values will be interpreted as the width and height, respectively.

• rotation (a number) – The rotation, in degrees. Defaults to zero.

• annotation (a boolean) – Whether this region should be an annotation. Defaults to False.

• name (a string) – The name. Defaults to the empty string.

Returns:

A new region object.

Return type:

carta.region.EllipticalRegion object

add_line(start, end, annotation=False, name='')

Add a new line region or line annotation to this image.

Parameters:

• start (a pair of numbers or coordinate strings) – The start position.

• end (a pair of numbers or coordinate strings) – The end position.

• annotation (a boolean) – Whether this region should be an annotation. Defaults to False.

• name (a string) – The name. Defaults to the empty string.

Returns:

A new region object.

Return type:

carta.region.LineRegion object

add_point(center, annotation=False, name='')

Add a new point region or point annotation to this image.

Parameters:

• center (a pair of numbers or coordinate strings) – The center position.

• annotation (a boolean) – Whether the region should be an annotation. Defaults to False.

• name (a string) – The name. Defaults to the empty string.

Returns:

A new region object.

Return type:

carta.region.Region or carta.region.PointAnnotation object

add_polygon(points, annotation=False, name='')

Add a new polygonal region or polygonal annotation to this image.

Parameters:

• points (an iterable with at least 3 elements in which each element is a pair of numbers or an iterable with at least 3 elements in which each element is a pair of coordinate strings) – The positions of the vertices, either all in world coordinates or all in image coordinates.

• annotation (a boolean) – Whether this region should be an annotation. Defaults to False.

• name (a string) – The name. Defaults to the empty string.

Returns:

A new region object.

Return type:

carta.region.PolygonRegion object

add_polyline(points, annotation=False, name='')

Add a new polyline region or polyline annotation to this image.

Parameters:

• points (an iterable with at least 3 elements in which each element is a pair of numbers or an iterable with at least 3 elements in which each element is a pair of coordinate strings) – The positions of the vertices, either all in world coordinates or all in image coordinates.

• annotation (a boolean) – Whether this region should be an annotation. Defaults to False.

• name (a string) – The name. Defaults to the empty string.

Returns:

A new region object.

Return type:

carta.region.PolylineRegion object

add_rectangle(center, size, rotation=0, annotation=False, name='')

Add a new rectangular region or rectangular annotation to this image with the center point and size provided.

Parameters:

• center (a pair of numbers or coordinate strings) – The center position.

• size (a pair of numbers or size strings) – The size. The two values will be interpreted as the width and height, respectively.

• rotation (a number) – The rotation, in degrees. Defaults to zero.

• annotation (a boolean) – Whether this region should be an annotation. Defaults to False.

• name (a string) – The name. Defaults to the empty string.

Returns:

A new region object.

Return type:

carta.region.RectangularRegion object

add_rectangle_from_corners(bottom_left, top_right, rotation=0, annotation=False, name='')

Add a new rectangular region or rectangular annotation to this image with the bottom-left and top-right corners provided.

Parameters:

• bottom_left (a pair of numbers or coordinate strings) – The bottom-left corner position.

• top_right (a pair of numbers or coordinate strings) – The top-right corner position.

• rotation (a number) – The rotation, in degrees. Defaults to zero.

• annotation (a boolean) – Whether this region should be an annotation. Defaults to False.

• name (a string) – The name. Defaults to the empty string.

Returns:

A new region object.

Return type:

carta.region.RectangularRegion object

add_region(region_type, points, rotation=0, name='')

Add a new region or annotation to this image.

This is a generic low-level function. Also see the higher-level functions for adding regions of specific types, such as carta.region.RegionSet.add_point.

Parameters:

• region_type (a member of carta.constants.RegionType) – The type of the region.

• points (an iterable in which each element is a pair of numbers) – The control points defining the region, in image coordinates. How these values are interpreted depends on the region type.

• rotation (a number) – The rotation of the region, in degrees. Defaults to zero.

• name (a string) – The name of the region. Defaults to the empty string.

add_ruler(start, end, name='')

Add a new ruler annotation to this image.

Parameters:

• start (a pair of numbers or coordinate strings) – The start position.

• end (a pair of numbers or coordinate strings) – The end position.

• name (a string) – The name. Defaults to the empty string.

Returns:

A new region object.

Return type:

carta.region.RulerAnnotation object

add_text(center, size, text, rotation=0, name='')

Add a new text annotation to this image.

Parameters:

• center (a pair of numbers or coordinate strings) – The center position.

• size (a pair of numbers or size strings) – The size. The two values will be interpreted as the width and height, respectively.

• text (a string) – The text content to display.

• rotation (a number) – The rotation, in degrees. Defaults to zero.

• name (a string) – The name. Defaults to the empty string.

Returns:

A new region object.

Return type:

carta.region.TextAnnotation object

add_vector(start, end, name='')

Add a new vector annotation to this image.

Parameters:

• start (a pair of numbers or coordinate strings) – The start position.

• end (a pair of numbers or coordinate strings) – The end position.

• name (a string) – The name. Defaults to the empty string.

Returns:

A new region object.

Return type:

carta.region.VectorAnnotation object

clear()

Delete all regions except for the cursor region.

export_to(path, coordinate_type=CoordinateType.WORLD, file_type=FileType.CRTF, region_ids=None)

Export regions from this image into a file.

Parameters:

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

• coordinate_type (a member of carta.constants.CoordinateType) – The coordinate type to use (world coordinates by default).

• file_type (one of 1, 2) – The region file type to use (CRTF by default).

• region_ids (an iterable in which each element is a number or None) – The region IDs to include. By default all regions will be included (except the cursor).

get(region_id)

Return the region with the given region ID.

Parameters:

region_id (a number) – The region ID.

Returns:

The region with the given ID.

Return type:

carta.region.Region object

Raises:

ValueError – If there is no region with the given ID.

import_from(path)

Import regions into this image from a file.

Parameters:

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

Raises:

CartaActionFailed – If the file does not exist or is not a region file.

list(ignore_cursor=True)

Return the list of regions associated with this image.

Parameters:

ignore_cursor (a boolean or None) – Ignore the cursor region. This is set by default.

Return type:

list of carta.region.Region objects.

class carta.region.RulerAnnotation(region_set, region_id)

Bases: HasFontMixin, HasEndpointsMixin, HasRotationMixin, HasSizeMixin, Region

A ruler annotation.

REGION_TYPES = (RegionType.ANNRULER,)

The region types corresponding to this class.

property auxiliary_lines_dash_length

The dash length of the auxiliary lines.

Returns:

The dash length of the auxiliary lines, in pixels.

Return type:

number

property auxiliary_lines_visible

The visibility of the auxiliary lines.

Returns:

Whether the auxiliary lines are visible.

Return type:

boolean

set_auxiliary_lines_style(visible=None, dash_length=None)

Set the auxiliary line style.

All parameters are optional. Omitted properties will be left unmodified.

Parameters:

• visible (a boolean or None) – Whether the auxiliary lines should be visible.

• dash_length (a number or None) – The dash length of the auxiliary lines, in pixels.

set_text_offset(offset_x=None, offset_y=None)

Set the text offset.

All parameters are optional. Omitted properties will be left unmodified.

Parameters:

• offset_x (a number or None) – The X offset of the text, in pixels.

• offset_y (a number or None) – The Y offset of the text, in pixels.

property text_offset

The X and Y text offsets.

Returns:

• number – The X offset of the text, in pixels.

• number – The Y offset of the text, in pixels.

class carta.region.TextAnnotation(region_set, region_id)

Bases: HasFontMixin, HasRotationMixin, HasSizeMixin, Region

A text annotation.

REGION_TYPES = (RegionType.ANNTEXT,)

The region types corresponding to this class.

property position

The position of the text in this annotation.

Returns:

The text position.

Return type:

carta.constants.TextPosition

set_text(text)

Set the text content.

Parameters:

text (a string) – The text content.

set_text_position(text_position)

Set the position of the text in this annotation.

Parameters:

text_position (a member of carta.constants.TextPosition) – The position of the text.

property text

The text content.

Returns:

The text content.

Return type:

string

class carta.region.VectorAnnotation(region_set, region_id)

Bases: HasPointerMixin, HasEndpointsMixin, HasRotationMixin, HasSizeMixin, Region

A vector annotation.

REGION_TYPES = (RegionType.ANNVECTOR,)

The region types corresponding to this class.

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:

• carta.session.Session.interact for interacting with an existing CARTA session open in the user’s browser.

• carta.session.Session.start_and_interact for starting a new backend instance and then interacting with the default session which is automatically opened by the backend in the user’s browser.

• carta.session.Session.create for creating a new CARTA session in a headless browser by connecting to an existing CARTA backend or controller instance.

• carta.session.Session.start_and_create for starting a new backend instance and then connecting to it to create a new session in a headless browser.

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

Parameters:

• session_id (integer) – The ID of the CARTA frontend session associated with this object. This is set automatically when a new session is created with carta.session.Session.create or carta.session.Session.start_and_create.

• protocol (carta.protocol.Protocol) – The protocol object which handles HTTP communication with the CARTA scripting API. This is created automatically when a new session is created with one of the three class methods for creating sessions.

• browser (carta.browser.Browser) – The browser object associated with this session. This is created automatically when a new session is created with carta.session.Session.create or carta.session.Session.start_and_create.

• backend (carta.backend.Backend) – The backend object associated with this session. This is created automatically when a new session is created with carta.session.Session.start_and_create.

Variables:

• session_id (integer) – The ID of the CARTA frontend session associated with this object.

• wcs (carta.wcs_overlay.SessionWCSOverlay) – Sub-object with functions related to the WCS overlay.

• raster (carta.raster.SessionRaster) – Sub-object with functions related to the global raster image settings.

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:

• CartaBadRequest – If the request was invalid.

• CartaRequestFailed – If the backend could not send the request to the frontend.

• CartaActionFailed – If the action failed.

• CartaBadResponse – If a request which was expected to have a JSON response did not have one, or if a JSON response could not be decoded.

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:

• CartaBadToken – If an invalid token was provided.

• CartaBadUrl – If an invalid URL was provided.

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

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:

• CartaBadID – If the ID provided cannot be converted to an integer

• CartaBadToken – If an invalid token was provided.

• CartaBadUrl – If an invalid URL was provided.

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

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. There is also a frontend issue which is preventing the cursor from being updated correctly (it is updated only in the profiles).

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:

• CartaBadToken – If an invalid token was provided.

• CartaBadUrl – If an invalid URL was provided.

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

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.

as_cookie(domain)

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'>}

A mapping of units to angular size subclasses.

NAME = 'angular size'

A descriptive name.

SYMBOL_UNIT_REGEX = '^(-?\\d+(?:\\.\\d+)?)(|′|\'|"|″)$'

All recognised input units which are a single character long.

WORD_UNIT_REGEX = '^(-?\\d+(?:\\.\\d+)?)\\s*(uas|arcmin|arcminute|milliarcseconds|amin|degrees|deg|milliarcsecond|asec|arcminutes|microarcsecond|microarcseconds|µas|arcsecond|milliarcsec|degree|arcsec|arcseconds|microarcsec|mas)$'

All recognised input units which are multiple characters long.

property arcsec

The numeric value in arcseconds.

Returns:

The numeric value of this angular size, in arcseconds.

Return type:

float

classmethod from_arcsec(arcsec)

Construct an angular size object from a numeric value in arcseconds.

If this method is called on the parent carta.units.AngularSize class, it will automatically guess the most appropriate unit subclass. If it is called on a unit subclass, it will return an instance of that subclass.

Parameters:

arcsec (float) – The angular size in arcseconds.

Returns:

The angular size object.

Return type:

carta.units.AngularSize object

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.

ARCSEC_FACTOR = 60

The scaling factor to use when converting the value to arcseconds.

FACTOR = 1

The scaling factor to use when representing the value using the output unit.

INPUT_UNITS = {"'", 'amin', 'arcmin', 'arcminute', 'arcminutes', '′'}

All recognised input unit strings.

NAME = 'arcminute'

A descriptive name.

OUTPUT_UNIT = "'"

The canonical output unit string.

SYMBOL_UNIT_REGEX = "^(-?\\d+(?:\\.\\d+)?)(′|')$"

All recognised input units which are a single character long.

WORD_UNIT_REGEX = '^(-?\\d+(?:\\.\\d+)?)\\s*(amin|arcmin|arcminutes|arcminute)$'

All recognised input units which are multiple characters long.

class carta.units.ArcsecSize(value)

Bases: AngularSize

An angular size in arcseconds.

ARCSEC_FACTOR = 1

The scaling factor to use when converting the value to arcseconds.

FACTOR = 1

The scaling factor to use when representing the value using the output unit.

INPUT_UNITS = {'', '"', 'arcsec', 'arcsecond', 'arcseconds', 'asec', '″'}

All recognised input unit strings.

NAME = 'arcsecond'

A descriptive name.

OUTPUT_UNIT = '"'

The canonical output unit string.

SYMBOL_UNIT_REGEX = '^(-?\\d+(?:\\.\\d+)?)(|"|″)$'

All recognised input units which are a single character long.

WORD_UNIT_REGEX = '^(-?\\d+(?:\\.\\d+)?)\\s*(arcsecond|arcsec|arcseconds|asec)$'

All recognised input units which are multiple characters long.

class carta.units.DMSCoordinate(hours_or_degrees, minutes, seconds)

Bases: SexagesimalCoordinate

A world coordinate in DMS format.

FMT = 'dms'

The number format.

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

All recognised input string formats.

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:

• value (string) – The input string.

• axis (carta.constants.SpatialAxis) – The spatial axis of this coordinate.

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'}

All recognised degree units.

FMT = 'd'

The number format.

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

All recognised input string formats.

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:

• value (string) – The input string.

• axis (carta.constants.SpatialAxis) – The spatial axis of this coordinate.

Returns:

The coordinate object.

Return type:

carta.util.DegreesCoordinate

class carta.units.DegreesSize(value)

Bases: AngularSize

An angular size in degrees.

ARCSEC_FACTOR = 3600

The scaling factor to use when converting the value to arcseconds.

FACTOR = 1

The scaling factor to use when representing the value using the output unit.

INPUT_UNITS = {'deg', 'degree', 'degrees'}

All recognised input unit strings.

NAME = 'degree'

A descriptive name.

OUTPUT_UNIT = 'deg'

The canonical output unit string.

SYMBOL_UNIT_REGEX = '^(-?\\d+(?:\\.\\d+)?)()$'

All recognised input units which are a single character long.

WORD_UNIT_REGEX = '^(-?\\d+(?:\\.\\d+)?)\\s*(degrees|deg|degree)$'

All recognised input units which are multiple characters long.

class carta.units.HMSCoordinate(hours_or_degrees, minutes, seconds)

Bases: SexagesimalCoordinate

A world coordinate in HMS format.

FMT = 'hms'

The number format.

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)?$'}

All recognised input string formats.

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:

• value (string) – The input string.

• axis (carta.constants.SpatialAxis) – The spatial axis of this coordinate.

Returns:

The coordinate object.

Return type:

carta.util.HMSCoordinate

class carta.units.MicroarcsecSize(value)

Bases: AngularSize

An angular size in microarcseconds.

ARCSEC_FACTOR = 1e-06

The scaling factor to use when converting the value to arcseconds.

FACTOR = 1e-06

The scaling factor to use when representing the value using the output unit.

INPUT_UNITS = {'microarcsec', 'microarcsecond', 'microarcseconds', 'uas', 'µas'}

All recognised input unit strings.

NAME = 'microarcsecond'

A descriptive name.

OUTPUT_UNIT = '"'

The canonical output unit string.

SYMBOL_UNIT_REGEX = '^(-?\\d+(?:\\.\\d+)?)()$'

All recognised input units which are a single character long.

WORD_UNIT_REGEX = '^(-?\\d+(?:\\.\\d+)?)\\s*(microarcseconds|µas|uas|microarcsecond|microarcsec)$'

All recognised input units which are multiple characters long.

class carta.units.MilliarcsecSize(value)

Bases: AngularSize

An angular size in milliarcseconds.

ARCSEC_FACTOR = 0.001

The scaling factor to use when converting the value to arcseconds.

FACTOR = 0.001

The scaling factor to use when representing the value using the output unit.

INPUT_UNITS = {'mas', 'milliarcsec', 'milliarcsecond', 'milliarcseconds'}

All recognised input unit strings.

NAME = 'milliarcsecond'

A descriptive name.

OUTPUT_UNIT = '"'

The canonical output unit string.

SYMBOL_UNIT_REGEX = '^(-?\\d+(?:\\.\\d+)?)()$'

All recognised input units which are a single character long.

WORD_UNIT_REGEX = '^(-?\\d+(?:\\.\\d+)?)\\s*(milliarcseconds|milliarcsec|milliarcsecond|mas)$'

All recognised input units which are multiple characters long.

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:

• value (string) – The input string.

• axis (carta.constants.SpatialAxis) – The spatial axis of this coordinate.

Returns:

The coordinate object.

Return type:

carta.util.SexagesimalCoordinate

class carta.units.WorldCoordinate

Bases: object

A world coordinate.

FMT = None

The number format.

FORMATS = {NumberFormat.DEGREES: <class 'carta.units.DegreesCoordinate'>, NumberFormat.DMS: <class 'carta.units.DMSCoordinate'>, NumberFormat.HMS: <class 'carta.units.HMSCoordinate'>}

A mapping of number formats to world coordinate subclasses.

classmethod from_string(value, axis)

Construct a world coordinate object from a string.

This is implemented in subclasses corresponding to different formats.

Parameters:

• value (string) – The input string.

• axis (carta.constants.SpatialAxis) – The spatial axis of this coordinate.

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.

class carta.util.Point(x, y)

Bases: object

A pair of coordinates or sizes.

This object may have numeric or string values, and may be used to represent a pair of coordinates or a pair of sizes.

Numbers should be interpreted as pixel values, and strings should be valid WCS coordinates or angular sizes. Different types of values should not be combined.

Functions exposed to the user should accept pairs of points as two-item iterables, and use this object internally to ensure that the correct serialization is sent to the frontend. It is the responsibility of calling functions to ensure that the object is interpreted correctly.

Parameters:

• x (number or string) – The x value.

• y (number or string) – The y value.

as_tuple()

The tuple representation of this object.

This is the format in which these values should be returned to the user.

Returns:

• number or string – The X value.

• number or string – The Y value.

classmethod is_angular_size(x, y)

Whether this is a pair of angular sizes.

Returns:

Whether both values are strings and can be parsed as valid angular sizes.

Return type:

boolean

classmethod is_pixel(x, y)

Whether this is a pair of pixel values.

Returns:

Whether both values are numeric and should be interpreted as pixels.

Return type:

boolean

classmethod is_wcs_coordinate(x, y)

Whether this is a pair of world coordinates.

Returns:

Whether both values are strings and can be parsed as valid world coordinates.

Return type:

boolean

json()

The JSON serialization of this object.

This is the format in which these values should be sent to the frontend.

Returns:

A dictionary which can be coerced to a 2D point object in the frontend after serialization and deserialization.

Return type:

dict

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, required_keys={}, exact_keys=False)

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.Point

Bases: Union

A pair of numbers, WCS coordinate strings, or angular size strings, as an iterable with two values (which will be evaluated as x and y values in that order). Numbers will be interpreted as pixel values.

More fine-grained combinations of value options (numeric only, world coordinate only, angular size only, any coordinate, any size) are provided as local classes which may also be used individually.

The two values must always match (numbers, string coordinates and string sizes can’t be mixed).

class AngularSizePoint

Bases: Union

A pair of angular size strings.

class CoordinatePoint

Bases: Union

A pair of coordinates.

class NumericPoint

Bases: Union

A pair of numbers.

class SizePoint

Bases: Union

A pair of angular sizes.

class WorldCoordinatePoint

Bases: Union

A pair of WCS coordinate strings.

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:

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

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

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:

• 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.

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:

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

• border (carta.wcs_overlay.ColorbarBorder object) – The border subcomponent.

• ticks (carta.wcs_overlay.ColorbarTicks object) – The ticks subcomponent.

• numbers (carta.wcs_overlay.ColorbarNumbers object) – The numbers subcomponent.

• label (carta.wcs_overlay.ColorbarLabel object) – The label subcomponent.

• gradient (carta.wcs_overlay.ColorbarGradient object) – The gradient subcomponent.

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:

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

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

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:

• member of carta.constants.FontFamily – The font family.

• member of carta.constants.FontStyle – The font style.

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:

• font_family (a member of carta.constants.FontFamily or None) – The font family.

• font_style (a member of carta.constants.FontStyle or None) – The font style.

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:

• title (carta.wcs_overlay.ImageWCSOverlay.ImageTitle object) – The title settings subcomponent.

• colorbar (carta.wcs_overlay.ImageWCSOverlay.ImageColorbar object) – The colorbar settings subcomponent.

• beam (carta.wcs_overlay.ImageWCSOverlay.ImageBeam object) – The beam settings subcomponent.

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:

• a member of carta.constants.NumberFormat or None – The X format.

• a member of carta.constants.NumberFormat or None – The Y format.

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:

• format_x (a member of carta.constants.NumberFormat or None) – The X format.

• format_y (a member of carta.constants.NumberFormat or None) – The Y format.

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:

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

• global_ (carta.wcs_overlay.Global object) – The global settings subcomponent.

• title (carta.wcs_overlay.Title object) – The title settings subcomponent.

• grid (carta.wcs_overlay.Grid object) – The grid settings subcomponent.

• border (carta.wcs_overlay.Border object) – The border settings subcomponent.

• ticks (carta.wcs_overlay.Ticks object) – The ticks settings subcomponent.

• axes (carta.wcs_overlay.Axes object) – The axes settings subcomponent.

• numbers (carta.wcs_overlay.Numbers object) – The numbers settings subcomponent.

• labels (carta.wcs_overlay.Labels object) – The labels settings subcomponent.

• colorbar (carta.wcs_overlay.Colorbar object) – The colorbar settings subcomponent.

• beam (carta.wcs_overlay.Beam object) – The beam settings subcomponent.

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