add the unlicense, remove unused code and add documentation

.gitignore

@@ -31,6 +31,9 @@ bld/
 [Tt]est[Rr]esult*/
 [Bb]uild[Ll]og.*
 
+# Doc comments xml
+src/BigGustave/BigGustave.xml
+
 # NUNIT
 *.VisualState.xml
 TestResult.xml

LICENSE

@@ -0,0 +1,24 @@
+This is free and unencumbered software released into the public domain.
+
+Anyone is free to copy, modify, publish, use, compile, sell, or
+distribute this software, either in source code form or as a compiled
+binary, for any purpose, commercial or non-commercial, and by any
+means.
+
+In jurisdictions that recognize copyright laws, the author or authors
+of this software dedicate any and all copyright interest in the
+software to the public domain. We make this dedication for the benefit
+of the public at large and to the detriment of our heirs and
+successors. We intend this dedication to be an overt act of
+relinquishment in perpetuity of all present and future rights to this
+software under copyright law.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+IN NO EVENT SHALL THE AUTHORS BE LIABLE FOR ANY CLAIM, DAMAGES OR
+OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
+ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
+OTHER DEALINGS IN THE SOFTWARE.
+
+For more information, please refer to <http://unlicense.org>

README.md

@@ -2,15 +2,29 @@
 
 [![Build status](https://ci.appveyor.com/api/projects/status/nh12x7vg36qxunp0?svg=true)](https://ci.appveyor.com/project/EliotJones/biggustave)
 
-An attempt at PNG decoding according to the PNG spec using .NET standard libraries only.
+Open, read and create PNG images in fully managed C#.
 
 ## Usage ##
 
-Still being written but the idea is calling:
+To open a PNG image from file and get some pixel values:
 
-    Png png = Png.Open(Stream stream)
+    using (var stream = File.OpenRead(@"C:\my\file\path\file.png"))
+    {
+        Png image = Png.Open(stream);
 
-Will return a PNG object.
+        Pixel pixel = image.GetPixel(image.Width - 1, image.Height - 1);
+
+        int pixelRedAverage = 0;
+
+        pixelRedAverage += pixel.R;
+
+        pixel = image.GetPixel(0, 0);
+
+        pixelRedAverage += pixel.R;
+
+        Console.WriteLine(pixelRedAverage / 2.0);       
+        
+    }
 
 The PNG object has methods to inspect the header and get the pixel values. The header has properties for:
 
@@ -35,4 +49,25 @@ To get a pixel use:
 
     Pixel pixel = png.GetPixel(0, 7);
 
-Where the first argument is x (column) and the second is y (row). The `Pixel` is used for all image types, e.g. Grayscale, Colour, with/without transparency.
+Where the first argument is x (column) and the second is y (row). The `Pixel` is used for all image types, e.g. Grayscale, Colour, with/without transparency.
+
+## Creation ##
+
+Because of some issues with ZLib compatibility the created images work with most, but not all image viewers. Of the viewers tested the images work with all browsers, Paint, Gimp, Paint3D etc.
+
+To create a PNG use:
+
+    var builder = PngBuilder.Create(2, 2, false);
+
+    var red = new Pixel(255, 0, 12, 255, false);
+    var black = new Pixel(0, 0, 0, 255, false);
+
+    builder.SetPixel(new Pixel(255, 0, 12, 255, false), 0, 0);
+    builder.SetPixel(new Pixel(255, 0, 12, 255, false), 1, 1);
+
+    using (var memory = new MemoryStream())
+    {
+        builder.Save(memory);
+        
+        return memory.ToArray();
+    }

src/BigGustave.Tests/PngBuilderTests.cs

@@ -34,5 +34,28 @@ public void SimpleCheckerboard()
                 Assert.Equal(red, bottomRight);
             }
         }
+
+        [Fact]
+        public void BiggerImage()
+        {
+            var builder = PngBuilder.Create(10, 10, false);
+
+            var green = new Pixel(0, 255, 25, 255, false);
+            var color1 = new Pixel(60, 201, 32, 255, false);
+            var color2 = new Pixel(100, 5, 250, 255, false);
+
+            builder.SetPixel(green, 1, 1).SetPixel(green, 2, 1).SetPixel(green, 3, 1).SetPixel(green, 4, 1).SetPixel(green, 5, 1);
+
+            builder.SetPixel(color1, 5, 7).SetPixel(color1, 5, 8)
+                .SetPixel(color1, 6, 7).SetPixel(color1, 6, 8)
+                .SetPixel(color1, 7, 7).SetPixel(color1, 7, 8);
+
+            builder.SetPixel(color2, 9, 9).SetPixel(color2, 8, 8);
+
+            using (var memoryStream = new MemoryStream())
+            {
+                builder.Save(memoryStream);
+            }
+        }
     }
 }

src/BigGustave/Adam7.cs

