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

@@ -1,10 +1,12 @@
 using System;
 using System.IO;
+using System.Linq;
 using NUnit.Framework;
 using QuestPDF.Drawing.Exceptions;
 using QuestPDF.Examples.Engine;
 using QuestPDF.Fluent;
 using QuestPDF.Helpers;
+using QuestPDF.Infrastructure;
 
 namespace QuestPDF.Examples
 {
@@ -64,42 +66,24 @@ namespace QuestPDF.Examples
             });
         }
         
+        
+        
         [Test]
-        public void ReusingTheSameImageFileShouldBePossible()
+        public void ImageResolutionScaling()
         {
-            var fileName = Path.GetTempFileName() + ".jpg";
+            var image = Image.FromFile("large-image.jpg");
             
-            try
+            Document
-            {
+                .Create(document =>
-                var image = Placeholders.Image(300, 100);
+                {
-                
+                    document.Page(page =>
-                using var file = File.Create(fileName);
-                file.Write(image);
-                file.Dispose();
-                
-                RenderingTest
-                    .Create()
-                    .ProducePdf()
-                    .PageSize(PageSizes.A4)
-                    .ShowResults()
-                    .Render(container =>
                     {
-                        container
+                        page.Size(210, 210);
-                            .Padding(20)
+                        page.Margin(50);
-                            .Column(column =>
+                        page.Content().Image(image);
-                            {
-                                column.Spacing(20);
-                                
-                                column.Item().Image(fileName);
-                                column.Item().Image(fileName);
-                                column.Item().Image(fileName);
-                            });
                     });
-            }
+                })
-            finally
+                .GeneratePdf($"test.pdf");
-            {
-                File.Delete(fileName);
-            }
         }
     }
 }

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,10 +1,16 @@
-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;
+using Image = QuestPDF.Infrastructure.Image;
 
 namespace QuestPDF.UnitTests
 {
@@ -15,9 +21,9 @@ namespace QuestPDF.UnitTests
         public void Measure_TakesAvailableSpaceRegardlessOfSize()
         {
             TestPlan
-                .For(x => new Image
+                .For(x => new QuestPDF.Elements.Image
                 {
-                    InternalImage = GenerateImage(400, 300)
+                    DocumentImage = Image.FromSkImage(GenerateImage(400, 300))
                 })
                 .MeasureElement(new Size(300, 200))
                 .CheckMeasureResult(SpacePlan.FullRender(300, 200));
@@ -27,9 +33,9 @@ namespace QuestPDF.UnitTests
         public void Draw_TakesAvailableSpaceRegardlessOfSize()
         {
             TestPlan
-                .For(x => new Image
+                .For(x => new QuestPDF.Elements.Image
                 {
-                    InternalImage = GenerateImage(400, 300)
+                    DocumentImage = Image.FromSkImage(GenerateImage(400, 300))
                 })
                 .DrawElement(new Size(300, 200))
                 .ExpectCanvasDrawImage(new Position(0, 0), new Size(300, 200))
@@ -51,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)
         {
@@ -58,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

@@ -7,11 +7,12 @@ namespace QuestPDF.Elements
 {
     internal class Image : Element, ICacheable
     {
-        public SKImage? InternalImage { get; set; }
+        public Infrastructure.Image? DocumentImage { get; set; }
 
         ~Image()
         {
-            InternalImage?.Dispose();
+            if (DocumentImage is { IsDocumentScoped: true })
+                DocumentImage?.Dispose();
         }
         
         internal override SpacePlan Measure(Size availableSpace)
@@ -23,10 +24,10 @@ namespace QuestPDF.Elements
 
         internal override void Draw(Size availableSpace)
         {
-            if (InternalImage == null)
+            if (DocumentImage == null)
                 return;
 
-            Canvas.DrawImage(InternalImage, Position.Zero, availableSpace);
+            Canvas.DrawImage(DocumentImage.GetVersionOfSize(availableSpace), Position.Zero, availableSpace);
         }
     }
 }

Source/QuestPDF/Fluent/ImageExtensions.cs

@@ -3,7 +3,6 @@ using System.IO;
 using QuestPDF.Drawing.Exceptions;
 using QuestPDF.Elements;
 using QuestPDF.Infrastructure;
-using SkiaSharp;
 
 namespace QuestPDF.Fluent
 {
@@ -11,30 +10,30 @@ namespace QuestPDF.Fluent
     {
         public static void Image(this IContainer parent, byte[] imageData, ImageScaling scaling = ImageScaling.FitWidth)
         {
-            var image = SKImage.FromEncodedData(imageData);
+            var image = Infrastructure.Image.FromBinaryData(imageData).DisposeAfterDocumentGeneration();
             parent.Image(image, scaling);
         }
         
         public static void Image(this IContainer parent, string filePath, ImageScaling scaling = ImageScaling.FitWidth)
         {
-            var image = SKImage.FromEncodedData(filePath);
+            var image = Infrastructure.Image.FromFile(filePath).DisposeAfterDocumentGeneration();
             parent.Image(image, scaling);
         }
         
         public static void Image(this IContainer parent, Stream fileStream, ImageScaling scaling = ImageScaling.FitWidth)
         {
-            var image = SKImage.FromEncodedData(fileStream);
+            var image = Infrastructure.Image.FromStream(fileStream).DisposeAfterDocumentGeneration();
             parent.Image(image, scaling);
         }
         
-        private static void Image(this IContainer parent, SKImage image, ImageScaling scaling = ImageScaling.FitWidth)
+        public static void Image(this IContainer parent, Infrastructure.Image image, ImageScaling scaling = ImageScaling.FitWidth)
         {
             if (image == null)
                 throw new DocumentComposeException("Cannot load or decode provided image.");
             
-            var imageElement = new Image
+            var imageElement = new QuestPDF.Elements.Image
             {
-                InternalImage = image
+                DocumentImage = image
             };
 
             if (scaling != ImageScaling.Resize)

Source/QuestPDF/Infrastructure/Image.cs

@@ -0,0 +1,181 @@
+using System;
+using System.Collections.Generic;
+using System.IO;
+using QuestPDF.Drawing;
+using QuestPDF.Drawing.Exceptions;
+using SkiaSharp;
+
+namespace QuestPDF.Infrastructure
+{
+    public class Image : IDisposable
+    {
+        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 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
+
+        internal static Image FromSkImage(SKImage image)
+        {
+            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;
     }
 }