Image analytics documentation, samples, internalization (#2372)

* samples and documentation * addressing issue #1798 for the Image Analytics project.
dotnet · Feb 5, 2019 · 410a296 · 410a296
1 parent 05afe4e
commit 410a296
Show file tree

Hide file tree

Showing 21 changed files with 1,052 additions and 537 deletions.
diff --git a/docs/samples/Microsoft.ML.Samples/Dynamic/ImageAnalytics/ConvertToGrayScale.cs b/docs/samples/Microsoft.ML.Samples/Dynamic/ImageAnalytics/ConvertToGrayScale.cs
@@ -0,0 +1,57 @@
+using System.IO;
+using Microsoft.ML.Data;
+
+namespace Microsoft.ML.Samples.Dynamic
+{
+    public class ConvertToGrayscaleExample
+    {
+        // Sample that loads images from the file system, and converts them to grayscale. 
+        public static void ConvertToGrayscale()
+        {
+            var mlContext = new MLContext();
+
+            // Downloading a few images, and an images.tsv file, which contains a list of the files from the dotnet/machinelearning/test/data/images/.
+            // If you inspect the fileSystem, after running this line, an "images" folder will be created, containing 4 images, and a .tsv file
+            // enumerating the images. 
+            var imagesDataFile = SamplesUtils.DatasetUtils.DownloadImages();
+
+            // Preview of the content of the images.tsv file
+            //
+            // imagePath    imageType
+            // tomato.bmp   tomato
+            // banana.jpg   banana
+            // hotdog.jpg   hotdog
+            // tomato.jpg   tomato
+
+            var data = mlContext.Data.CreateTextLoader(new TextLoader.Arguments()
+            {
+                Columns = new[]
+                {
+                        new TextLoader.Column("ImagePath", DataKind.TX, 0),
+                        new TextLoader.Column("Name", DataKind.TX, 1),
+                 }
+            }).Read(imagesDataFile);
+
+            var imagesFolder = Path.GetDirectoryName(imagesDataFile);
+            // Image loading pipeline. 
+            var pipeline = mlContext.Transforms.LoadImages(imagesFolder, ("ImageObject", "ImagePath"))
+                           .Append(mlContext.Transforms.ConvertToGrayscale(("Grayscale", "ImageObject")));
+
+            var transformedData = pipeline.Fit(data).Transform(data);
+
+            // The transformedData IDataView contains the loaded images column, and the grayscaled column.
+            // Preview of the transformedData
+            var transformedDataPreview = transformedData.Preview();
+
+            // Preview of the content of the images.tsv file
+            // The actual images, in the Grayscale column are of type System.Drawing.Bitmap.
+            //
+            // ImagePath    Name        ImageObject                   Grayscale
+            // tomato.bmp   tomato      {System.Drawing.Bitmap}     {System.Drawing.Bitmap}
+            // banana.jpg   banana      {System.Drawing.Bitmap}     {System.Drawing.Bitmap}
+            // hotdog.jpg   hotdog      {System.Drawing.Bitmap}     {System.Drawing.Bitmap}
+            // tomato.jpg   tomato      {System.Drawing.Bitmap}     {System.Drawing.Bitmap}
+
+        }
+    }
+}
diff --git a/docs/samples/Microsoft.ML.Samples/Dynamic/ImageAnalytics/ExtractPixels.cs b/docs/samples/Microsoft.ML.Samples/Dynamic/ImageAnalytics/ExtractPixels.cs
@@ -0,0 +1,59 @@
+using System.IO;
+using Microsoft.ML.Data;
+
+namespace Microsoft.ML.Samples.Dynamic
+{
+    public class ExtractPixelsExample
+    {
+        // Sample that loads the images from the file system, resizes them (ExtractPixels requires a resizing operation), and extracts the 
+        // values of the pixels as a vector. 
+        public static void ExtractPixels()
+        {
+            var mlContext = new MLContext();
+
+            // Downloading a few images, and an images.tsv file, which contains a list of the files from the dotnet/machinelearning/test/data/images/.
+            // If you inspect the fileSystem, after running this line, an "images" folder will be created, containing 4 images, and a .tsv file
+            // enumerating the images. 
+            var imagesDataFile = SamplesUtils.DatasetUtils.DownloadImages();
+
+            // Preview of the content of the images.tsv file
+            //
+            // imagePath    imageType
+            // tomato.bmp   tomato
+            // banana.jpg   banana
+            // hotdog.jpg   hotdog
+            // tomato.jpg   tomato
+
+            var data = mlContext.Data.CreateTextLoader(new TextLoader.Arguments()
+            {
+                Columns = new[]
+                {
+                        new TextLoader.Column("ImagePath", DataKind.TX, 0),
+                        new TextLoader.Column("Name", DataKind.TX, 1),
+                }
+            }).Read(imagesDataFile);
+
+            var imagesFolder = Path.GetDirectoryName(imagesDataFile);
+            // Image loading pipeline. 
+            var pipeline = mlContext.Transforms.LoadImages(imagesFolder, ("ImageObject", "ImagePath"))
+                          .Append(mlContext.Transforms.Resize("ImageObject",imageWidth: 100 , imageHeight: 100 ))
+                          .Append(mlContext.Transforms.ExtractPixels("Pixels", "ImageObject"));
+
+
+            var transformedData = pipeline.Fit(data).Transform(data);
+
+            // The transformedData IDataView contains the loaded images now
+            //Preview of the transformedData
+            var transformedDataPreview = transformedData.Preview();
+
+            // Preview of the content of the images.tsv file
+            //
+            // ImagePath    Name        ImageObject                 "Pixels"
+            // tomato.bmp   tomato      {System.Drawing.Bitmap}     [ 255, 255, 255, ..... 232, 243, 226, ...
+            // banana.jpg   banana      {System.Drawing.Bitmap}     [ 255, 255, 255, ..... 90,  54,  43, ...
+            // hotdog.jpg   hotdog      {System.Drawing.Bitmap}     [ 255, 255, 255, ..... 132, 143, 126, ...
+            // tomato.jpg   tomato      {System.Drawing.Bitmap}     [ 255, 255, 255, ..... 16,  21,  23, ...
+
+        }
+    }
+}
diff --git a/docs/samples/Microsoft.ML.Samples/Dynamic/ImageAnalytics/LoadImage.cs b/docs/samples/Microsoft.ML.Samples/Dynamic/ImageAnalytics/LoadImage.cs
@@ -0,0 +1,55 @@
+using System.IO;
+using Microsoft.ML.Data;
+
+namespace Microsoft.ML.Samples.Dynamic
+{
+    public class LoadImageExample
+    {
+        // Loads the images of the imagesFolder into an IDataView. 
+        public static void LoadImage()
+        {
+            var mlContext = new MLContext();
+
+            // Downloading a few images, and an images.tsv file, which contains a list of the files from the dotnet/machinelearning/test/data/images/.
+            // If you inspect the fileSystem, after running this line, an "images" folder will be created, containing 4 images, and a .tsv file
+            // enumerating the images. 
+            var imagesDataFile = SamplesUtils.DatasetUtils.DownloadImages();
+
+            // Preview of the content of the images.tsv file
+            //
+            // imagePath    imageType
+            // tomato.bmp   tomato
+            // banana.jpg   banana
+            // hotdog.jpg   hotdog
+            // tomato.jpg   tomato
+
+            var data = mlContext.Data.CreateTextLoader(new TextLoader.Arguments()
+            {
+                Columns = new[]
+                {
+                        new TextLoader.Column("ImagePath", DataKind.TX, 0),
+                        new TextLoader.Column("Name", DataKind.TX, 1),
+                    }
+            }).Read(imagesDataFile);
+
+            var imagesFolder = Path.GetDirectoryName(imagesDataFile);
+            // Image loading pipeline. 
+            var pipeline = mlContext.Transforms.LoadImages(imagesFolder, ("ImageReal", "ImagePath"));
+            var transformedData = pipeline.Fit(data).Transform(data);
+
+            // The transformedData IDataView contains the loaded images now
+            //Preview of the transformedData
+            var transformedDataPreview = transformedData.Preview();
+
+            // Preview of the content of the images.tsv file
+            // The actual images, in the ImageReal column are of type System.Drawing.Bitmap.
+            //
+            // ImagePath    Name        ImageReal
+            // tomato.bmp   tomato      {System.Drawing.Bitmap}
+            // banana.jpg   banana      {System.Drawing.Bitmap}
+            // hotdog.jpg   hotdog      {System.Drawing.Bitmap}
+            // tomato.jpg   tomato      {System.Drawing.Bitmap}
+
+        }
+    }
+}
diff --git a/docs/samples/Microsoft.ML.Samples/Dynamic/ImageAnalytics/ResizeImage.cs b/docs/samples/Microsoft.ML.Samples/Dynamic/ImageAnalytics/ResizeImage.cs
@@ -0,0 +1,58 @@
+using System.IO;
+using Microsoft.ML.Data;
+
+namespace Microsoft.ML.Samples.Dynamic
+{
+    public class ResizeImageExample
+    {
+        // Example on how to load the images from the file system, and resize them. 
+        public static void ResizeImage()
+        {
+            var mlContext = new MLContext();
+
+            // Downloading a few images, and an images.tsv file, which contains a list of the files from the dotnet/machinelearning/test/data/images/.
+            // If you inspect the fileSystem, after running this line, an "images" folder will be created, containing 4 images, and a .tsv file
+            // enumerating the images. 
+            var imagesDataFile = SamplesUtils.DatasetUtils.DownloadImages();
+
+            // Preview of the content of the images.tsv file
+            //
+            // imagePath    imageType
+            // tomato.bmp   tomato
+            // banana.jpg   banana
+            // hotdog.jpg   hotdog
+            // tomato.jpg   tomato
+
+            var data = mlContext.Data.CreateTextLoader(new TextLoader.Arguments()
+            {
+                Columns = new[]
+                {
+                        new TextLoader.Column("ImagePath", DataKind.TX, 0),
+                        new TextLoader.Column("Name", DataKind.TX, 1),
+                }
+            }).Read(imagesDataFile);
+
+            var imagesFolder = Path.GetDirectoryName(imagesDataFile);
+            // Image loading pipeline. 
+            var pipeline = mlContext.Transforms.LoadImages(imagesFolder, ("ImageReal", "ImagePath"))
+                        .Append(mlContext.Transforms.Resize("ImageReal", imageWidth: 100, imageHeight: 100));
+
+
+            var transformedData = pipeline.Fit(data).Transform(data);
+
+            // The transformedData IDataView contains the loaded images now
+            //Preview of the transformedData
+            var transformedDataPreview = transformedData.Preview();
+
+            // Preview of the content of the images.tsv file
+            // The actual images, in the ImageReal column are of type System.Drawing.Bitmap.
+            //
+            // ImagePath    Name        ImageReal
+            // tomato.bmp   tomato      {System.Drawing.Bitmap}
+            // banana.jpg   banana      {System.Drawing.Bitmap}
+            // hotdog.jpg   hotdog      {System.Drawing.Bitmap}
+            // tomato.jpg   tomato      {System.Drawing.Bitmap}
+
+        }
+    }
+}
diff --git a/docs/samples/Microsoft.ML.Samples/Dynamic/Transforms/Concatenate.cs b/docs/samples/Microsoft.ML.Samples/Dynamic/Transforms/Concatenate.cs
@@ -15,7 +15,7 @@ public static void ConcatTransform()
             var mlContext = new MLContext();
 
             // Get a small dataset as an IEnumerable and them read it as ML.NET's data type.
-            IEnumerable<SamplesUtils.DatasetUtils.SampleInfertData> data = SamplesUtils.DatasetUtils.GetInfertData();
+            var data = SamplesUtils.DatasetUtils.GetInfertData();
             var trainData = mlContext.Data.ReadFromEnumerable(data);
 
             // Preview of the data.

diff --git a/docs/samples/Microsoft.ML.Samples/Program.cs b/docs/samples/Microsoft.ML.Samples/Program.cs
@@ -6,7 +6,7 @@ internal static class Program
     {
         static void Main(string[] args)
         {
-            WordEmbeddingTransform.ExtractEmbeddings();
+            ExtractPixelsExample.ExtractPixels();
         }
     }
 }
