Added functionality to abstract the reading of text/binary STLs (see STLDocument.Read) (fixes #2); commented the codebase (fixes #3); binary STLs now write the AttributeByteCount value for facets (fixes #4); added functionality to convert an STL document between text and binary format (see STLDocument.CopyAsText and STLDocument.CopyAsBinary) (fixes #5).

Author: JoshMcCullough

Source/STL/Facet.cs

@@ -8,17 +8,29 @@
 
 namespace QuantumConcepts.Formats.StereoLithography
 {
-    public class Facet : IEquatable<Facet>
+    /// <summary>A representation of a facet which is defined by its location (<see cref="Vertices"/>) and directionality (<see cref="Normal"/>).</summary>
+    public class Facet : IEquatable<Facet>, IEnumerable<Vertex>
     {
+        /// <summary>Indicates the directionality of the <see cref="Facet"/>.</summary>
         public Normal Normal { get; set; }
-        public List<Vertex> Vertices { get; set; }
+
+        /// <summary>Indicates the location of the <see cref="Facet"/>.</summary>
+        public IList<Vertex> Vertices { get; set; }
+
+        /// <summary>Additional data attached to the facet.</summary>
+        /// <remarks>Depending on the source of the STL, this could be used to indicate such things as the color of the <see cref="Facet"/>. This functionality only exists in binary STLs.</remarks>
         public int AttributeByteCount { get; set; }
 
+        /// <summary>Creates a new, empty <see cref="Facet"/>.</summary>
         public Facet()
         {
             this.Vertices = new List<Vertex>();
         }
 
+        /// <summary>Creates a new <see cref="Facet"/> using the provided parameters.</summary>
+        /// <param name="normal">The directionality of the <see cref="Facet"/>.</param>
+        /// <param name="vertices">The location of the <see cref="Facet"/>.</param>
+        /// <param name="attributeByteCount">Additional data to attach to the <see cref="Facet"/>.</param>
         public Facet(Normal normal, IEnumerable<Vertex> vertices, int attributeByteCount)
             : this()
         {
@@ -27,6 +39,8 @@ public Facet(Normal normal, IEnumerable<Vertex> vertices, int attributeByteCount
             this.AttributeByteCount = attributeByteCount;
         }
 
+        /// <summary>Reads a single <see cref="Facet"/> from the <paramref name="reader"/>.</summary>
+        /// <param name="reader">The reader which contains a <see cref="Facet"/> to be read at the current position</param>
         public static Facet Read(StreamReader reader)
         {
             if (reader == null)
@@ -52,6 +66,8 @@ public static Facet Read(StreamReader reader)
             return facet;
         }
 
+        /// <summary>Reads a single <see cref="Facet"/> from the <paramref name="reader"/>.</summary>
+        /// <param name="reader">The reader which contains a <see cref="Facet"/> to be read at the current position</param>
         public static Facet Read(BinaryReader reader)
         {
             if (reader == null)
@@ -72,6 +88,8 @@ public static Facet Read(BinaryReader reader)
             return facet;
         }
 
+        /// <summary>Writes the <see cref="Facet"/> as text to the <paramref name="writer"/>.</summary>
+        /// <param name="writer">The writer to which the <see cref="Facet"/> will be written at the current position.</param>
         public void Write(StreamWriter writer)
         {
             writer.Write("\t");
@@ -84,26 +102,46 @@ public void Write(StreamWriter writer)
             writer.WriteLine("\t\tendloop");
             writer.WriteLine("\tendfacet");
         }
-        
+
+        /// <summary>Writes the <see cref="Facet"/> as binary to the <paramref name="writer"/>.</summary>
+        /// <param name="writer">The writer to which the <see cref="Facet"/> will be written at the current position.</param>
         public void Write(BinaryWriter writer)
         {
             //Write the normal.
             this.Normal.Write(writer);
 
             //Write each vertex.
             this.Vertices.ForEach(o => o.Write(writer));
+
+            //Write the attribute byte count.
+            writer.Write(this.AttributeByteCount);
         }
 
+        /// <summary>Returns the string representation of this <see cref="Facet"/>.</summary>
         public override string ToString()
         {
             return "facet {0}".FormatString(this.Normal);
         }
 
+        /// <summary>Determines whether or not this instance is the same as the <paramref name="other"/> instance.</summary>
+        /// <param name="other">The <see cref="Facet"/> to which to compare.</param>
         public bool Equals(Facet other)
         {
             return (this.Normal.Equals(other.Normal)
                     && this.Vertices.Count == other.Vertices.Count
                     && this.Vertices.All((i, o) => o.Equals(other.Vertices[i])));
         }
+
+        /// <summary>Iterates through the <see cref="Vertices"/> collection.</summary>
+        public IEnumerator<Vertex> GetEnumerator()
+        {
+            return this.Vertices.GetEnumerator();
+        }
+
+        /// <summary>Iterates through the <see cref="Vertices"/> collection.</summary>
+        System.Collections.IEnumerator System.Collections.IEnumerable.GetEnumerator()
+        {
+            return GetEnumerator();
+        }
     }
 }

Source/STL/Normal.cs

@@ -7,28 +7,33 @@
 
 namespace QuantumConcepts.Formats.StereoLithography
 {
+    /// <summary>A simple XYZ representation of a normal (<see cref="Vertex"/>).</summary>
     public class Normal : Vertex
     {
-        public Normal() { }
+        /// <summary>Creates a new, empty <see cref="Normal"/>.</summary>
+        public Normal() : base() { }
 
-        public Normal(decimal x, decimal y, decimal z)
-            : this()
-        {
-            this.X = x;
-            this.Y = y;
-            this.Z = z;
-        }
+        /// <summary>Creates a new <see cref="Normal"/> using the provided coordinates.</summary>
+        public Normal(decimal x, decimal y, decimal z) : base(x, y, z) { }
 
+        /// <summary>Reads a single <see cref="Normal"/> from the <paramref name="reader"/>.</summary>
+        /// <param name="reader">The reader which contains a <see cref="Normal"/> to be read at the current position</param>
         public static Normal Read(StreamReader reader)
         {
             return Normal.FromVertex(Vertex.Read(reader));
         }
 
+        /// <summary>Reads a single <see cref="Normal"/> from the <paramref name="reader"/>.</summary>
+        /// <param name="reader">The reader which contains a <see cref="Normal"/> to be read at the current position</param>
         public static Normal Read(BinaryReader reader)
         {
             return Normal.FromVertex(Vertex.Read(reader));
         }
 
+        /// <summary>Converts the <paramref name="vertex"/> to a normal.</summary>
+        /// <remarks>This does nothing more than copy the X, Y and Z coordinates of the <paramref name="vertex"/> into a new <see cref="Normal"/> instance.</remarks>
+        /// <param name="vertex">The <see cref="Vertex"/> to be converted into a <see cref="Normal"/>.</param>
+        /// <returns>A <see cref="Normal"/> or null if the <paramref name="vertex"/> is null.</returns>
         public static Normal FromVertex(Vertex vertex)
         {
             if (vertex == null)
@@ -42,6 +47,7 @@ public static Normal FromVertex(Vertex vertex)
             };
         }
 
+        /// <summary>Returns the string representation of this <see cref="Normal"/>.</summary>
         public override string ToString()
         {
             return "normal {0} {1} {2}".FormatString(this.X, this.Y, this.Z);

Source/STL/Properties/AssemblyInfo.cs

@@ -8,5 +8,5 @@
 [assembly: AssemblyProduct("STL Format Reader and Writer")]
 [assembly: AssemblyCopyright("Copyright © Quantum Concepts Corporation")]
 [assembly: AssemblyTrademark("Copyright © Quantum Concepts Corporation")]
-[assembly: AssemblyVersion("1.0.0.0")]
-[assembly: AssemblyFileVersion("1.0.0.0")]
+[assembly: AssemblyVersion("1.1.0.0")]
+[assembly: AssemblyFileVersion("1.1.0.0")]

Source/STL/QuantumConcepts.Formats.STL.dll.nuspec

@@ -2,7 +2,7 @@
 <package >
   <metadata>
     <id>QuantumConcepts.Formats.STL</id>
-    <version>1.0.0.1</version>
+    <version>1.1.0.0</version>
     <title>Quantum Concepts STLdotNET</title>
     <authors>Quantum Concepts</authors>
     <owners>Quantum Concepts</owners>
@@ -11,8 +11,8 @@
     <iconUrl>http://quantumconceptscorp.com/Resources/Images/QCLogoButton-32.png</iconUrl>
     <requireLicenseAcceptance>false</requireLicenseAcceptance>
     <description>This library facilitates the reading and writing of Stereo Lithograph (STL) files.</description>
-    <releaseNotes>This is the initial release which includes all basic features required to read/write STL files.</releaseNotes>
-    <copyright>Copyright 2013 Quantum Concepts Corporation, released under the GNU Affero General Public License./</copyright>
+    <releaseNotes>Added functionality to abstract the reading of text/binary STLs (see STLDocument.Read); commented the codebase; binary STLs now write the AttributeByteCount value for facets; added functionality to convert an STL document between text and binary format (see STLDocument.CopyAsText and STLDocument.CopyAsBinary).</releaseNotes>
+    <copyright>Copyright 2014 Quantum Concepts Corporation, released under the GNU Affero General Public License./</copyright>
     <tags>3d reprap stl</tags>
     <dependencies>
       <dependency id="QuantumConcepts.Common" version="1.0" />