Added lazy image byte loading and EagerlyLoadImageBytes option

Author: EdwardBlair

src/UglyToad.PdfPig.Tests/TestPdfImage.cs

@@ -38,6 +38,8 @@ public class TestPdfImage : IPdfImage
 
         public Memory<byte> DecodedBytes { get; set; }
 
+        public bool HasLoadedBytes => !RawMemory.IsEmpty;
+
         public IPdfImage? MaskImage { get; }
 
         public bool TryGetBytesAsMemory(out Memory<byte> bytes)

src/UglyToad.PdfPig/Content/IPdfImage.cs

@@ -38,14 +38,23 @@ public interface IPdfImage: IBoundingBox
 
         /// <summary>
         /// The encoded memory of the image with all filters still applied.
+        /// Accesing this property may trigger loading of the image bytes from the PDF stream.
         /// </summary>
         Memory<byte> RawMemory { get; }
 
         /// <summary>
         /// The encoded memory span of the image with all filters still applied.
+        /// Accesing this property may trigger loading of the image bytes from the PDF stream.
         /// </summary>
         Span<byte> RawBytes { get; }
 
+        /// <summary>
+        /// Whether the image byte data is available. Returns <see langword="false"/> when
+        /// <see cref="ParsingOptions.EagerlyLoadImageBytes"/> is <see langword="false"/>.
+        /// Image metadata (dimensions, color space, bounding box) is available regardless.
+        /// </summary>
+        bool HasLoadedBytes { get; }
+
         /// <summary>
         /// The color rendering intent to be used when rendering the image.
         /// </summary>

src/UglyToad.PdfPig/Content/InlineImage.cs

