Support w, h and unit parameters in ggsave(). Implement issue #281

Author: MKoroteev-HORIS

future_changes.md

@@ -5,6 +5,11 @@ GeoTools [v 33.2](https://github.com/geotools/geotools/releases/tag/33.2)
 
 ### Added
 
+- ggsave():
+  - support font synthesis for *italic* and **bold** styles.
+  - `w`, `h` and `unit` parameters support [[#281]https://github.com/JetBrains/lets-plot-kotlin/issues/281],
+    [[#1368](https://github.com/JetBrains/lets-plot/issues/1368)]. 
+
 ### Changed
 
 - `facetWrap()` now drops factor levels that do not appear in the data (i.e., empty panels) by default [[#1322](https://github.com/JetBrains/lets-plot/issues/1322)]. <br>

plot-api/src/jvmMain/kotlin/org/jetbrains/letsPlot/export/ggsave.kt

@@ -7,10 +7,11 @@ package org.jetbrains.letsPlot.export
 
 import org.jetbrains.letsPlot.Figure
 import org.jetbrains.letsPlot.awt.plot.PlotSvgExport
+import org.jetbrains.letsPlot.commons.geometry.DoubleVector
+import org.jetbrains.letsPlot.core.util.PlotExportCommon
 import org.jetbrains.letsPlot.core.util.PlotHtmlExport
 import org.jetbrains.letsPlot.core.util.PlotHtmlHelper.scriptUrl
 import org.jetbrains.letsPlot.intern.toSpec
-import java.lang.Double.NaN
 import java.nio.file.Path
 import java.util.*
 import kotlin.io.path.*
@@ -22,29 +23,72 @@ private const val DEF_EXPORT_DIR = "lets-plot-images"
  * Supported formats: SVG, HTML, PNG, JPEG and TIFF.
  * Note: in some configurations raster formats might not be supported.
  *
- * The exported file is created in directory ${user.dir}/lets-plot-images
- * if not specified otherwise (see the `path` parameter).
+ * If [path] is not specified, the output file will be saved in
+ * `${user.dir}/lets-plot-images`.
  *
  * ## Examples
  *
  * - [export_to_file.ipynb](https://nbviewer.org/github/JetBrains/lets-plot-docs/blob/master/source/kotlin_examples/cookbook/export_to_file.ipynb)
  *
  * @param plot Plot to export.
- * @param filename The name of file. It mast end with file extention corresponding
- *      to one of the supported formats: svg, html (or htm), png, jpeg (or jpg) or tiff (or tif)
+ * @param filename Name of the file. Must include an extension matching
+ *      one of the supported formats: `.svg`, `.html`/`.htm`, `.png`, `.jpeg`/`.jpg`, or `.tiff`/`.tif`
  * @param scale Scaling factor (only for raster formats). Default: 2.0
- * @param dpi Dot-per-Inch value to store in the exported file metadata (only for raster formats).
+ * @param w Width of the output image in units.
+ * @param h Height of the output image in units.
+ * @param unit Unit of the output image. One of: `"in"`, `"cm"`, `"mm"`, `"px"`.
+ *      Only applicable when exporting to SVG, PNG, JPG, or TIFF.
+ * @param dpi Resolution in dots per inch to store in the exported file metadata.
+ *      Only applicable when exporting to the raster formats: PNG, JPG, or TIFF.
  *      Default: no metadata is stored.
  * @param path Path to a directory to save image files in.
  *      Default: `${user.dir}/lets-plot-images`
  *
- * @return Absolute pathname of created file.
+ * @return Absolute pathname of the created file.
+ *
+ * ### Notes
+ *
+ * The output format is inferred from the file extension.
+ *
+ * **For PNG and PDF:**
+ *
+ * - If [w], [h], [unit], and [dpi] are all specified:
+ *
+ *   - The plot's pixel size (default or set via [ggsize()](https://lets-plot.org/kotlin/api-reference/-lets--plot--kotlin/org.jetbrains.letsPlot/ggsize.html) is ignored.
+ *   - The output size is computed from the given dimensions and DPI.
+ *   - The plot is resized to fit the specified [w] x [h] area, which may affect the layout.
+ *
+ * - If only [dpi] is specified:
+ *   - The plot's pixel size (default or set via [ggsize()](https://lets-plot.org/kotlin/api-reference/-lets--plot--kotlin/org.jetbrains.letsPlot/ggsize.html)) is converted to inches assuming the standard display PPI of 96 PPI.
+ *   - The output size is computed from this size and [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] and [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.
+ *
+ * **For SVG:**
+ * - If [w], [h], and [unit] are specified:
+ *   - The plot's pixel size (default or set via [ggsize()](https://lets-plot.org/kotlin/api-reference/-lets--plot--kotlin/org.jetbrains.letsPlot/ggsize.html)) is ignored.
+ *   - The output size is set from the given values.
+ *
+ * **For HTML:**
+ * - If [w] and [h] are specified:
+ *   - The plot's pixel size (default or set via [ggsize()](https://lets-plot.org/kotlin/api-reference/-lets--plot--kotlin/org.jetbrains.letsPlot/ggsize.html)) is ignored.
+ *   - The output size is determined directly from the specified [w] and [h], which are treated as pixel values.
+ *
  */
 @Suppress("SpellCheckingInspection")
 fun ggsave(
     plot: Figure,
     filename: String,
-    scale: Number = 2,
+    scale: Number? = null,
+    w: Number? = null,
+    h: Number? = null,
+    unit: String? = null,
     dpi: Number? = null,
     path: String? = null
 ): String {
@@ -65,10 +109,16 @@ fun ggsave(
     val file = dir.resolve(filename)
 
     val spec: MutableMap<String, Any> = plot.toSpec()
+    val sizeUnit = PlotExportCommon.SizeUnit.fromName(unit ?: "")
+    val plotSize = toDoubleVector(w, h)
 
     when (ext) {
         "svg" -> {
-            val svg = PlotSvgExport.buildSvgImageFromRawSpecs(spec)
+            val svg = PlotSvgExport.buildSvgImageFromRawSpecs(
+                spec,
+                plotSize = plotSize,
+                sizeUnit = sizeUnit?: PlotExportCommon.SizeUnit.PX,
+            )
             if (file.notExists()) {
                 file.createFile()
             }
@@ -78,8 +128,9 @@ fun ggsave(
         "html", "htm" -> {
             val html = PlotHtmlExport.buildHtmlFromRawSpecs(
                 spec,
+                scriptUrl = scriptUrl(VersionChecker.letsPlotJsVersion),
                 iFrame = true,
-                scriptUrl = scriptUrl(VersionChecker.letsPlotJsVersion)
+                plotSize = plotSize
             )
             if (file.notExists()) {
                 file.createFile()
@@ -91,8 +142,10 @@ fun ggsave(
             exportRasterImage(
                 spec,
                 file,
-                scalingFactor = scale.toDouble(),
-                targetDPI = dpi?.toDouble() ?: NaN
+                scalingFactor = scale,
+                plotSize = plotSize,
+                unit = sizeUnit,
+                targetDPI = dpi
             )
         }
 
@@ -107,11 +160,23 @@ fun ggsave(
     return file.toRealPath().toString()
 }
 
+
+private fun toDoubleVector(x: Number?, y: Number?): DoubleVector? {
+    return if (x != null && y != null) {
+        DoubleVector(x.toDouble(), y.toDouble())
+    } else {
+        null
+    }
+}
+
+
 private fun exportRasterImage(
     spec: MutableMap<String, Any>,
     file: Path,
-    scalingFactor: Double,
-    targetDPI: Double
+    scalingFactor: Number? = null,
+    plotSize: DoubleVector? = null,
+    unit: PlotExportCommon.SizeUnit? = null,
+    targetDPI: Number? = null
 ) {
     // lets-plot-image-export.jar might not be present in the classpath.
     val imageBytes: ByteArray = try {
@@ -127,6 +192,8 @@ private fun exportRasterImage(
             plotSpec = spec,
             format = format,
             scalingFactor = scalingFactor,
+            plotSize = plotSize,
+            unit = unit,
             targetDPI = targetDPI
         )
         image.bytes