revert change to public api of letter. update readme

README.md

@@ -10,6 +10,40 @@ This project allows users to read text content from PDF files.
 
 This project aims to port [PDFBox](https://github.com/apache/pdfbox) to C#.
 
+## Get Started ##
+
+The simplest usage at this stage is to open a document, reading the words from every page:
+
+    using (PdfDocument document = PdfDocument.Open(@"C:\Documents\document.pdf"))
+    {
+        for (var i = 0; i < document.NumberOfPages; i++)
+        {
+            // This starts at 1 rather than 0.
+            var page = document.GetPage(i + 1);
+
+            foreach (var word in page.GetWords())
+            {
+                Console.WriteLine(word.Text);
+            }
+        }
+    }
+
+## Installation ##
+
+The package is available via the releases tab or from Nuget:
+
+https://www.nuget.org/packages/PdfPig/
+
+Or from the package manager console:
+
+    > Install-Package PdfPig
+
+While the version is below 1.0.0 minor versions will change the public API without warning (SemVer will not be followed until 1.0.0 is reached).
+
+## API Changes ##
+
++ 0.0.3 - Changes to position data for ```Letter```. Letter has a Location, Width and GlyphRectangle property. Consult the [Wiki](https://github.com/UglyToad/PdfPig/wiki/Letters) for details of the new API. Adds ```PdfDocument.Structure``` property allowing access to raw data.
+
 ## Usage ##
 
 The ```PdfDocument``` class provides access to the contents of a document loaded either from file or passed in as bytes. To open from a file use the ```PdfDocument.Open``` static method:
@@ -31,7 +65,7 @@ The ```PdfDocument``` class provides access to the contents of a document loaded
 
 ```PdfDocument``` should only be used in a ```using``` statement since it implements ```IDisposable``` (unless the consumer disposes of it elsewhere).
 
-Since this is alpha software the consumer should wrap all access in a ```try catch``` block since it is extremely likely to throw exceptions. As a fallback you can try running PDFBox using [IKVM](https://www.ikvm.net/) or using [PDFsharp](http://www.pdfsharp.net).
+Since this is alpha software the consumer should wrap all access in a ```try catch``` block since it is extremely likely to throw exceptions. As a fallback you can try running PDFBox using [IKVM](https://www.ikvm.net/) or using [PDFsharp](http://www.pdfsharp.net) or by a native library wrapper using [docnet](https://github.com/GowenGit/docnet).
 
 The document contains the version of the PDF specification it complies with, accessed by ```document.Version```:
 
@@ -50,6 +84,19 @@ The ```PdfDocument``` provides access to the document metadata as ```DocumentInf
     string title = document.Information.Title;
     // etc...
 
+### Document Structure ###
+
+New in 0.0.3 the document now has a Structure member:
+
+    UglyToad.PdfPig.Structure structure = document.Structure;
+
+This provides access to tokenized PDF document content:
+
+    Catalog catalog = structure.Catalog;
+    DictionaryToken pagesDictionary = catalog.PagesDictionary;
+
+The pages dictionary is the root of the pages tree within a PDF document. The structure also exposes a ```GetObject(IndirectReference reference)```  method which allows random access to any object in the PDF as long as its identifier number is known. This is an identifier of the form ```69 0 R``` where 69 is the object number and 0 is the generation.
+
 ### Page ###
 
 The ```Page``` contains the page width and height in points as well as mapping to the ```PageSize``` enum:
@@ -62,6 +109,16 @@ The ```Page``` contains the page width and height in points as well as mapping t
 
     string text = page.Text;
 
+There is a new (0.0.3) method which provides access to the words. This uses basic heuristics and is not reliable or well-tested:
+
+    IEnumerable<Word> words = page.GetWords();
+
+There is also an early access (0.0.3) API for retrieving the raw bytes of PDF image objects per page:
+
+    IEnumerable<XObjectImage> images = page.ExperimentalAccess.GetRawImages();
+
+This API will be changed in future releases.
+
 ### Letter ###
 
 Due to the way a PDF is structured internally the page text may not be a readable representation of the text as it appears in the document. Since PDF is a presentation format, text can be drawn in any order, not necessarily reading order. This means spaces may be missing or words may be in unexpected positions in the text.
@@ -78,17 +135,12 @@ These letters contain:
 + The width of the letter: ```letter.Width```.
 + The font size in unscaled relative text units (these sizes are internal to the PDF and do not correspond to sizes in pixels, points or other units): ```letter.FontSize```.
 + The name of the font used to render the letter if available: ```letter.FontName```.
++ A rectangle which is the smallest rectangle that completely contains the visible region of the letter/glyph: ```letter.GlyphRectangle```.
 
-Letter position is measured in PDF coordinates where the origin is the lower left corner of the page. Therefore an higher Y value means closer to the top of the page.
+Letter position is measured in PDF coordinates where the origin is the lower left corner of the page. Therefore a higher Y value means closer to the top of the page.
 
 At this stage letter position is experimental and **will change in future versions**! Do not rely on letter positions remaining constant between different versions of this package.
 
-## Installation ##
-
-The **pre-release** package is available via the releases tab or from Nuget:
-
-https://www.nuget.org/packages/PdfPig/
-
 ## Issues ##
 
 At this stage the software is in Alpha. In order to proceed to Beta and production we need to see a wide variety of document types.
@@ -101,7 +153,7 @@ Issues on unplanned features are off topic for now and will probably be closed w
 
 ## Status ##
 
-*Why is class or property X internal?* With the exception of ```letter.Position``` internal properties and classes are not stable enough for the end user yet. If you want to access them feel free to use reflection but be aware they may change or disappear between versions.
+*Why is class or property X internal?* With the exception of ```letter.Location``` and ```XObjectImage``` internal properties and classes are not stable enough for the end user yet. If you want to access them feel free to use reflection but be aware they may change or disappear between versions.
 
 The initial version of this package aims only to support reading text content from unencrypted PDF files. Due to the legal and dependency consequences of decrypting, handling encrypted documents is not in scope.
 

src/UglyToad.PdfPig.Tests/Integration/AssertablePositionData.cs

@@ -47,7 +47,7 @@ public void AssertWithinTolerance(Letter letter, Page page, bool includeHeight =
         {
             Assert.Equal(Text, letter.Value);
             Assert.Equal(FontName, letter.FontName);
-            Assert.Equal(X, letter.Origin.X, 1);
+            Assert.Equal(X, letter.Location.X, 1);
             Assert.Equal(Width, letter.Width, 1);
             if (includeHeight)
             {

src/UglyToad.PdfPig.Tests/Integration/SinglePageNonLatinAcrobatDistillerTests.cs

@@ -68,7 +68,7 @@ public void LetterPositionsAreCorrectPdfBox()
                         break;
                     }
 
-                    var myX = pageLetter.Origin.X;
+                    var myX = pageLetter.Location.X;
                     var theirX = pdfBoxData[index].X;
 
                     var myLetter = pageLetter.Value;
@@ -111,7 +111,7 @@ public void LetterPositionsAreCorrectXfinium()
                         break;
                     }
 
-                    var myX = pageLetter.Origin.X;
+                    var myX = pageLetter.Location.X;
                     var theirX = positions[index].X;
 
                     var myLetter = pageLetter.Value;

src/UglyToad.PdfPig.Tests/Integration/SinglePageSimpleGoogleChromeTests.cs

@@ -132,9 +132,9 @@ public void LettersHavePdfBoxPositions()
                     }
 
                     Assert.Equal(datum.Text, letter.Value);
-                    Assert.Equal(datum.X, letter.Origin.X, 2);
+                    Assert.Equal(datum.X, letter.Location.X, 2);
 
-                    var transformed = page.Height - letter.Origin.Y;
+                    var transformed = page.Height - letter.Location.Y;
                     Assert.Equal(datum.Y, transformed, 2);
 
                     Assert.Equal(datum.Width, letter.Width, 2);
@@ -177,9 +177,9 @@ public void LettersHaveOtherProviderPositions()
                     }
 
                     Assert.Equal(datum.Text, letter.Value);
-                    Assert.Equal(datum.X, letter.Origin.X, 2);
+                    Assert.Equal(datum.X, letter.Location.X, 2);
 
-                    var transformed = page.Height - letter.Origin.Y;
+                    var transformed = page.Height - letter.Location.Y;
                     Assert.Equal(datum.Y, transformed, 2);
 
                     // Until we get width from glyphs we're a bit out.

src/UglyToad.PdfPig/Content/Letter.cs

@@ -15,7 +15,7 @@ public class Letter
         /// <summary>
         /// The placement position of the character in PDF space.
         /// </summary>
-        public PdfPoint Origin { get; }
+        public PdfPoint Location { get; }
 
         /// <summary>
         /// The width occupied by the character within the PDF content.
@@ -24,7 +24,7 @@ public class Letter
 
         /// <summary>
         /// Position of the bounding box for the glyph, this is the box surrounding the visible glyph as it appears on the page.
-        /// For example letters with descenders, p, j, etc., will have a box extending below the <see cref="Origin"/> they are placed at.
+        /// For example letters with descenders, p, j, etc., will have a box extending below the <see cref="Location"/> they are placed at.
         /// The width of the glyph may also be more or less than the <see cref="Width"/> allocated for the character in the PDF content.
         /// </summary>
         public PdfRectangle GlyphRectangle { get; }
@@ -47,14 +47,14 @@ public class Letter
         /// <summary>
         /// Create a new letter to represent some text drawn by the Tj operator.
         /// </summary>
-        internal Letter(string value, PdfRectangle glyphRectangle, PdfPoint origin, decimal width, decimal fontSize, string fontName, decimal pointSize)
+        internal Letter(string value, PdfRectangle glyphRectangle, PdfPoint location, decimal width, decimal fontSize, string fontName, decimal pointSize)
         {
             Value = value;
             GlyphRectangle = glyphRectangle;
             FontSize = fontSize;
             FontName = fontName;
             PointSize = pointSize;
-            Origin = origin;
+            Location = location;
             Width = width;
         }
 
@@ -63,7 +63,7 @@ internal Letter(string value, PdfRectangle glyphRectangle, PdfPoint origin, deci
         /// </summary>
         public override string ToString()
         {
-            return $"{Value} {Origin} {FontName} {PointSize}";
+            return $"{Value} {Location} {FontName} {PointSize}";
         }
     }
 }

src/UglyToad.PdfPig/Content/Word.cs

@@ -43,9 +43,9 @@ public Word(IReadOnlyList<Letter> letters)
 
             Text = string.Join(string.Empty, letters.Select(x => x.Value));
 
-            var minX = letters.Min(x => x.Origin.X);
-            var minY = letters.Min(x => x.Origin.Y);
-            var maxX = letters.Max(x => x.Origin.X + x.Width);
+            var minX = letters.Min(x => x.Location.X);
+            var minY = letters.Min(x => x.Location.Y);
+            var maxX = letters.Max(x => x.Location.X + x.Width);
             var maxY = letters.Max(x => x.GlyphRectangle.Top);
 
             BoundingBox = new PdfRectangle(minX, minY, maxX, maxY);

src/UglyToad.PdfPig/Util/DefaultWordExtractor.cs

@@ -9,8 +9,8 @@ internal class DefaultWordExtractor : IWordExtractor
     {
         public IEnumerable<Word> GetWords(IReadOnlyList<Letter> letters)
         {
-            var lettersOrder = letters.OrderByDescending(x => x.Origin.Y)
-                .ThenBy(x => x.Origin.X);
+            var lettersOrder = letters.OrderByDescending(x => x.Location.Y)
+                .ThenBy(x => x.Location.X);
 
             var lettersSoFar = new List<Letter>(10);
 
@@ -21,12 +21,12 @@ public IEnumerable<Word> GetWords(IReadOnlyList<Letter> letters)
             {
                 if (!y.HasValue)
                 {
-                    y = letter.Origin.Y;
+                    y = letter.Location.Y;
                 }
 
                 if (!lastX.HasValue)
                 {
-                    lastX = letter.Origin.X;
+                    lastX = letter.Location.X;
                 }
 
                 if (lastLetter == null)
@@ -41,7 +41,7 @@ public IEnumerable<Word> GetWords(IReadOnlyList<Letter> letters)
                     continue;
                 }
 
-                if (letter.Origin.Y > y.Value + 0.5m)
+                if (letter.Location.Y > y.Value + 0.5m)
                 {
                     if (lettersSoFar.Count > 0)
                     {
@@ -54,15 +54,15 @@ public IEnumerable<Word> GetWords(IReadOnlyList<Letter> letters)
                         lettersSoFar.Add(letter);
                     }
 
-                    y = letter.Origin.Y;
-                    lastX = letter.Origin.X;
+                    y = letter.Location.Y;
+                    lastX = letter.Location.X;
                     lastLetter = letter;
 
                     continue;
                 }
 
-                var gap = letter.Origin.X - (lastLetter.Origin.X + lastLetter.Width);
-                var nextToLeft = letter.Origin.X < lastX.Value - 1;
+                var gap = letter.Location.X - (lastLetter.Location.X + lastLetter.Width);
+                var nextToLeft = letter.Location.X < lastX.Value - 1;
                 var nextBigSpace = gap > Math.Max(lastLetter.GlyphRectangle.Height, letter.GlyphRectangle.Height) * 0.39m;
                 var nextIsWhiteSpace = string.IsNullOrWhiteSpace(letter.Value);
                 var nextFontDiffers = !string.Equals(letter.FontName, lastLetter.FontName, StringComparison.OrdinalIgnoreCase) && gap > letter.Width * 0.1m;
@@ -84,7 +84,7 @@ public IEnumerable<Word> GetWords(IReadOnlyList<Letter> letters)
 
                 lastLetter = letter;
 
-                lastX = letter.Origin.X;
+                lastX = letter.Location.X;
             }
 
             if (lettersSoFar.Count > 0)