@@ -2,27 +2,28 @@
 {
     using System;
     using System.Collections.Generic;
-    using System.Diagnostics.CodeAnalysis;
+    using System.Diagnostics.CodeAnalysis;
     using Core;
     using Filters;
     using Graphics.Colors;
     using Graphics.Core;
     using Tokens;
-    using Images.Png;
-
+    using Images.Png;
+
     /// <inheritdoc />
     /// <summary>
     /// A small image that is completely defined directly inline within a <see cref="T:UglyToad.PdfPig.Content.Page" />'s content stream.
     /// </summary>
     public class InlineImage : IPdfImage
     {
         private readonly Lazy<Memory<byte>>? memoryFactory;
+        private readonly Memory<byte> rawMemory;
 
         /// <inheritdoc />
-        public PdfRectangle BoundingBox { get; }
+        public PdfRectangle BoundingBox { get; }
 
-        /// <inheritdoc />
-        [Obsolete("Use BoundingBox instead.")]
+        /// <inheritdoc />
+        [Obsolete("Use BoundingBox instead.")]
         public PdfRectangle Bounds => BoundingBox;
 
         /// <inheritdoc />
@@ -53,33 +54,36 @@ public class InlineImage : IPdfImage
         public bool Interpolate { get; }
 
         /// <inheritdoc />
-        public Memory<byte> RawMemory { get; }
-
+        public Memory<byte> RawMemory => rawMemory;
+
         /// <inheritdoc />
         public Span<byte> RawBytes => RawMemory.Span;
 
         /// <inheritdoc />
-        public ColorSpaceDetails ColorSpaceDetails { get; }
-
-        /// <inheritdoc />
+        public bool HasLoadedBytes => !rawMemory.IsEmpty;
+
+        /// <inheritdoc />
+        public ColorSpaceDetails ColorSpaceDetails { get; }
+
+        /// <inheritdoc />
         public IPdfImage? MaskImage { get; }
 
         /// <summary>
         /// Create a new <see cref="InlineImage"/>.
         /// </summary>
-        internal InlineImage(PdfRectangle bounds,
-            int widthInSamples,
-            int heightInSamples,
-            int bitsPerComponent,
+        internal InlineImage(PdfRectangle bounds,
+            int widthInSamples,
+            int heightInSamples,
+            int bitsPerComponent,
             bool isImageMask,
             RenderingIntent renderingIntent,
             bool interpolate,
             IReadOnlyList<double> decode,
-            Memory<byte> rawMemory,
+            Memory<byte> rawMemory,
             ILookupFilterProvider filterProvider,
-            IReadOnlyList<NameToken> filterNames,
+            IReadOnlyList<NameToken> filterNames,
             DictionaryToken streamDictionary,
-            ColorSpaceDetails colorSpaceDetails,
+            ColorSpaceDetails colorSpaceDetails,
             IPdfImage? softMaskImage)
         {
             IsInlineImage = true;
@@ -92,33 +96,36 @@ internal InlineImage(PdfRectangle bounds,
             RenderingIntent = renderingIntent;
             Interpolate = interpolate;
             ImageDictionary = streamDictionary;
-            RawMemory = rawMemory;
-            ColorSpaceDetails = colorSpaceDetails;
-
-            var filters = filterProvider.GetNamedFilters(filterNames);
-            
-            var supportsFilters = true;
-            foreach (var filter in filters)
+            this.rawMemory = rawMemory;
+            ColorSpaceDetails = colorSpaceDetails;
+
+            if (!rawMemory.IsEmpty)
             {
-                if (!filter.IsSupported)
+                var filters = filterProvider.GetNamedFilters(filterNames);
+
+                var supportsFilters = true;
+                foreach (var filter in filters)
                 {
-                    supportsFilters = false;
-                    break;
+                    if (!filter.IsSupported)
+                    {
+                        supportsFilters = false;
+                        break;
+                    }
                 }
-            }
 
-            memoryFactory = supportsFilters ? new Lazy<Memory<byte>>(() =>
-            {
-                var b = RawMemory;
-                for (var i = 0; i < filters.Count; i++)
+                memoryFactory = supportsFilters ? new Lazy<Memory<byte>>(() =>
                 {
-                    var filter = filters[i];
-                    b = filter.Decode(b, streamDictionary, filterProvider, i);
-                }
+                    var b = RawMemory;
+                    for (var i = 0; i < filters.Count; i++)
+                    {
+                        var filter = filters[i];
+                        b = filter.Decode(b, streamDictionary, filterProvider, i);
+                    }
+
+                    return b;
+                }) : null;
+            }
 
-                return b;
-            }) : null;
-
             MaskImage = softMaskImage;
         }
 
@@ -143,6 +150,6 @@ public bool TryGetBytesAsMemory(out Memory<byte> bytes)
         public override string ToString()
         {
             return $"Inline Image (w {BoundingBox.Width}, h {BoundingBox.Height})";
-        }
+        }
     }
 }

src/UglyToad.PdfPig/Graphics/BaseStreamProcessor.cs

@@ -215,7 +215,7 @@ public virtual void PushState()
         /// <inheritdoc/>
         public void ShowText(IInputBytes bytes)
         {
-            TextSequence++;
+            TextSequence++;
 
             var currentState = GetCurrentState();
 
@@ -435,8 +435,16 @@ public virtual void ApplyXObject(NameToken xObjectName)
             }
             else if (subType.Equals(NameToken.Image))
             {
+                var imageStream = xObjectStream;
+                if (!ParsingOptions.EagerlyLoadImageBytes)
+                {
+                    // Replace the stream data with empty bytes so we dont hold image data in memory.
+                    // The dictionary is kept for metadata (width, height, etc).
+                    imageStream = new StreamToken(xObjectStream.StreamDictionary, Memory<byte>.Empty);
+                }
+
                 var contentRecord = new XObjectContentRecord(XObjectType.Image,
-                    xObjectStream,
+                    imageStream,
                     matrix,
                     state.RenderingIntent,
                     state.ColorSpaceContext?.CurrentStrokingColorSpace ?? DeviceRgbColorSpaceDetails.Instance);
@@ -565,7 +573,7 @@ protected virtual void ProcessFormXObject(StreamToken formStream, NameToken xObj
                         .ToArray());
             }
 
