Basic region support

carta/constants.py

@@ -216,6 +216,89 @@ class GridMode(StrEnum):
     FIXED = "fixed"
 
 
+class FileType(IntEnum):
+    """File types corresponding to the protobuf enum."""
+    CASA = 0
+    CRTF = 1
+    DS9_REG = 2
+    FITS = 3
+    HDF5 = 4
+    MIRIAD = 5
+    UNKNOWN = 6
+
+
+class RegionType(IntEnum):
+    """Region types corresponding to the protobuf enum."""
+
+    def __init__(self, value):
+        self.is_annotation = self.name.startswith("ANN")
+        self.label = f"{self.name[3:].title()} - Ann" if self.is_annotation else self.name.title()
+
+    POINT = 0
+    LINE = 1
+    POLYLINE = 2
+    RECTANGLE = 3
+    ELLIPSE = 4
+    # ANNULUS = 5 is not actually implemented
+    POLYGON = 6
+    ANNPOINT = 7
+    ANNLINE = 8
+    ANNPOLYLINE = 9
+    ANNRECTANGLE = 10
+    ANNELLIPSE = 11
+    ANNPOLYGON = 12
+    ANNVECTOR = 13
+    ANNRULER = 14
+    ANNTEXT = 15
+    ANNCOMPASS = 16
+
+
+class CoordinateType(IntEnum):
+    """Coordinate types corresponding to the protobuf enum."""
+    PIXEL = 0
+    WORLD = 1
+
+
+class PointShape(IntEnum):
+    """Point annotation shapes corresponding to the protobuf enum."""
+    SQUARE = 0
+    BOX = 1
+    CIRCLE = 2
+    CIRCLE_LINED = 3
+    DIAMOND = 4
+    DIAMOND_LINED = 5
+    CROSS = 6
+    X = 7
+
+
+class TextPosition(IntEnum):
+    """Text annotation positions corresponding to the protobuf enum."""
+    CENTER = 0
+    UPPER_LEFT = 1
+    UPPER_RIGHT = 2
+    LOWER_LEFT = 3
+    LOWER_RIGHT = 4
+    TOP = 5
+    BOTTOM = 6
+    LEFT = 7
+    RIGHT = 8
+
+
+class AnnotationFontStyle(StrEnum):
+    """Font styles which may be used in annotations."""
+    NORMAL = "Normal"
+    BOLD = "Bold"
+    ITALIC = "Italic"
+    BOLD_ITALIC = "Italic Bold"
+
+
+class AnnotationFont(StrEnum):
+    """Fonts which may be used in annotations."""
+    HELVETICA = "Helvetica"
+    TIMES = "Times"
+    COURIER = "Courier"
+
+
 class FontFamily(IntEnum):
     """Font family used in WCS overlay components."""
     SANS_SERIF = 0

carta/image.py

@@ -3,16 +3,18 @@
 Image objects should not be instantiated directly, and should only be created through methods on the :obj:`carta.session.Session` object.
 """
 
+
 from .constants import Polarization, SpatialAxis, SpectralSystem, SpectralType, SpectralUnit
-from .util import Macro, cached, BasePathMixin
+from .util import Macro, cached, BasePathMixin, Point as Pt
 from .units import AngularSize, WorldCoordinate
-from .validation import validate, Number, Constant, Boolean, Evaluate, Attr, Attrs, OneOf, Size, Coordinate, NoneOr
+from .validation import validate, Number, Constant, Boolean, Evaluate, Attr, Attrs, OneOf, Size, Coordinate, NoneOr, IterableOf, Point
 from .metadata import parse_header
 
 from .raster import Raster
 from .contours import Contours
 from .vector_overlay import VectorOverlay
 from .wcs_overlay import ImageWCSOverlay
+from .region import RegionSet
 
 
 class Image(BasePathMixin):
@@ -41,6 +43,8 @@ class Image(BasePathMixin):
         Sub-object with functions related to the vector overlay.
     wcs :  :obj:`carta.wcs_overlay.ImageWCSOverlay`
         Sub-object with functions related to the WCS overlay.
+    regions : :obj:`carta.region.RegionSet` object
+        Functions for manipulating regions associated with this image.
     """
 
     def __init__(self, session, image_id):
