Implemented automated image scaling

* DPI-based image scaling prototype (not ready for production)

* Added ImageDpi API

* Added support for image DPI scaling

Source/QuestPDF.Examples/ImageExamples.cs

@@ -66,28 +66,24 @@ namespace QuestPDF.Examples
             });
         }
         
+        
+        
         [Test]
-        public void ReusingTheSameImageFileShouldBePossible()
+        public void ImageResolutionScaling()
         {
-            var image = Image.FromBinaryData(Placeholders.Image(300, 100)).DisposeAfterDocumentGeneration();
-                
-            RenderingTest
-                .Create()
-                .ProducePdf()
-                .PageSize(PageSizes.A4)
-                .ShowResults()
-                .Render(container =>
+            var image = Image.FromFile("large-image.jpg");
+            
+            Document
+                .Create(document =>
                 {
-                    container
-                        .Padding(20)
-                        .Column(column =>
-                        {
-                            column.Spacing(20);
-                                
-                            foreach (var i in Enumerable.Range(0, 1000))
-                                column.Item().Image(image);
-                        });
-                });
+                    document.Page(page =>
+                    {
+                        page.Size(210, 210);
+                        page.Margin(50);
+                        page.Content().Image(image);
+                    });
+                })
+                .GeneratePdf($"test.pdf");
         }
     }
 }

Source/QuestPDF.Examples/QuestPDF.Examples.csproj

@@ -1,7 +1,7 @@
 <Project Sdk="Microsoft.NET.Sdk">
 
     <PropertyGroup>
-        <TargetFramework>netcoreapp3.1</TargetFramework>
+        <TargetFramework>net6.0</TargetFramework>
         <IsPackable>false</IsPackable>
     </PropertyGroup>
 
@@ -32,6 +32,12 @@
       <None Update="pdf-icon.svg">
         <CopyToOutputDirectory>PreserveNewest</CopyToOutputDirectory>
       </None>
+      <None Update="large-image.png">
+        <CopyToOutputDirectory>PreserveNewest</CopyToOutputDirectory>
+      </None>
+      <None Update="large-image.jpg">
+        <CopyToOutputDirectory>PreserveNewest</CopyToOutputDirectory>
+      </None>
     </ItemGroup>
 
 </Project>

Source/QuestPDF.UnitTests/ImageTests.cs

@@ -1,7 +1,12 @@
-using NUnit.Framework;
+using System;
+using System.Linq;
+using System.Net.Mime;
+using FluentAssertions;
+using NUnit.Framework;
 using QuestPDF.Drawing;
 using QuestPDF.Elements;
 using QuestPDF.Fluent;
+using QuestPDF.Helpers;
 using QuestPDF.Infrastructure;
 using QuestPDF.UnitTests.TestEngine;
 using SkiaSharp;
@@ -52,6 +57,52 @@ namespace QuestPDF.UnitTests
                 .MeasureElement(new Size(300, 200))
                 .CheckMeasureResult(SpacePlan.FullRender(300, 100));;
         }
+
+        [Test]
+        public void UsingSharedImageShouldNotDrasticallyIncreaseDocumentSize()
+        {
+            var placeholderImage = Placeholders.Image(1000, 200);
+            
+            var documentWithSingleImageSize = GetDocumentSize(container =>
+            {
+                container.Image(placeholderImage);
+            });
+            
+            var documentWithMultipleImagesSize = GetDocumentSize(container =>
+            {
+                container.Column(column =>
+                {
+                    foreach (var i in Enumerable.Range(0, 100))
+                        column.Item().Image(placeholderImage);
+                });
+            });
+            
+            var documentWithSingleImageUsedMultipleTimesSize = GetDocumentSize(container =>
+            {
+                container.Column(column =>
+                {
+                    var sharedImage = Image.FromBinaryData(placeholderImage).DisposeAfterDocumentGeneration();
+                    
+                    foreach (var i in Enumerable.Range(0, 100))
+                        column.Item().Image(sharedImage);
+                });
+            });
+
+            (documentWithMultipleImagesSize / (float)documentWithSingleImageSize).Should().BeInRange(90, 100);
+            (documentWithSingleImageUsedMultipleTimesSize / (float)documentWithSingleImageSize).Should().BeInRange(1f, 1.5f);
+        }
+
+        [Test]
+        public void ImageShouldNotBeScaledAboveItsNativeResolution()
+        {
+            var image = Placeholders.Image(200, 200);
+
+            var documentSizeWithScaledDownImage = GetDocumentSize(container => container.Width(100).Height(100).Image(Image.FromBinaryData(image)));
+            //var documentSizeWithNormalImage = GetDocumentSize(container => container.Width(200).Height(200).Image(image));
+            //var documentSizeWithScaledUpImage = GetDocumentSize(container => container.Width(400).Height(400).Image(image));
+        }
+
+        #region helpers
         
         SKImage GenerateImage(int width, int height)
         {
@@ -59,5 +110,21 @@ namespace QuestPDF.UnitTests
             using var surface = SKSurface.Create(imageInfo);
             return surface.Snapshot();
         }
