Improve Image module docs (#25978)

Improves the docs for the Image module to mention read/write support

[Reviewed by @DanilaFe]

modules/packages/Image.chpl

@@ -17,7 +17,7 @@
  * limitations under the License.
  */
 
-/* Provides a way to write arrays of pixels to an output image format.
+/* Provides a way to read/write arrays of pixels to image formats.
 
 For example, the following code creates a 3x3 array of pixels and writes it to
 a BMP file. The array is then scaled by a factor of 2 (creating a 9x9 image)
@@ -39,6 +39,19 @@ and written to a second BMP file.
    writeImage("pixels.bmp", imageType.bmp, arr);
    writeImage("pixels2.bmp", imageType.bmp, scale(arr, 2));
 
+In another example, the following code reads a PNG file, removes all green from
+the image, and writes it back out to a new JPG file.
+
+.. code-block:: chapel
+
+   use Image;
+
+   var arr = readImage("input.png", imageType.png);
+   const fmt = (rgbColor.red, rgbColor.green, rgbColor.blue);
+   var colors = pixelToColor(arr, format=fmt);
+   [c in colors] c(1) = 0;
+   arr = colorToPixel(colors, format=fmt);
+   writeImage("output.jpg", imageType.jpg, arr);
 
 */
 @unstable("Image is unstable")

test/library/packages/Image/.gitignore

@@ -1,2 +1,4 @@
 *.bmp
 *.mp4
+*.jpg
+*.png

test/library/packages/Image/example2.catfiles

@@ -0,0 +1 @@
+output.jpg

test/library/packages/Image/example2.chpl

@@ -0,0 +1,27 @@
+use Image;
+
+// create the input image
+{
+  var colors: [1..#3, 1..#3] 3*int;
+  colors[1, ..] = [(0xFF,0,0), (0,0xFF,0), (0,0,0xFF)];
+  colors[2, ..] = [(0,0xFF,0), (0,0,0xFF), (0xFF,0,0)];
+  colors[3, ..] = [(0,0,0xFF), (0xFF,0,0), (0,0xFF,0)];
+  var pixels = colorToPixel(colors, format=(rgbColor.blue, rgbColor.green, rgbColor.red));
+  writeImage("input.png", imageType.png, pixels);
+}
+
+
+//
+// the second example from the Image module docs
+//
+var arr = readImage("input.png", imageType.png);
+const fmt = (rgbColor.red, rgbColor.green, rgbColor.blue);
+var colors = pixelToColor(arr, format=fmt);
+[c in colors] c(1) = 0;
+arr = colorToPixel(colors, format=fmt);
+writeImage("output.jpg", imageType.jpg, arr);
+
+
+// clean up file not needed
+use FileSystem;
+remove("input.png");

test/library/packages/Image/example2.cleanfiles

@@ -0,0 +1 @@
+output.jpg