@@ -55,6 +59,7 @@ def __init__(self, session, image_id):
         self.contours = Contours(self)
         self.vectors = VectorOverlay(self)
         self.wcs = ImageWCSOverlay(self)
+        self.regions = RegionSet(self)
 
     @classmethod
     def new(cls, session, directory, file_name, hdu, append, image_arithmetic, make_active=True, update_directory=False):
@@ -530,6 +535,113 @@ def set_spectral_coordinate(self, spectral_type, spectral_unit=None):
         spectral_coordinate_string = description if spectral_unit is None else f"{description} ({spectral_unit})"
         self.call_action("setSpectralCoordinate", spectral_coordinate_string)
 
+    # COORDINATE AND SIZE CONVERSIONS
+
+    @validate(IterableOf(Point.WorldCoordinatePoint()))
+    def from_world_coordinate_points(self, 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 : {0}
+            Points with string values which are valid world coordinates.
+
+        Returns
+        -------
+        iterable of numeric points
+            Points with numeric values which are image coordinates.
+        """
+        points = [Pt(*p) for p in points]
+        converted_points = self.call_action("getImagePosFromWCS", points)
+        return [Pt(**p).as_tuple() for p in converted_points]
+
+    @validate(IterableOf(Point.NumericPoint()))
+    def to_world_coordinate_points(self, points):
+        """Convert image coordinate points to world coordinate points.
+
+        The points must be numeric.
+
+        Parameters
+        ----------
+        points : {0}
+            Points with numeric values which are valid image coordinates.
+
+        Returns
+        -------
+        iterable of string coordinate points
+            Points with string values which are world coordinates.
+        """
+        points = [Pt(*p) for p in points]
+        converted_points = self.call_action("getWCSFromImagePos", points)
+        return [Pt(**p).as_tuple() for p in converted_points]
+
+    @validate(Size.AngularSize(), Constant(SpatialAxis))
+    def from_angular_size(self, size, axis):
+        """Convert angular size to pixel size.
+
+        Parameters
+        ----------
+        size : {0}
+            The angular size.
+        axis : {1}
+            The axis.
+
+        Returns
+        -------
+        float
+            The pixel size.
+        """
+        arcsec = AngularSize.from_string(size).arcsec
+        if axis == SpatialAxis.X:
+            return self.call_action("getImageXValueFromArcsec", arcsec)
+        if axis == SpatialAxis.Y:
+            return self.call_action("getImageYValueFromArcsec", arcsec)
+
+    @validate(IterableOf(Point.AngularSizePoint()))
+    def from_angular_size_points(self, points):
+        """Convert angular size points to pixel size points.
+
+        The points must have string values which can be parsed as angular sizes.
+
+        Parameters
+        ----------
+        points : {0}
+            Points with string values which are valid angular sizes.
+
+        Returns
+        -------
+        iterable of numeric points
+            Points with numeric values which are pixel sizes.
+        """
+        converted_points = []
+        for x, y in points:
+            converted_points.append((self.from_angular_size(x, SpatialAxis.X), self.from_angular_size(y, SpatialAxis.Y)))
+        return converted_points
+
+    @validate(IterableOf(Point.NumericPoint()))
+    def to_angular_size_points(self, points):
+        """Convert pixel size points to angular size points.
+
+        The points must be numeric.
+
+        Parameters
+        ----------
+        points : {0}
+            Points with numeric values which are valid image coordinates.
+
+        Returns
+        -------
+        iterable of angular size points
+            Points with string values which are angular sizes.
+        """
+        converted_points = []
+        for p in points:
+            converted = self.call_action("getWcsSizeInArcsec", Pt(*p))
+            converted_points.append(Pt(**converted).as_tuple())
+        return converted_points
+
     # CLOSE
 
     def close(self):