+        
+        private static int GetDocumentSize(Action<IContainer> container)
+        {
+            return Document
+                .Create(document =>
+                {
+                    document.Page(page =>
+                    {
+                        page.Content().Element(container);
+                    });
+                })
+                .GeneratePdf()
+                .Length;
+        }
+        
+        #endregion
     }
 }

Source/QuestPDF.UnitTests/QuestPDF.UnitTests.csproj

@@ -1,7 +1,7 @@
 <Project Sdk="Microsoft.NET.Sdk">
 
     <PropertyGroup>
-        <TargetFramework>netcoreapp3.1</TargetFramework>
+        <TargetFramework>net6.0</TargetFramework>
         <IsPackable>false</IsPackable>
     </PropertyGroup>
 

Source/QuestPDF/Drawing/DocumentGenerator.cs

@@ -10,6 +10,7 @@ using QuestPDF.Elements.Text.Items;
 using QuestPDF.Fluent;
 using QuestPDF.Helpers;
 using QuestPDF.Infrastructure;
+using Image = QuestPDF.Elements.Image;
 
 namespace QuestPDF.Drawing
 {
@@ -21,7 +22,7 @@ namespace QuestPDF.Drawing
             
             var metadata = document.GetMetadata();
             var canvas = new PdfCanvas(stream, metadata);
-            RenderDocument(canvas, document);
+            RenderDocument(canvas, document, metadata);
         }
         
         internal static void GenerateXps(Stream stream, IDocument document)
@@ -30,7 +31,7 @@ namespace QuestPDF.Drawing
             
             var metadata = document.GetMetadata();
             var canvas = new XpsCanvas(stream, metadata);
-            RenderDocument(canvas, document);
+            RenderDocument(canvas, document, metadata);
         }
 
         private static void CheckIfStreamIsCompatible(Stream stream)
@@ -46,24 +47,26 @@ namespace QuestPDF.Drawing
         {
             var metadata = document.GetMetadata();
             var canvas = new ImageCanvas(metadata);
-            RenderDocument(canvas, document);
+            RenderDocument(canvas, document, metadata);
 
             return canvas.Images;
         }
 
         internal static ICollection<PreviewerPicture> GeneratePreviewerPictures(IDocument document)
         {
+            var metadata = document.GetMetadata();
             var canvas = new SkiaPictureCanvas();
-            RenderDocument(canvas, document);
+            RenderDocument(canvas, document, metadata);
             return canvas.Pictures;
         }
         
-        internal static void RenderDocument<TCanvas>(TCanvas canvas, IDocument document)
+        internal static void RenderDocument<TCanvas>(TCanvas canvas, IDocument document, DocumentMetadata metadata)
             where TCanvas : ICanvas, IRenderingCanvas
         {
             var container = new DocumentContainer();
             document.Compose(container);
             var content = container.Compose();
+            ApplyDefaultImageDpi(content, metadata.RasterDpi, metadata.ImageQuality);
             ApplyDefaultTextStyle(content, TextStyle.LibraryDefault);
             ApplyContentDirection(content, ContentDirection.LeftToRight);
             
@@ -173,6 +176,18 @@ namespace QuestPDF.Drawing
 
             return debuggingState;
         }
