lets-plot 4.6.1__cp310-cp310-macosx_11_0_arm64.whl → 4.7.0rc1__cp310-cp310-macosx_11_0_arm64.whl

lets_plot/plot/annotation.py

@@ -14,7 +14,24 @@ __all__ = ['layer_labels']
 
 class layer_labels(FeatureSpec):
     """
-    Configure annotations (for pie and bar charts).
+    Configure annotations for geometry layers.
+
+    Annotations are currently supported for bar, pie, and crossbar geometry
+    layers. This class provides methods to customize the appearance and
+    content of text labels displayed on these geometries.
+
+    Notes
+    -----
+    By default, annotation text color is automatically selected for optimal
+    contrast: white text appears on darker filled geometries, and black text
+    appears on lighter filled geometries.
+
+    The text color can be manually specified using:
+    ``theme(label_text=element_text(color=...))``
+
+    Alternatively, the ``inherit_color()`` method can be used to override both
+    automatic and manual color settings, making the annotation text use the
+    geometry's ``color`` aesthetic instead.
 
     Examples
     --------
@@ -24,9 +41,9 @@ class layer_labels(FeatureSpec):
 
         from lets_plot import *
         LetsPlot.setup_html()
-        data = {'name': ['a', 'b', 'c', 'd', 'b'], 'value': [40, 90, 10, 50, 20 ] }
+        data = {'name': ['a', 'b', 'c', 'd', 'b'], 'value': [40, 90, 10, 50, 20 ]}
         ggplot(data) + geom_pie(aes(slice='value', fill='name'), size=15, hole=0.4, \\
-                                stat='identity', tooltips = 'none', \\
+                                stat='identity', tooltips='none', \\
                                 labels=layer_labels().line('@value'))
 
     """
@@ -46,11 +63,12 @@ class layer_labels(FeatureSpec):
         self._lines: List = None
         self._variables = variables
         self._size = None
+        self._useLayerColor = None
         super().__init__('labels', name=None)
 
     def as_dict(self):
         """
-        Return the dictionary of all properties of the object.
+        Return a dictionary of all properties of the object.
 
         Returns
         -------
@@ -76,6 +94,7 @@ class layer_labels(FeatureSpec):
         d['lines'] = self._lines
         d['variables'] = self._variables
         d['annotation_size'] = self._size
+        d['use_layer_color'] = self._useLayerColor
         return _filter_none(d)
 
     def format(self, field=None, format=None):
@@ -113,7 +132,7 @@ class layer_labels(FeatureSpec):
 
             from lets_plot import *
             LetsPlot.setup_html()
-            data = {'name': ['a', 'b', 'c', 'd', 'b'], 'value': [40, 90, 10, 50, 20 ] }
+            data = {'name': ['a', 'b', 'c', 'd', 'b'], 'value': [40, 90, 10, 50, 20 ]}
             ggplot(data) + geom_pie(aes(fill=as_discrete('name', order_by='..count..'), weight='value'), \\
                                     size=15, tooltips='none', \\
                                     labels=layer_labels(['..proppct..']) \\
@@ -127,7 +146,7 @@ class layer_labels(FeatureSpec):
 
             from lets_plot import *
             LetsPlot.setup_html()
-            data = {'name': ['a', 'b', 'c', 'd', 'b'], 'value': [40, 90, 10, 50, 20 ] }
+            data = {'name': ['a', 'b', 'c', 'd', 'b'], 'value': [40, 90, 10, 50, 20 ]}
             ggplot(data) + geom_pie(aes(fill=as_discrete('name', order_by='..count..', order=1), weight='value'), \\
                                     size=15, tooltips='none', \\
                                     labels=layer_labels() \\
@@ -146,12 +165,17 @@ class layer_labels(FeatureSpec):
 
     def line(self, value):
         """
-        Line to show in the annotation.
+        Add a line of text to the multiline label annotation.
+
+        This method configures one line of text that will be displayed in a
+        multiline label. Multiple calls to this method can be chained to build
+        up a complete multiline annotation.
 
         Parameters
         ----------
         value : str
-            Enriched string which becomes one line of the annotation.
+            The text content for this line of the annotation. Can include
+            variable and aesthetic references.
 
         Returns
         -------
@@ -162,17 +186,16 @@ class layer_labels(FeatureSpec):
         -----
         Variables and aesthetics can be accessed via special syntax:
 
-        - ^color for aes,
+        - ^color for aesthetics,
         - @x for variable,
         - @{x + 1} for variable with spaces in the name,
         - @{x^2 + 1} for variable with spaces and '^' symbol in the name,
         - @x^2 for variable with '^' symbol in its name.
 