-            // 2. Update current transformation matrix.
+            // 2. Update current transformation matrix.
             ModifyCurrentTransformationMatrix(formMatrix);
 
             var contentStream = formStream.Decode(FilterProvider, PdfScanner);
@@ -587,7 +595,7 @@ protected virtual void ProcessFormXObject(StreamToken formStream, NameToken xObj
             if (hasCircularReference)
             {
                 if (ParsingOptions.UseLenientParsing)
-                {
+                {
                     // TODO - We might be removing too much, good for the moment. See Issues1250() for examples
                     operations = operations.Where(o => o is not InvokeNamedXObject xo || xo.Name != xObjectName)
                         .ToArray();
@@ -635,21 +643,21 @@ protected virtual bool HasFormXObjectCircularReference(StreamToken formStream,
             if (!TryGetXObjectToken(formStream, xObjectName, PdfScanner, out var t1))
             {
                 return false;
-            }
-
+            }
+
             if (!ResourceStore.TryGetXObject(xObjectName, out var resourceStream))
             {
                 return false;
-            }
-
+            }
+
             if (!TryGetXObjectToken(resourceStream, xObjectName, PdfScanner, out var t2))
             {
                 return false;
-            }
-            
-            if (t1 is null || t2 is null)
-            {
-                return false;
+            }
+            
+            if (t1 is null || t2 is null)
+            {
+                return false;
             }
 
             return t1.Equals(t2);
@@ -660,8 +668,8 @@ static bool TryGetXObjectToken(StreamToken streamToken, NameToken xObjectName, I
                 if (!streamToken.StreamDictionary.TryGet<DictionaryToken>(NameToken.Resources, scanner, out var formResources))
                 {
                     return false;
-                }
-
+                }
+
                 if (!formResources.TryGet<DictionaryToken>(NameToken.Xobject, out var xObjectBase) || !xObjectBase.TryGet(xObjectName, out token))
                 {
                     return false;
@@ -887,7 +895,7 @@ public virtual void EndInlineImage(Memory<byte> bytes)
                 return;
             }
 
-            InlineImageBuilder.Bytes = bytes;
+            InlineImageBuilder.Bytes = ParsingOptions.EagerlyLoadImageBytes ? bytes : Memory<byte>.Empty;
 
             var image = InlineImageBuilder.CreateInlineImage(CurrentTransformationMatrix,
                 FilterProvider,
@@ -1004,7 +1012,7 @@ public virtual void SetWordSpacing(double spacing)
         /// <inheritdoc/>
         public virtual void ModifyCurrentTransformationMatrix(TransformationMatrix value)
         {
-            var state = GetCurrentState();
+            var state = GetCurrentState();
             state.CurrentTransformationMatrix = value.Multiply(state.CurrentTransformationMatrix);
         }
 

src/UglyToad.PdfPig/ParsingOptions.cs

@@ -63,5 +63,15 @@ public sealed class ParsingOptions
         /// Filter provider to use while parsing the document. The <see cref="DefaultFilterProvider"/> will be used if set to <c>null</c>.
         /// </summary>
         public IFilterProvider? FilterProvider { get; set; } = null;
+
+        /// <summary>
+        /// Whether to load image byte data when enumerating images on a page.
+        /// When <see langword="true"/> (the default), image bytes are available via <see cref="Content.IPdfImage.RawMemory"/>
+        /// and <see cref="Content.IPdfImage.TryGetBytesAsMemory(out System.Memory{byte})"/>.
+        /// When <see langword="false"/>, image metadata (width, height, bounding box, color space, etc.)
+        /// is still available but image byte data is not retained, reducing memory usage
+        /// for documents with large or numerous images.
+        /// </summary>
+        public bool EagerlyLoadImageBytes { get; set; } = true;
     }
 }