diff options
Diffstat (limited to 'doc/articles/image_package.html')
| -rw-r--r-- | doc/articles/image_package.html | 312 |
1 files changed, 0 insertions, 312 deletions
diff --git a/doc/articles/image_package.html b/doc/articles/image_package.html deleted file mode 100644 index 39a93ccda..000000000 --- a/doc/articles/image_package.html +++ /dev/null @@ -1,312 +0,0 @@ -<!--{ - "Title": "The Go image package", - "Template": true -}--> - -<p> -The <a href="/pkg/image/">image</a> and -<a href="/pkg/image/color/">image/color</a> packages define a number of types: -<code>color.Color</code> and <code>color.Model</code> describe colors, -<code>image.Point</code> and <code>image.Rectangle</code> describe basic 2-D -geometry, and <code>image.Image</code> brings the two concepts together to -represent a rectangular grid of colors. A -<a href="/doc/articles/image_draw.html">separate article</a> covers image -composition with the <a href="/pkg/image/draw/">image/draw</a> package. -</p> - -<p> -<b>Colors and Color Models</b> -</p> - -<p> -<a href="/pkg/image/color/#Color">Color</a> is an interface that defines the minimal -method set of any type that can be considered a color: one that can be converted -to red, green, blue and alpha values. The conversion may be lossy, such as -converting from CMYK or YCbCr color spaces. -</p> - -{{code "/src/pkg/image/color/color.go" `/type Color interface/` `/^}/`}} - -<p> -There are three important subtleties about the return values. First, the red, -green and blue are alpha-premultiplied: a fully saturated red that is also 25% -transparent is represented by RGBA returning a 75% r. Second, the channels have -a 16-bit effective range: 100% red is represented by RGBA returning an r of -65535, not 255, so that converting from CMYK or YCbCr is not as lossy. Third, -the type returned is <code>uint32</code>, even though the maximum value is 65535, to -guarantee that multiplying two values together won't overflow. Such -multiplications occur when blending two colors according to an alpha mask from a -third color, in the style of -<a href="https://en.wikipedia.org/wiki/Alpha_compositing">Porter and Duff's</a> -classic algebra: -</p> - -<pre> -dstr, dstg, dstb, dsta := dst.RGBA() -srcr, srcg, srcb, srca := src.RGBA() -_, _, _, m := mask.RGBA() -const M = 1<<16 - 1 -// The resultant red value is a blend of dstr and srcr, and ranges in [0, M]. -// The calculation for green, blue and alpha is similar. -dstr = (dstr*(M-m) + srcr*m) / M -</pre> - -<p> -The last line of that code snippet would have been more complicated if we worked -with non-alpha-premultiplied colors, which is why <code>Color</code> uses -alpha-premultiplied values. -</p> - -<p> -The image/color package also defines a number of concrete types that implement -the <code>Color</code> interface. For example, -<a href="/pkg/image/color/#RGBA"><code>RGBA</code></a> is a struct that represents -the classic "8 bits per channel" color. -</p> - -{{code "/src/pkg/image/color/color.go" `/type RGBA struct/` `/^}/`}} - -<p> -Note that the <code>R</code> field of an <code>RGBA</code> is an 8-bit -alpha-premultiplied color in the range [0, 255]. <code>RGBA</code> satisfies the -<code>Color</code> interface by multiplying that value by 0x101 to generate a -16-bit alpha-premultiplied color in the range [0, 65535]. Similarly, the -<a href="/pkg/image/color/#NRGBA"><code>NRGBA</code></a> struct type represents -an 8-bit non-alpha-premultiplied color, as used by the PNG image format. When -manipulating an <code>NRGBA</code>'s fields directly, the values are -non-alpha-premultiplied, but when calling the <code>RGBA</code> method, the -return values are alpha-premultiplied. -</p> - -<p> -A <a href="/pkg/image/color/#Model"><code>Model</code></a> is simply -something that can convert <code>Color</code>s to other <code>Color</code>s, possibly lossily. For -example, the <code>GrayModel</code> can convert any <code>Color</code> to a -desaturated <a href="/pkg/image/color/#Gray"><code>Gray</code></a>. A -<code>Palette</code> can convert any <code>Color</code> to one from a -limited palette. -</p> - -{{code "/src/pkg/image/color/color.go" `/type Model interface/` `/^}/`}} - -{{code "/src/pkg/image/color/color.go" `/type Palette \[\]Color/`}} - -<p> -<b>Points and Rectangles</b> -</p> - -<p> -A <a href="/pkg/image/#Point"><code>Point</code></a> is an (x, y) co-ordinate -on the integer grid, with axes increasing right and down. It is neither a pixel -nor a grid square. A <code>Point</code> has no intrinsic width, height or -color, but the visualizations below use a small colored square. -</p> - -{{code "/src/pkg/image/geom.go" `/type Point struct/` `/^}/`}} - -<p> -<img src="image-package-01.png" width="400" height="300"> -</p> - -{{code "/doc/progs/image_package1.go" `/p := image.Point/`}} - -<p> -A <a href="/pkg/image/#Rectangle"><code>Rectangle</code></a> is an axis-aligned -rectangle on the integer grid, defined by its top-left and bottom-right -<code>Point</code>. A <code>Rectangle</code> also has no intrinsic color, but -the visualizations below outline rectangles with a thin colored line, and call -out their <code>Min</code> and <code>Max</code> <code>Point</code>s. -</p> - -{{code "/src/pkg/image/geom.go" `/type Rectangle struct/` `/^}/`}} - -<p> -For convenience, <code>image.Rect(x0, y0, x1, y1)</code> is equivalent to -<code>image.Rectangle{image.Point{x0, y0}, image.Point{x1, y1}}</code>, but is -much easier to type. -</p> - -<p> -A <code>Rectangle</code> is inclusive at the top-left and exclusive at the -bottom-right. For a <code>Point p</code> and a <code>Rectangle r</code>, -<code>p.In(r)</code> if and only if -<code>r.Min.X <= p.X && p.X < r.Max.X</code>, and similarly for <code>Y</code>. This is analogous to how -a slice <code>s[i0:i1]</code> is inclusive at the low end and exclusive at the -high end. (Unlike arrays and slices, a <code>Rectangle</code> often has a -non-zero origin.) -</p> - -<p> -<img src="image-package-02.png" width="400" height="300"> -</p> - -{{code "/doc/progs/image_package2.go" `/r := image.Rect/` `/fmt.Println/`}} - -<p> -Adding a <code>Point</code> to a <code>Rectangle</code> translates the -<code>Rectangle</code>. Points and Rectangles are not restricted to be in the -bottom-right quadrant. -</p> - -<p> -<img src="image-package-03.png" width="400" height="300"> -</p> - -{{code "/doc/progs/image_package3.go" `/r := image.Rect/` `/fmt.Println/`}} - -<p> -Intersecting two Rectangles yields another Rectangle, which may be empty. -</p> - -<p> -<img src="image-package-04.png" width="400" height="300"> -</p> - -{{code "/doc/progs/image_package4.go" `/r := image.Rect/` `/fmt.Printf/`}} - -<p> -Points and Rectangles are passed and returned by value. A function that takes a -<code>Rectangle</code> argument will be as efficient as a function that takes -two <code>Point</code> arguments, or four <code>int</code> arguments. -</p> - -<p> -<b>Images</b> -</p> - -<p> -An <a href="/pkg/image/#Image">Image</a> maps every grid square in a -<code>Rectangle</code> to a <code>Color</code> from a <code>Model</code>. -"The pixel at (x, y)" refers to the color of the grid square defined by the -points (x, y), (x+1, y), (x+1, y+1) and (x, y+1). -</p> - -{{code "/src/pkg/image/image.go" `/type Image interface/` `/^}/`}} - -<p> -A common mistake is assuming that an <code>Image</code>'s bounds start at (0, -0). For example, an animated GIF contains a sequence of Images, and each -<code>Image</code> after the first typically only holds pixel data for the area -that changed, and that area doesn't necessarily start at (0, 0). The correct -way to iterate over an <code>Image</code> m's pixels looks like: -</p> - -<pre> -b := m.Bounds() -for y := b.Min.Y; y < b.Max.Y; y++ { - for x := b.Min.X; x < b.Max.X; x++ { - doStuffWith(m.At(x, y)) - } -} -</pre> - -<p> -<code>Image</code> implementations do not have to be based on an in-memory -slice of pixel data. For example, a -<a href="/pkg/image/#Uniform"><code>Uniform</code></a> is an -<code>Image</code> of enormous bounds and uniform color, whose in-memory -representation is simply that color. -</p> - -{{code "/src/pkg/image/names.go" `/type Uniform struct/` `/^}/`}} - -<p> -Typically, though, programs will want an image based on a slice. Struct types -like <a href="/pkg/image/#RGBA"><code>RGBA</code></a> and -<a href="/pkg/image/#Gray"><code>Gray</code></a> (which other packages refer -to as <code>image.RGBA</code> and <code>image.Gray</code>) hold slices of pixel -data and implement the <code>Image</code> interface. -</p> - -{{code "/src/pkg/image/image.go" `/type RGBA struct/` `/^}/`}} - -<p> -These types also provide a <code>Set(x, y int, c color.Color)</code> method -that allows modifying the image one pixel at a time. -</p> - -{{code "/doc/progs/image_package5.go" `/m := image.New/` `/m.Set/`}} - -<p> -If you're reading or writing a lot of pixel data, it can be more efficient, but -more complicated, to access these struct type's <code>Pix</code> field directly. -</p> - -<p> -The slice-based <code>Image</code> implementations also provide a -<code>SubImage</code> method, which returns an <code>Image</code> backed by the -same array. Modifying the pixels of a sub-image will affect the pixels of the -original image, analogous to how modifying the contents of a sub-slice -<code>s[i0:i1]</code> will affect the contents of the original slice -<code>s</code>. -</p> - -<img src="image-package-05.png" width="400" height="300"> - -{{code "/doc/progs/image_package6.go" `/m0 := image.New/` `/fmt.Println\(m0.Stride/`}} - -<p> -For low-level code that works on an image's <code>Pix</code> field, be aware -that ranging over <code>Pix</code> can affect pixels outside an image's bounds. -In the example above, the pixels covered by <code>m1.Pix</code> are shaded in -blue. Higher-level code, such as the <code>At</code> and <code>Set</code> -methods or the <a href="/pkg/image/draw/">image/draw package</a>, will clip -their operations to the image's bounds. -</p> - -<p> -<b>Image Formats</b> -</p> - -<p> -The standard package library supports a number of common image formats, such as -GIF, JPEG and PNG. If you know the format of a source image file, you can -decode from an <a href="/pkg/io/#Reader"><code>io.Reader</code></a> directly. -</p> - -<pre> -import ( - "image/jpeg" - "image/png" - "io" -) - -// convertJPEGToPNG converts from JPEG to PNG. -func convertJPEGToPNG(w io.Writer, r io.Reader) error { - img, err := jpeg.Decode(r) - if err != nil { - return err - } - return png.Encode(w, img) -} -</pre> - -<p> -If you have image data of unknown format, the -<a href="/pkg/image/#Decode"><code>image.Decode</code></a> function can detect -the format. The set of recognized formats is constructed at run time and is not -limited to those in the standard package library. An image format package -typically registers its format in an init function, and the main package will -"underscore import" such a package solely for the side effect of format -registration. -</p> - -<pre> -import ( - "image" - "image/png" - "io" - - _ "code.google.com/p/vp8-go/webp" - _ "image/jpeg" -) - -// convertToPNG converts from any recognized format to PNG. -func convertToPNG(w io.Writer, r io.Reader) error { - img, _, err := image.Decode(r) - if err != nil { - return err - } - return png.Encode(w, img) -} -</pre> |