+
+        internal static void ApplyDefaultImageDpi(this Element? content, int targetDpi, int targetImageQuality)
+        {
+            content.VisitChildren(x =>
+            {
+                if (x is not Image { DocumentImage: { } image })
+                    return;
+                
+                image.TargetDpi ??= targetDpi;
+                image.ImageQuality ??= targetImageQuality;
+            });
+        }
         
         internal static void ApplyContentDirection(this Element? content, ContentDirection direction)
         {

Source/QuestPDF/Drawing/DocumentMetadata.cs

@@ -5,8 +5,10 @@ namespace QuestPDF.Drawing
 {
     public class DocumentMetadata
     {
+        public const int DefaultPdfDpi = 72;
+        
         public int ImageQuality { get; set; } = 101;
-        public int RasterDpi { get; set; } = 72;
+        public int RasterDpi { get; set; } = DefaultPdfDpi;
         public bool PdfA { get; set; }
         
         public string? Title { get; set; }

Source/QuestPDF/Elements/Image.cs

@@ -27,7 +27,7 @@ namespace QuestPDF.Elements
             if (DocumentImage == null)
                 return;
 
-            Canvas.DrawImage(DocumentImage.SkImage, Position.Zero, availableSpace);
+            Canvas.DrawImage(DocumentImage.GetVersionOfSize(availableSpace), Position.Zero, availableSpace);
         }
     }
 }

Source/QuestPDF/Infrastructure/Image.cs

@@ -1,5 +1,7 @@
 using System;
+using System.Collections.Generic;
 using System.IO;
+using QuestPDF.Drawing;
 using QuestPDF.Drawing.Exceptions;
 using SkiaSharp;
 
@@ -7,26 +9,101 @@ namespace QuestPDF.Infrastructure
 {
     public class Image : IDisposable
     {
-        internal SKImage SkImage { get; }
+        private SKImage SkImage { get; }
+        internal List<(Size size, SKImage image)>? ScaledImageCache { get; set; }
+
+        internal int? TargetDpi { get; set; }
+        internal int? ImageQuality { get; set; }
+        internal bool PerformScalingToTargetDpi { get; set; }
         internal bool IsDocumentScoped { get; set; }
-        
+
         public int Width => SkImage.Width;
         public int Height => SkImage.Height;
-        
+
+        private const float ImageSizeSimilarityToleranceMax = 1.1f;
+        private const float ImageSizeSimilarityToleranceMin = 1 / ImageSizeSimilarityToleranceMax;
+
         private Image(SKImage image)
         {
             SkImage = image;
+            PerformScalingToTargetDpi = image.EncodedData.Size >= Settings.AdjustImageSizeThreshold;
         }
 
-        public Image DisposeAfterDocumentGeneration()
-        {
-            IsDocumentScoped = true;
-            return this;
-        }
-        
         public void Dispose()
         {
             SkImage.Dispose();
+            ScaledImageCache?.ForEach(x => x.image.Dispose());
+        }
+
+        internal SKImage GetVersionOfSize(Size size)
+        {
+            if (!PerformScalingToTargetDpi)
+                return SkImage;
+
+            var scalingFactor = TargetDpi.Value / (float)DocumentMetadata.DefaultPdfDpi;
+            var targetResolution = new Size(size.Width * scalingFactor, size.Height * scalingFactor);
+
+            if (targetResolution.Width > Width || targetResolution.Height > Height)
+                return SkImage;
+
+            ScaledImageCache ??= new List<(Size size, SKImage image)>();
+
+            foreach (var imageCache in ScaledImageCache)
+            {
+                if (HasSimilarSize(imageCache.size, targetResolution))
+                    return imageCache.image;
+            }
+
+            var scaledImage = ScaleImage(SkImage, targetResolution, ImageQuality);
+            ScaledImageCache.Add((targetResolution, scaledImage));
+
+            if (SkImage.EncodedData.Size < scaledImage.EncodedData.Size)
+                return SkImage;
+
+            return scaledImage;
+
+            
+            
+            static SKImage ScaleImage(SKImage originalImage, Size targetSize, int? imageQuality)
+            {
+                var imageInfo = new SKImageInfo((int)targetSize.Width, (int)targetSize.Height);
+                using var target = SKImage.Create(imageInfo);
+                originalImage.ScalePixels(target.PeekPixels(), SKFilterQuality.High);
+
+                var codes = SKCodec.Create(target.EncodedData);
+
+                var targetFormat = imageQuality > 100 ? SKEncodedImageFormat.Png : SKEncodedImageFormat.Jpeg;
+                var targetQuality = Math.Max(imageQuality, 100);
+                var data = target.Encode(targetFormat, targetQuality);
+
+                return SKImage.FromEncodedData(data);
+            }
+
+            static (SKEncodedImageFormat format, int quality) GetTargetImageFormat(SKImage originalImage, int? imageQuality) 
+            {
+                if (imageQuality.HasValue)
+                {
+                    var format = imageQuality > 100 
+                        ? SKEncodedImageFormat.Png 
+                        : SKEncodedImageFormat.Jpeg;
+
+                    var quality = Math.Max(imageQuality.Value, 100);
+
+                    return (format, quality);
+                }
+                
+                var codec = SKCodec.Create(originalImage.EncodedData);
+                
+            }
+
+            static bool HasSimilarSize(Size a, Size b)
+            {
+                var widthRatio = a.Width / b.Width;
+                var heightRatio = a.Height / b.Height;
+
+                return widthRatio is > ImageSizeSimilarityToleranceMin and < ImageSizeSimilarityToleranceMax &&
+                       heightRatio is > ImageSizeSimilarityToleranceMin and < ImageSizeSimilarityToleranceMax;
+            }
         }
 
         #region public constructors
@@ -35,30 +112,70 @@ namespace QuestPDF.Infrastructure
         {
             return CreateImage(image);
         }
-        
+
         public static Image FromBinaryData(byte[] imageData)
         {
             return CreateImage(SKImage.FromEncodedData(imageData));
         }
-        
+
         public static Image FromFile(string filePath)
         {
             return CreateImage(SKImage.FromEncodedData(filePath));
         }
-        
+
         public static Image FromStream(Stream fileStream)
         {
             return CreateImage(SKImage.FromEncodedData(fileStream));
         }
-        
+
         private static Image CreateImage(SKImage? image)
         {
             if (image == null)
                 throw new DocumentComposeException("Cannot load or decode provided image.");
-            
+
             return new Image(image);
         }
 
         #endregion
+
+        #region configuration API
+
+        public Image DisposeAfterDocumentGeneration()
+        {
+            IsDocumentScoped = true;
+            return this;
+        }
+
+        /// <summary>
+        /// Values from 1 to 100 correspond to the JPEG format, where 1 is lowest and 100 is highest quality.
+        /// Value 101 correspond to the PNG format with a lossless compression and alpha channel support. 
+        /// </summary>
+        /// <param name="quality"></param>
+        /// <returns></returns>
+        public Image WithQuality(int quality)
+        {
+            ImageQuality = quality;
+            return this;
+        }
+        
+        public Image WithQuality(ImageQuality quality)
+        {
+            ImageQuality = (int)quality;
+            return this;
+        }
+
+        public Image WithTargetDpi(int dpi = DocumentMetadata.DefaultPdfDpi)
+        {
+            TargetDpi = dpi;
+            return this;
+        }
+
+        public Image ScaleToTargetDpi(bool value = true)
+        {
+            PerformScalingToTargetDpi = value;
+            return this;
+        }
+
+        #endregion
     }
 }