-        A '^' symbol can be escaped with a backslash, a brace character
-        in the literal text - by doubling:
+        Special characters can be escaped:
 
-        - 'x\\\\^2' -> "x^2"
-        - '{{x}}' -> "{x}"
+        - 'x\\\\^2' -> "x^2" (escape ^ with backslash)
+        - '{{x}}' -> "{x}" (escape braces by doubling)
 
         Examples
         --------
@@ -182,7 +205,7 @@ class layer_labels(FeatureSpec):
 
             from lets_plot import *
             LetsPlot.setup_html()
-            data = {'name': ['a', 'b', 'c', 'd', 'b'], 'value': [40, 90, 10, 50, 20 ] }
+            data = {'name': ['a', 'b', 'c', 'd', 'b'], 'value': [40, 90, 10, 50, 20 ]}
             ggplot(data) + geom_pie(aes(fill='name', weight='value'), size=15, \\
                                     tooltips='none', \\
                                     labels=layer_labels()\\
@@ -200,12 +223,12 @@ class layer_labels(FeatureSpec):
 
     def size(self, value):
         """
-        Text size in the annotation.
+        Set the text size for the annotation.
 
         Parameters
         ----------
         value : float
-            Text size in the annotation.
+            The text size value for the annotation.
 
         Returns
         -------
@@ -221,9 +244,9 @@ class layer_labels(FeatureSpec):
 
             from lets_plot import *
             LetsPlot.setup_html()
-            data = {'name': ['a', 'b', 'c', 'd', 'b'], 'value': [40, 90, 10, 50, 20 ] }
+            data = {'name': ['a', 'b', 'c', 'd', 'b'], 'value': [40, 90, 10, 50, 20 ]}
             ggplot(data) + geom_pie(aes(slice='value', fill='name'), size=15, hole=0.4, \\
-                                    stat='identity', tooltips = 'none', \\
+                                    stat='identity', tooltips='none', \\
                                     labels=layer_labels().line('@value')
                                                              .size(25))
 
@@ -231,3 +254,37 @@ class layer_labels(FeatureSpec):
 
         self._size = value
         return self
+
+    def inherit_color(self):
+        """
+        Use the layer's color for the annotation text.
+
+        When enabled, the annotation text will inherit the color from the
+        layer it's associated with, rather than using a default or
+        explicitly set color.
+
+        Returns
+        -------
+        `layer_labels`
+            Annotations specification.
+
+        Examples
+        --------
+
+        .. jupyter-execute::
+            :linenos:
+            :emphasize-lines: 8
+
+            from lets_plot import *
+            LetsPlot.setup_html()
+            data = {'name': ['a', 'b', 'c', 'd', 'b'], 'value': [40, 90, 10, 50, 20 ]}
+            ggplot(data) + geom_pie(aes(slice='value', color='name'), alpha=0, size=15, hole=0.4, \\
+                                    stroke=5, spacer_color='pen', \\
+                                    stat='identity', tooltips='none', \\
+                                    labels=layer_labels().line('@value')
+                                                         .inherit_color())
+
+        """
+
+        self._useLayerColor = True
+        return self

lets_plot/plot/core.py

@@ -9,7 +9,7 @@ from typing import Union
 
 __all__ = ['aes', 'layer']
 
-from lets_plot._global_settings import get_global_bool, has_global_value, FRAGMENTS_ENABLED
+from lets_plot._global_settings import get_global_bool, has_global_value, FRAGMENTS_ENABLED, MAGICK_EXPORT
 
 
 def aes(x=None, y=None, **kwargs):
@@ -96,7 +96,7 @@ def layer(geom=None, stat=None, data=None, mapping=None, position=None, **kwargs
         mapped to plot "aesthetics".
     position : str or `FeatureSpec`
         Position adjustment.
-        Either a position adjustment name: 'dodge', 'dodgev', 'jitter', 'nudge', 'jitterdodge', 'fill',
+        Either a position adjustment name: 'dodge', 'jitter', 'nudge', 'jitterdodge', 'fill',
         'stack' or 'identity', or the result of calling a position adjustment function (e.g., `position_dodge()` etc.).
     kwargs:
         Other arguments passed on to layer. These are often aesthetics settings, used to set an aesthetic to a fixed
@@ -566,10 +566,10 @@ class PlotSpec(FeatureSpec):
         h : float, default=None
             Height of the output image in units.
             Only applicable when exporting to PNG or PDF.
-        unit : {'in', 'cm', 'mm'}, default=None
+        unit : {'in', 'cm', 'mm'}, default='in'
             Unit of the output image. One of: 'in', 'cm', 'mm'.
             Only applicable when exporting to PNG or PDF.
-        dpi : int, default=None
+        dpi : int, default=300
             Resolution in dots per inch.
             Only applicable when exporting to PNG or PDF.
 
@@ -580,9 +580,27 @@ class PlotSpec(FeatureSpec):
 
         Notes
         -----
-        Export to PNG file uses the CairoSVG library.
-        CairoSVG is free and distributed under the LGPL-3.0 license.
-        For more details visit: https://cairosvg.org/documentation/
+        - If `w`, `h`, `unit`, and `dpi` are all specified:
+
+          - The plot's pixel size (default or set by `ggsize()`) is ignored.
+          - The output size is calculated using the specified `w`, `h`, `unit`, and `dpi`.
+
+            - The plot is resized to fit the specified `w` x `h` area, which may affect the layout, tick labels, and other elements.
+
+        - If only `dpi` is specified:
+
+          - The plot's pixel size (default or set by `ggsize()`) is converted to inches using the standard display PPI of 96.
+          - The output size is then calculated based on the specified DPI.
+
+            - The plot maintains its aspect ratio, preserving layout, tick labels, and other visual elements.
+            - Useful for printing - the plot will appear nearly the same size as on screen.
+
+        - If `w`, `h` are not specified:
+
+          - The `scale` parameter is used to determine the output size.
+
+            - The plot maintains its aspect ratio, preserving layout, tick labels, and other visual elements.
+            - Useful for generating high-resolution images suitable for publication.
 
         Examples
         --------
@@ -600,6 +618,7 @@ class PlotSpec(FeatureSpec):
             file_like = io.BytesIO()
             p.to_png(file_like)
             display.Image(file_like.getvalue())
+
         """
         return _export_as_raster(self, path, scale, 'png', w=w, h=h, unit=unit, dpi=dpi)
 
@@ -623,10 +642,10 @@ class PlotSpec(FeatureSpec):
         h : float, default=None
             Height of the output image in units.
             Only applicable when exporting to PNG or PDF.
-        unit : {'in', 'cm', 'mm'}, default=None
+        unit : {'in', 'cm', 'mm'}, default='in'
             Unit of the output image. One of: 'in', 'cm', 'mm'.
             Only applicable when exporting to PNG or PDF.
-        dpi : int, default=None
+        dpi : int, default=300
             Resolution in dots per inch.
             Only applicable when exporting to PNG or PDF.
 
@@ -637,9 +656,27 @@ class PlotSpec(FeatureSpec):
 
         Notes
         -----
-        Export to PDF file uses the CairoSVG library.
-        CairoSVG is free and distributed under the LGPL-3.0 license.
-        For more details visit: https://cairosvg.org/documentation/
+        - If `w`, `h`, `unit`, and `dpi` are all specified:
+
+          - The plot's pixel size (default or set by `ggsize()`) is ignored.
+          - The output size is calculated using the specified `w`, `h`, `unit`, and `dpi`.
+
+            - The plot is resized to fit the specified `w` x `h` area, which may affect the layout, tick labels, and other elements.
+
+        - If only `dpi` is specified:
+
+          - The plot's pixel size (default or set by `ggsize()`) is converted to inches using the standard display PPI of 96.
+          - The output size is then calculated based on the specified DPI.
+
+            - The plot maintains its aspect ratio, preserving layout, tick labels, and other visual elements.
+            - Useful for printing - the plot will appear nearly the same size as on screen.
+
+        - If `w`, `h` are not specified:
+
+          - The `scale` parameter is used to determine the output size.
+
+            - The plot maintains its aspect ratio, preserving layout, tick labels, and other visual elements.
+            - Useful for generating high-resolution images suitable for publication.
 
         Examples
         --------
@@ -660,6 +697,7 @@ class PlotSpec(FeatureSpec):
             p = ggplot({'x': x, 'y': y}, aes(x='x', y='y')) + geom_jitter()
             file_like = io.BytesIO()
             p.to_pdf(file_like)
+
         """
         return _export_as_raster(self, path, scale, 'pdf', w=w, h=h, unit=unit, dpi=dpi)
 
@@ -875,29 +913,108 @@ def _to_html(spec, path, iframe: bool) -> Union[str, None]:
         return None
 
 
-def _export_as_raster(spec, path, scale: float, export_format: str, w=None, h=None, unit=None, dpi=None) -> Union[
-    str, None]:
-    try:
-        import cairosvg
-    except ImportError:
-        import sys
-        print("\n"
-              "To export Lets-Plot figure to a PNG or PDF file please install CairoSVG library"
-              "to your Python environment.\n"
-              "CairoSVG is free and distributed under the LGPL-3.0 license.\n"
-              "For more details visit: https://cairosvg.org/documentation/\n", file=sys.stderr)
-        return None
+def _export_as_raster(spec, path, scale: float, export_format: str, w=None, h=None, unit=None, dpi=None) -> Union[str, None]:
+    if get_global_bool(MAGICK_EXPORT):
+        if w is None and h is None and unit is None and dpi is None:
+            def_scale = 2.0
+            def_dpi = -1
+            def_unit = ""
+        else:
+            def_scale = 1.0
+            def_dpi = 300
+            def_unit = 'in'
+
+        return _export_with_magick(
+            spec,
+            path,
+            scale if scale is not None else def_scale,
+            export_format,
+            w if w is not None else -1,
+            h if h is not None else -1,
+            unit if unit is not None else def_unit,
+            dpi if dpi is not None else def_dpi
+        )
+    else:
+        return _export_with_cairo(spec, path, scale, export_format, w, h, unit, dpi)
+
+
+def _export_with_magick(spec, path, scale: float, export_format: str, w, h, unit, dpi) -> Union[str, None]:
+    import base64
+    from .. import _kbridge
+
+    if isinstance(path, str):
+        file_path = _makedirs(path)
+        file_like_object = None
+    else:
+        file_like_object = path
+        file_path = None
+
+    png_base64 = _kbridge._export_png(spec.as_dict(), float(w), float(h), unit, int(dpi), float(scale))
+    png = base64.b64decode(png_base64)
 
     if export_format.lower() == 'png':
-        export_function = cairosvg.svg2png
+        if file_path is not None:
+            with open(file_path, 'wb') as f:
+                f.write(png)
+            return file_path
+        else:
+            file_like_object.write(png)
+            return None
     elif export_format.lower() == 'pdf':
-        export_function = cairosvg.svg2pdf
+        try:
+            from PIL import Image
+        except ImportError:
+            import sys
+            print("\n"
+                  "To export Lets-Plot figure to a PDF file please install pillow library"
+                  "to your Python environment.\n"
+                  "Pillow is free and distributed under the MIT-CMU license.\n"
+                  "For more details visit: https://python-pillow.github.io/\n", file=sys.stderr)
+            return None
+
+
+        with Image.open(io.BytesIO(png)) as img:
+            if img.mode == 'RGBA':
+                img = img.convert('RGB')
+
+            dpi = dpi if dpi is not None else 96  # Default DPI if not specified
+            if file_path is not None:
+                img.save(file_path, "PDF", dpi=(dpi, dpi))
+                return file_path
+            else:
+                img.save(file_like_object, "PDF", dpi=(dpi, dpi))
+                return None
     else:
         raise ValueError("Unknown export format: {}".format(export_format))
 
+
+def _export_with_cairo(spec, path, scale: float, export_format: str, w=None, h=None, unit=None, dpi=None) -> Union[str, None]:
     from .. import _kbridge
-    # Use SVG image-rendering style as Cairo doesn't support CSS image-rendering style,
-    svg = _kbridge._generate_svg(spec.as_dict(), use_css_pixelated_image_rendering=False)
+
+    input = None
+    export_function = None
+
+    if export_format.lower() == 'png' or export_format.lower() == 'pdf':
+        try:
+            import cairosvg
+        except ImportError:
+            import sys
+            print("\n"
+                  "To export Lets-Plot figure to a PNG or PDF file please install CairoSVG library"
+                  "to your Python environment.\n"
+                  "CairoSVG is free and distributed under the LGPL-3.0 license.\n"
+                  "For more details visit: https://cairosvg.org/documentation/\n", file=sys.stderr)
+            return None
+
+        if export_format.lower() == 'png':
+            export_function = cairosvg.svg2png
+        elif export_format.lower() == 'pdf':
+            export_function = cairosvg.svg2pdf
+
+        # Use SVG image-rendering style as Cairo doesn't support CSS image-rendering style,
+        input = _kbridge._generate_svg(spec.as_dict(), use_css_pixelated_image_rendering=False)
+    else:
+        raise ValueError("Unknown export format: {}".format(export_format))
 
     if isinstance(path, str):
         abspath = _makedirs(path)
@@ -910,10 +1027,10 @@ def _export_as_raster(spec, path, scale: float, export_format: str, w=None, h=No
             raise ValueError("w, h, unit, and dpi must all be specified")
 
         w, h = _to_inches(w, unit) * dpi, _to_inches(h, unit) * dpi
-        export_function(bytestring=svg, write_to=path, dpi=dpi, output_width=w, output_height=h)
+        export_function(bytestring=input, write_to=path, dpi=dpi, output_width=w, output_height=h)
     else:
         scale = scale if scale is not None else 2.0
-        export_function(bytestring=svg, write_to=path, scale=scale)
+        export_function(bytestring=input, write_to=path, scale=scale)
 
     return result