diff --git a/src/Microsoft.ML.ImageAnalytics/EntryPoints/ImageAnalytics.cs b/src/Microsoft.ML.ImageAnalytics/EntryPoints/ImageAnalytics.cs
@@ -11,51 +11,51 @@ namespace Microsoft.ML.ImageAnalytics.EntryPoints
 {
     internal static class ImageAnalytics
     {
-        [TlcModule.EntryPoint(Name = "Transforms.ImageLoader", Desc = ImageLoaderTransformer.Summary,
-            UserName = ImageLoaderTransformer.UserName, ShortName = ImageLoaderTransformer.LoaderSignature)]
-        public static CommonOutputs.TransformOutput ImageLoader(IHostEnvironment env, ImageLoaderTransformer.Arguments input)
+        [TlcModule.EntryPoint(Name = "Transforms.ImageLoader", Desc = ImageLoadingTransformer.Summary,
+            UserName = ImageLoadingTransformer.UserName, ShortName = ImageLoadingTransformer.LoaderSignature)]
+        public static CommonOutputs.TransformOutput ImageLoader(IHostEnvironment env, ImageLoadingTransformer.Options input)
         {
             var h = EntryPointUtils.CheckArgsAndCreateHost(env, "ImageLoaderTransform", input);
-            var xf = ImageLoaderTransformer.Create(h, input, input.Data);
+            var xf = ImageLoadingTransformer.Create(h, input, input.Data);
             return new CommonOutputs.TransformOutput()
             {
                 Model = new TransformModelImpl(h, xf, input.Data),
                 OutputData = xf
             };
         }
 
-        [TlcModule.EntryPoint(Name = "Transforms.ImageResizer", Desc = ImageResizerTransformer.Summary,
-            UserName = ImageResizerTransformer.UserName, ShortName = ImageResizerTransformer.LoaderSignature)]
-        public static CommonOutputs.TransformOutput ImageResizer(IHostEnvironment env, ImageResizerTransformer.Arguments input)
+        [TlcModule.EntryPoint(Name = "Transforms.ImageResizer", Desc = ImageResizingTransformer.Summary,
+            UserName = ImageResizingTransformer.UserName, ShortName = ImageResizingTransformer.LoaderSignature)]
+        public static CommonOutputs.TransformOutput ImageResizer(IHostEnvironment env, ImageResizingTransformer.Arguments input)
         {
             var h = EntryPointUtils.CheckArgsAndCreateHost(env, "ImageResizerTransform", input);
-            var xf = ImageResizerTransformer.Create(h, input, input.Data);
+            var xf = ImageResizingTransformer.Create(h, input, input.Data);
             return new CommonOutputs.TransformOutput()
             {
                 Model = new TransformModelImpl(h, xf, input.Data),
                 OutputData = xf
             };
         }
 
-        [TlcModule.EntryPoint(Name = "Transforms.ImagePixelExtractor", Desc = ImagePixelExtractorTransformer.Summary,
-            UserName = ImagePixelExtractorTransformer.UserName, ShortName = ImagePixelExtractorTransformer.LoaderSignature)]
-        public static CommonOutputs.TransformOutput ImagePixelExtractor(IHostEnvironment env, ImagePixelExtractorTransformer.Arguments input)
+        [TlcModule.EntryPoint(Name = "Transforms.ImagePixelExtractor", Desc = ImagePixelExtractingTransformer.Summary,
+            UserName = ImagePixelExtractingTransformer.UserName, ShortName = ImagePixelExtractingTransformer.LoaderSignature)]
+        public static CommonOutputs.TransformOutput ImagePixelExtractor(IHostEnvironment env, ImagePixelExtractingTransformer.Options input)
         {
             var h = EntryPointUtils.CheckArgsAndCreateHost(env, "ImagePixelExtractorTransform", input);
-            var xf = ImagePixelExtractorTransformer.Create(h, input, input.Data);
+            var xf = ImagePixelExtractingTransformer.Create(h, input, input.Data);
             return new CommonOutputs.TransformOutput()
             {
                 Model = new TransformModelImpl(h, xf, input.Data),
                 OutputData = xf
             };
         }
 
-        [TlcModule.EntryPoint(Name = "Transforms.ImageGrayscale", Desc = ImageGrayscaleTransformer.Summary,
-            UserName = ImageGrayscaleTransformer.UserName, ShortName = ImageGrayscaleTransformer.LoaderSignature)]
-        public static CommonOutputs.TransformOutput ImageGrayscale(IHostEnvironment env, ImageGrayscaleTransformer.Arguments input)
+        [TlcModule.EntryPoint(Name = "Transforms.ImageGrayscale", Desc = ImageGrayscalingTransformer.Summary,
+            UserName = ImageGrayscalingTransformer.UserName, ShortName = ImageGrayscalingTransformer.LoaderSignature)]
+        public static CommonOutputs.TransformOutput ImageGrayscale(IHostEnvironment env, ImageGrayscalingTransformer.Options input)
         {
             var h = EntryPointUtils.CheckArgsAndCreateHost(env, "ImageGrayscaleTransform", input);
-            var xf = ImageGrayscaleTransformer.Create(h, input, input.Data);
+            var xf = ImageGrayscalingTransformer.Create(h, input, input.Data);
             return new CommonOutputs.TransformOutput()
             {
                 Model = new TransformModelImpl(h, xf, input.Data),