@@ -1,6 +1,5 @@
 namespace BigGustave
 {
-    using System;
     using System.Collections.Generic;
 
     internal static class Adam7

src/BigGustave/BigGustave.csproj

@@ -3,6 +3,15 @@
   <PropertyGroup>
     <TargetFramework>netstandard2.0</TargetFramework>
     <LangVersion>7.2</LangVersion>
+    <Description>Open, read and create PNG images.</Description>
+    <RepositoryUrl>https://github.com/EliotJones/BigGustave</RepositoryUrl>
+    <PackageIconUrl>https://raw.githubusercontent.com/UglyToad/DataTable/master/uglytoadsmall.png</PackageIconUrl>
+    <PackageLicenseUrl>https://github.com/EliotJones/BigGustave/blob/master/LICENSE</PackageLicenseUrl>
+    <PackageProjectUrl>https://github.com/EliotJones/BigGustave</PackageProjectUrl>
+  </PropertyGroup>
+
+  <PropertyGroup Condition="'$(Configuration)|$(Platform)'=='Debug|AnyCPU'">
+    <DocumentationFile>C:\git\csharp\BigGustave\src\BigGustave\BigGustave.xml</DocumentationFile>
   </PropertyGroup>
 
 </Project>

src/BigGustave/ChunkHeader.cs

@@ -2,6 +2,9 @@
 {
     using System;
 
+    /// <summary>
+    /// The header for a data chunk in a PNG file.
+    /// </summary>
     public readonly struct ChunkHeader
     {
         /// <summary>
@@ -19,10 +22,25 @@ public readonly struct ChunkHeader
         /// </summary>
         public string Name { get; }
 
+        /// <summary>
+        /// Whether the chunk is critical (must be read by all readers) or ancillary (may be ignored).
+        /// </summary>
         public bool IsCritical => char.IsUpper(Name[0]);
+
+        /// <summary>
+        /// A public chunk is one that is defined in the International Standard or is registered in the list of public chunk types maintained by the Registration Authority. 
+        /// Applications can also define private (unregistered) chunk types for their own purposes.
+        /// </summary>
         public bool IsPublic => char.IsUpper(Name[1]);
+
+        /// <summary>
+        /// Whether the (if unrecognized) chunk is safe to copy.
+        /// </summary>
         public bool IsSafeToCopy => char.IsUpper(Name[3]);
 
+        /// <summary>
+        /// Create a new <see cref="ChunkHeader"/>.
+        /// </summary>
         public ChunkHeader(long position, int length, string name)
         {
             if (length < 0)
@@ -35,6 +53,7 @@ public ChunkHeader(long position, int length, string name)
             Name = name;
         }
 
+        /// <inheritdoc />
         public override string ToString()
         {
             return $"{Name} at {Position} (length: {Length}).";

src/BigGustave/ColorType.cs

@@ -8,9 +8,21 @@
     [Flags]
     public enum ColorType : byte
     {
+        /// <summary>
+        /// Grayscale.
+        /// </summary>
         None = 0,
+        /// <summary>
+        /// Colors are stored in a palette rather than directly in the data.
+        /// </summary>
         PaletteUsed = 1,
+        /// <summary>
+        /// The image uses color.
+        /// </summary>
         ColorUsed = 2,
+        /// <summary>
+        /// The image has an alpha channel.
+        /// </summary>
         AlphaChannelUsed = 4
     }
 }

src/BigGustave/Crc32.cs

@@ -2,6 +2,9 @@
 {
     using System.Collections.Generic;
 
+    /// <summary>
+    /// 32-bit Cyclic Redundancy Code used by the PNG for checking the data is intact.
+    /// </summary>
     public static class Crc32
     {
         private const uint Polynomial = 0xEDB88320;
@@ -30,6 +33,9 @@ static Crc32()
             }
         }
 
+        /// <summary>
+        /// Calculate the CRC32 for data.
+        /// </summary>
         public static uint Calculate(byte[] data)
         {
             var crc32 = uint.MaxValue;
@@ -42,6 +48,9 @@ public static uint Calculate(byte[] data)
             return crc32 ^ uint.MaxValue;
         }
 
+        /// <summary>
+        /// Calculate the CRC32 for data.
+        /// </summary>
         public static uint Calculate(List<byte> data)
         {
             var crc32 = uint.MaxValue;
@@ -54,6 +63,9 @@ public static uint Calculate(List<byte> data)
             return crc32 ^ uint.MaxValue;
         }
 
+        /// <summary>
+        /// Calculate the combined CRC32 for data.
+        /// </summary>
         public static uint Calculate(byte[] data, byte[] data2)
         {
             var crc32 = uint.MaxValue;

src/BigGustave/Decoder.cs

@@ -208,28 +208,4 @@ private static byte GetPaethValue(byte a, byte b, byte c)
             return pb <= pc ? b : c;
         }
     }
-
-    public enum FilterType
-    {
-        /// <summary>
-        /// The raw byte is unaltered.
-        /// </summary>
-        None = 0,
-        /// <summary>
-        /// The byte to the left.
-        /// </summary>
-        Sub = 1,
-        /// <summary>
-        /// The byte above.
-        /// </summary>
-        Up = 2,
-        /// <summary>
-        /// The mean of bytes left and above, rounded down.
-        /// </summary>
-        Average = 3,
-        /// <summary>
-        /// Byte to the left, above or top-left based on Paeth's algorithm.
-        /// </summary>
-        Paeth = 4
-    }
 }

src/BigGustave/FilterType.cs

@@ -0,0 +1,26 @@
+namespace BigGustave
+{
+    internal enum FilterType
+    {
+        /// <summary>
+        /// The raw byte is unaltered.
+        /// </summary>
+        None = 0,
+        /// <summary>
+        /// The byte to the left.
+        /// </summary>
+        Sub = 1,
+        /// <summary>
+        /// The byte above.
+        /// </summary>
+        Up = 2,
+        /// <summary>
+        /// The mean of bytes left and above, rounded down.
+        /// </summary>
+        Average = 3,
+        /// <summary>
+        /// Byte to the left, above or top-left based on Paeth's algorithm.
+        /// </summary>
+        Paeth = 4
+    }
+}