Source/QuestPDF/Infrastructure/ImageQuality.cs

@@ -0,0 +1,40 @@
+namespace QuestPDF.Infrastructure
+{
+    public enum ImageQuality
+    {
+        /// <summary>
+        /// PNG format with alpha support
+        /// </summary>
+        Lossless = 101,
+        
+        /// <summary>
+        /// JPEG format with compression set to 100 out of 100
+        /// </summary>
+        Max = 100,
+        
+        /// <summary>
+        /// JPEG format with compression set to 90 out of 100
+        /// </summary>
+        VeryHigh = 90,
+        
+        /// <summary>
+        /// JPEG format with compression set to 80 out of 100
+        /// </summary>
+        High = 80,
+        
+        /// <summary>
+        /// JPEG format with compression set to 60 out of 100
+        /// </summary>
+        Medium = 60,
+
+        /// <summary>
+        /// JPEG format with compression set to 40 out of 100
+        /// </summary>
+        Low = 40,
+        
+        /// <summary>
+        /// JPEG format with compression set to 20 out of 100
+        /// </summary>
+        VeryLow = 20
+    }
+}

Source/QuestPDF/Settings.cs

@@ -36,5 +36,11 @@
         /// </summary>
         /// <remarks>By default, this flag is enabled only when the debugger IS attached.</remarks>
         public static bool CheckIfAllTextGlyphsAreAvailable { get; set; } = System.Diagnostics.Debugger.IsAttached;
+        
+        
+        /// <summary>
+        /// The file size threshold in bytes that is used to determine if the image should be automatically scaled to physical dimensions.
+        /// </summary>
+        public static int AdjustImageSizeThreshold { get; set; } = 32 * 1024;
     }
 }