Add ColorBlending module for multi-image blending support

carta/constants.py

@@ -23,6 +23,20 @@ class ComplexComponent(StrEnum):
 Colormap.__doc__ = """All available colormaps."""
 
 
+class ColormapSet(StrEnum):
+    """Colormap sets for color blending."""
+    RGB = "RGB"
+    CMY = "CMY"
+    RAINBOW = "Rainbow"
+
+
+class ImageType(IntEnum):
+    """Image view item types, corresponding to the frontend ImageType enum."""
+    FRAME = 0
+    COLOR_BLENDING = 1
+    PV_PREVIEW = 2
+
+
 Scaling = IntEnum('Scaling', ('LINEAR', 'LOG', 'SQRT', 'SQUARE', 'POWER', 'GAMMA'), start=0)
 Scaling.__doc__ = """Colormap scaling types."""
 

carta/image.py

@@ -9,7 +9,6 @@
 from .units import AngularSize, WorldCoordinate
 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
@@ -256,7 +255,7 @@ def polarizations(self):
 
     def make_active(self):
         """Make this the active image."""
-        self.session.call_action("setActiveFrameById", self.image_id)
+        self.session.call_action("setActiveImageByFileId", self.image_id)
 
     def make_spatial_reference(self):
         """Make this image the spatial reference."""
@@ -362,7 +361,7 @@ def valid_wcs(self):
     def set_center(self, 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 :obj:`carta.session.set_coordinate_system` and :obj:`set_custom_number_format`.
+        World coordinates are interpreted according to the session's globally set coordinate system and any custom number formats. These can be changed using :obj:`carta.wcs_overlay.Global.set_coordinate_system` and :obj:`carta.wcs_overlay.Numbers.set_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.
 

carta/session.py

@@ -10,6 +10,7 @@
 import posixpath
 
 from .image import Image
+from .colorblending import ColorBlending
 from .constants import PanelMode, GridMode, ComplexComponent, Polarization
 from .backend import Backend
 from .protocol import Protocol
@@ -520,6 +521,19 @@ def image_list(self):
         """
         return Image.from_list(self, self.get_value("frameNames"))
 
+    def color_blending_list(self):
+        """Return the list of currently open color blending objects.
+
+        Returns
+        -------
+        list of :obj:`carta.colorblending.ColorBlending` objects
+            The list of color blending objects open in this session.
+        """
+        path = "imageViewConfigStore.colorBlendingImages"
+        length = self.get_value(f"{path}.length")
+        store_ids = [self.get_value(f"{path}[{idx}].id") for idx in range(length)]
+        return [ColorBlending(self, store_id) for store_id in store_ids]
+
     def active_frame(self):
         """Return the currently active image.
 

docs/source/carta.rst

@@ -17,6 +17,14 @@ carta.browser module
    :undoc-members:
    :show-inheritance:
 
+carta.colorblending module
+--------------------------
+
+.. automodule:: carta.colorblending
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
 carta.constants module
 ----------------------
 

docs/source/quickstart.rst

@@ -171,8 +171,9 @@ Helper methods on the session object open images in the frontend and return imag
 .. code-block:: python
 
     # Open or append images
-    img1 = session.open_image("data/hdf5/first_file.hdf5")
-    img2 = session.open_image("data/fits/second_file.fits", append=True)
+    img0 = session.open_image("data/hdf5/first_file.hdf5")
+    img1 = session.open_image("data/fits/second_file.fits", append=True)
+    img2 = session.open_image("data/fits/third_file.fits", append=True)
 
 Changing image properties
 -------------------------
@@ -192,7 +193,7 @@ Properties specific to individual images can be accessed through image objects:
     # pan and zoom
     y, x = img.shape[-2:]
     img.set_center(x/2, y/2)
-    img.set_zoom(4)
+    img.set_zoom_level(4)
 
     # change colormap
     img.raster.set_colormap(Colormap.VIRIDIS)
@@ -225,7 +226,117 @@ Properties which affect the whole session can be set through the session object:
     session.wcs.global_.set_color(PaletteColor.RED)
     session.wcs.ticks.set_color(PaletteColor.VIOLET)
     session.wcs.title.show()
-
+
+Making color blended image
+--------------------------
+
+Create a color blending object from a list of files:
+
+.. code-block:: python
+
+    from carta.colorblending import ColorBlending
+    from carta.constants import Colormap, ColormapSet
+
+    # Make a color blending object
+    # Warning: setting `append=False` will close any existing images
+    # Note: The base layer (index = 0) cannot be deleted or moved.
+    files = [
+        "data/hdf5/first_file.hdf5",
+        "data/fits/second_file.fits",
+        "data/fits/third_file.fits",
+    ]
+    cb = ColorBlending.from_files(session, files, append=False)
+
+Create a color blending object from a list of images:
+
+.. code-block:: python
+
+    from carta.colorblending import ColorBlending
+    from carta.constants import Colormap, ColormapSet
+
+    # Make a color blending object
+    # Warning: This will break the current spatial matching and
+    #          use the first image as the spatial reference
+    # Note: The base layer (index = 0) cannot be deleted or moved.
+    cb = ColorBlending.from_images(session, [img0, img1, img2])
+
+To work with color blending images that are already open in a session, use
+the session helper:
+
+.. code-block:: python
+
+    # Get all open color blending objects in this session
+    color_blendings = session.color_blending_list()
+    cb = color_blendings[0]
+
+    # Or get a color blending object by its image view index
+    cb = ColorBlending.from_imageview_id(session, 3)
+
+.. note::
+    The ``ColorBlending`` constructor takes the internal color blending store ID,
+    not the image view index. Use ``ColorBlending.from_files``,
+    ``ColorBlending.from_images``, ``ColorBlending.from_imageview_id`` or
+    ``session.color_blending_list`` in scripts.
+
+Manipulate properties of the color blending object and the underlying images:
+
+.. code-block:: python
+
+    # Get layer objects
+    layers = cb.layer_list()
+
+    # Set colormap for individual layers
+    layers[0].set_colormap(Colormap.REDS)
+    layers[1].set_colormap(Colormap.GREENS)
+    layers[2].set_colormap(Colormap.BLUES)
+
+    # Or apply an existing colormap set
+    cb.set_colormap_set(ColormapSet.RGB)
+
+    # Print the current alpha values of all layers
+    print(cb.alpha)
+
+    # Set alpha for individual layers
+    layers[0].set_alpha(0.7)
+    layers[1].set_alpha(0.8)
+    layers[2].set_alpha(0.9)
+
+    # Or set alpha for all layers at once
+    cb.set_alpha([0.7, 0.8, 0.9])
+
+    # Set which layers to keep, and in what order
+    # The first layer index must be the base layer (index = 0)
+    # Since the base layer cannot be moved,
+    # the layers will be reordered as [img0, img2, img1]
+    cb.set_layer_sequence([0, 2, 1])
+
+    # Remove the last layer (index = 2)
+    cb.delete_layer(2)
+
+    # Add a new layer
+    # The layer to be added cannot be one of the current layers
+    cb.add_layer(img1)
+
+    # Set center
+    cb.set_center(100, 100)
+
+    # Set zoom level
+    cb.set_zoom_level(2)
+
+    # Set the color blending object as the active frame
+    cb.make_active()
+
+    # Set contour visibility
+    # This will hide the contours (if any)
+    cb.set_contour_visible(False)
+
+    # Close the color blending object
+    cb.close()
+
+.. note::
+    If you need to change the layer order involving the base layer (index = 0),
+    close the current color blending object and create a new one.
+
 Saving or displaying an image
 -----------------------------