[インデックス 12620] ファイルの概要

このコミットは、Go言語の公式ドキュメントにimage/drawパッケージに関する新しい記事を追加し、既存のコードスニペットをGo 1の仕様に適合させるための変更を含んでいます。具体的には、doc/articles/image_draw.htmlとして新しい記事が追加され、関連する画像ファイル（image-20.pngからimage-2f.png）も追加されています。また、記事内で使用されるGoコードの例がdoc/progs/image_draw.goとして新規作成され、doc/Makefileとdoc/docs.htmlが更新され、新しい記事へのリンクが追加されています。src/pkg/image/draw/draw.goのコメントも、新しい記事のURLを指すように修正されています。

コミット

commit fef92cbbac97022c094f4ff5bfb47b12852e076b
Author: Johan Euphrosine <proppy@google.com>
Date:   Wed Mar 14 11:27:41 2012 +1100

    doc: add Go image/draw package article and convert code snippets to Go1.
    
    Originally published on The Go Programming Language Blog, September 29, 2011.
    
    http://blog.golang.org/2011/09/go-imagedraw-package.html
    
    Update #2547.
    
    R=golang-dev, adg, rsc
    CC=golang-dev
    https://golang.org/cl/5755057

GitHub上でのコミットページへのリンク

https://github.com/golang/go/commit/fef92cbbac97022c094f4ff5bfb47b12852e076b

元コミット内容

このコミットの元々の目的は、Go言語のimage/drawパッケージに関する記事を公式ドキュメントに追加すること、およびその記事内のコードスニペットをGo 1のリリースに合わせて更新することでした。この記事は元々2011年9月29日にGo公式ブログで公開されたものです。

変更の背景

Go言語は、そのシンプルさと効率性から、画像処理のような計算集約的なタスクにも適しています。imageパッケージは基本的な画像表現を提供し、image/drawパッケージは画像間の合成操作を可能にします。Go 1のリリースが近づくにつれて、既存のドキュメントやコード例が新しい言語仕様やAPIの変更に準拠していることを確認する必要がありました。

このコミットの主な背景は以下の通りです。

1. image/drawパッケージの重要性: image/drawパッケージは、Goにおける画像処理の基本的な構成要素であり、その機能と使い方を詳細に解説する公式ドキュメントが必要とされていました。
2. Go 1への移行: Go 1はGo言語の安定版としてリリースされ、APIの安定性が保証されました。これに伴い、既存のコード例やドキュメントはGo 1の仕様に適合させる必要がありました。特に、Go 1では一部のAPIが変更されたため、古いコードスニペットは更新が必要でした。
3. ドキュメントの充実: ユーザーがGo言語の画像処理機能を効果的に利用できるよう、包括的で分かりやすい解説記事を提供することが目的でした。

前提知識の解説

このコミットの変更内容を理解するためには、以下の前提知識が役立ちます。

Go言語のimageパッケージとimage/drawパッケージ

• imageパッケージ: Go言語の標準ライブラリの一部で、画像データを表現するための基本的なインターフェースと実装を提供します。image.Imageインターフェースは、任意の画像形式を抽象化し、At(x, y int) color.Colorメソッドを通じてピクセルデータにアクセスできます。また、image.RGBA、image.Gray、image.Palettedなどの具体的な画像型も提供します。
• image/drawパッケージ: imageパッケージの上に構築され、画像間の合成（描画）操作を提供します。主な機能は、ソース画像からデスティネーション画像への描画です。これは、Porter-Duff合成モデルに基づいており、Draw関数やDrawMask関数を通じて実現されます。
  • Porter-Duff合成: 1984年にThomas PorterとTom Duffによって発表された、デジタル画像の合成に関する理論モデルです。2つの画像（ソースとデスティネーション）をどのように組み合わせるかを定義する12の演算子（例: Src, Over, In, Outなど）を提案しました。image/drawパッケージでは、特にSrc（ソースをそのままコピー）とOver（ソースをデスティネーションの上に重ねる）が重要です。
  • マスク: DrawMask関数では、オプションでマスク画像を指定できます。マスクは、ソース画像のどの部分をデスティネーション画像に適用するかを制御するために使用されます。マスクのアルファ値が高いほど、ソース画像が強く適用されます。
  • draw.Imageインターフェース: image/drawパッケージで定義されるインターフェースで、Set(x, y int, c color.Color)メソッドを持ちます。これは、ピクセルデータを変更可能な画像型を表し、Draw操作のデスティネーションとして使用されます。

Go 1のリリース

Go 1は、Go言語の最初の安定版リリースであり、2012年3月28日に公開されました。Go 1の目標は、言語仕様と標準ライブラリの安定性を提供し、将来のバージョンアップでも既存のGo 1プログラムが動作し続けることを保証することでした。これにより、Go言語はより広範な採用を促進し、開発者が安心してGoでアプリケーションを構築できるようになりました。Go 1では、一部のAPIが整理・変更されたため、それ以前のコードはGo 1の仕様に合わせるための更新が必要となる場合がありました。

godocコマンドとドキュメント生成

godocはGo言語のツールチェーンの一部であり、Goのソースコードからドキュメントを生成・表示するために使用されます。godoc -urlオプションは、特定のURLパスに対応するドキュメントを生成するために使用されます。このコミットでは、Makefile内でgodoc -url /doc/$< >$@という形式で利用されており、HTMLファイルをrawhtmlファイルに変換する際に、Goのドキュメントシステムが解釈できる形式に変換しています。

技術的詳細

このコミットは、Go言語のドキュメントシステムと画像処理ライブラリの統合に関する技術的な側面を深く掘り下げています。

ドキュメント生成パイプラインの変更

doc/Makefileの変更は、Goのドキュメント生成プロセスにおける重要な側面を示しています。

--- a/doc/Makefile
+++ b/doc/Makefile
@@ -7,13 +7,14 @@ RAWHTML=\
 	articles/error_handling.rawhtml\
 	articles/slices_usage_and_internals.rawhtml\
 	articles/laws_of_reflection.rawhtml\
+\tarticles/image_draw.rawhtml\
 \teffective_go.rawhtml\
 \tgo1.rawhtml\
 
 all: $(RAWHTML)
 
 %.rawhtml: %.html
-\tgodoc -url /doc/$* >$@
+\tgodoc -url /doc/$< >$@

• RAWHTML変数の更新: 新しい記事articles/image_draw.rawhtmlがRAWHTML変数に追加されています。これは、この新しい記事がドキュメント生成プロセスの一部として処理されることを意味します。
• godocコマンドの引数変更: %.rawhtml: %.htmlルールにおいて、godoc -url /doc/$* >$@がgodoc -url /doc/$< >$@に変更されています。
  • $*は、パターンマッチングにおいて拡張子を除いたターゲット名（例: image_draw）を表します。
  • $<は、最初の前提条件（例: image_draw.html）を表します。
  • この変更は、godocがHTMLファイルを処理する際に、より正確なファイルパスを引数として受け取るようにするための修正です。これにより、godocがHTMLファイルの内容を正しく解析し、Goのドキュメントシステムに組み込むためのrawhtmlファイルを生成できるようになります。

image/drawパッケージの解説記事

doc/articles/image_draw.htmlは、image/drawパッケージの機能と使用法を詳細に解説しています。

• Porter-Duff合成モデル: 記事は、image/drawパッケージがPorter-Duff合成モデルに基づいていることを強調しています。特にOverとSrcという2つの主要な合成演算子について説明しています。
  • Over: ソース画像をデスティネーション画像の上に自然に重ねる操作。ソースの透明度に応じてデスティネーションへの影響が変化します。
  • Src: ソース画像をデスティネーション画像にそのままコピーする操作。デスティネーションの元の内容は無視されます。
• 幾何学的アライメント: DrawおよびDrawMask関数が、デスティネーション、ソース、マスクの各画像における矩形と点の関係をどのように扱うかについて説明しています。これにより、画像の特定の部分を正確に描画したり、部分的な更新を行ったりすることが可能になります。
• 一般的な画像操作の例: 記事は、image/drawパッケージを使用して実行できる一般的な画像操作のコード例を豊富に提供しています。
  • 矩形の塗りつぶし (image.Uniformを使用)
  • 画像のコピー
  • 画像のスクロール
  • 画像をRGBA形式に変換
  • 円形マスクを通じた描画
  • フォントグリフの描画
• パフォーマンスの最適化: DrawMask関数の実装が、インターフェース型を引数にとりながらも、内部で型アサーションを使用して特定の構造体型（例: image.RGBA）に特化した高速パスを実行していることを説明しています。これにより、一般的なケースでは高いパフォーマンスを維持しつつ、汎用的な操作も可能にしています。

コードスニペットのGo 1対応

doc/progs/image_draw.goは、記事内で参照されるGoコードスニペットを格納しています。これらのスニペットは、Go 1のAPIと慣習に準拠するように更新されています。

• image.ZPの使用: image.ZPはimage.Point{0, 0}のゼロ値であり、原点を表します。コードスニペットでは、このimage.ZPが適切に使用されています。
• image.Uniformの使用: 単一の色で矩形を塗りつぶす際にimage.Uniformが使用されています。これは、Goの画像処理における一般的なパターンです。
• image.Transparentの使用: 画像を透明にリセットする際にimage.Transparentが使用されています。
• image.Rectangleの操作: image.RectangleのSubやAddメソッドを使用して、矩形の座標変換やサイズ調整を行っています。
• カスタムマスクの実装: circleというカスタム型を定義し、image.Imageインターフェースとcolor.ColorModel、Bounds、Atメソッドを実装することで、円形マスクを作成する例が示されています。これは、image/drawパッケージの柔軟性を示しています。

コアとなるコードの変更箇所

このコミットにおける主要なコード変更は以下のファイルに集中しています。

1. doc/Makefile:

   • RAWHTML変数にarticles/image_draw.rawhtmlが追加されました。
   • %.rawhtml: %.htmlルールのgodocコマンドの引数が$*から$<に変更されました。

2. doc/articles/image-*.png:

   • image-20.pngからimage-2f.pngまでの複数のPNG画像ファイルが新規追加されました。これらはimage_draw.html記事内で使用される図です。

3. doc/articles/image_draw.html:

   • image/drawパッケージに関する新しい記事のHTMLファイルが新規追加されました。このファイルには、パッケージの概要、Porter-Duff合成、幾何学的アライメント、様々な画像操作の例、パフォーマンスに関する考察などが含まれています。
   • 記事内では、{{code "..." "..." "..."}}という形式のGoドキュメントシステム独自のディレクティブが使用されており、doc/progs/image_draw.goからコードスニペットを埋め込んでいます。

4. doc/docs.html:

   • Goのドキュメントのインデックスページに、新しいimage/drawパッケージの記事へのリンクが追加されました。
   • リンクのURLがブログ記事のURLから、新しいドキュメントのURL（/doc/articles/image_draw.html）に変更されました。

5. doc/progs/image_draw.go:

   • image_draw.html記事内で参照されるGoコードスニペットを含む新しいGoプログラムファイルが新規追加されました。このファイルには、image/drawパッケージの様々な使用例が関数としてまとめられています。

6. src/pkg/image/draw/draw.go:

   • image/drawパッケージのソースコード内のコメントが更新され、新しい記事のURLを指すように変更されました。

   --- a/src/pkg/image/draw/draw.go
   +++ b/src/pkg/image/draw/draw.go
   @@ -5,7 +5,7 @@
    // Package draw provides image composition functions.
    //
    // See "The Go image/draw package" for an introduction to this package:
   -// http://blog.golang.org/2011/09/go-imagedraw-package.html
   +// http://golang.org/doc/articles/image_draw.html
    package draw
   

コアとなるコードの解説

このコミットのコアとなる変更は、doc/articles/image_draw.htmlとdoc/progs/image_draw.goの新規追加、およびそれらをドキュメントシステムに統合するためのdoc/Makefileとdoc/docs.htmlの更新です。

doc/articles/image_draw.html

このHTMLファイルは、image/drawパッケージの包括的なガイドとして機能します。特に注目すべきは、Goのドキュメントシステムが提供する{{code "..." "..." "..."}}ディレクティブの使用です。これにより、外部のGoファイルから特定のコードブロックを記事内に埋め込むことができます。

例えば、矩形を単一の色で塗りつぶす例では、以下のようにdoc/progs/image_draw.goからコードが埋め込まれています。

{{code "/doc/progs/image_draw.go" `/ZERO/` `/STOP/`}}

これは、/doc/progs/image_draw.goファイル内で// ZERO OMITと// STOP OMITのコメントで囲まれたコードブロックを抽出して表示することを意味します。このメカニズムにより、ドキュメント内のコード例と実際の実行可能なコードが同期され、Go 1への移行に伴うコードの更新が容易になります。

doc/progs/image_draw.go

このGoファイルは、image_draw.html記事で参照されるすべてのコードスニペットを保持しています。各スニペットは、// OMITコメントを使用して、記事内でどの部分が抽出されるかを制御しています。

例えば、Color関数内の矩形塗りつぶしの例は以下のようになっています。

func Color() {
	c := color.RGBA{255, 0, 255, 255}
	r := image.Rect(0, 0, 640, 480)
	dst := image.NewRGBA(r)

	// ZERO OMIT
	// image.ZP is the zero point -- the origin.
	draw.Draw(dst, r, &image.Uniform{c}, image.ZP, draw.Src)
	// STOP OMIT

	// BLUE OMIT
	m := image.NewRGBA(image.Rect(0, 0, 640, 480))
	blue := color.RGBA{0, 0, 255, 255}
	draw.Draw(m, m.Bounds(), &image.Uniform{blue}, image.ZP, draw.Src)
	// STOP OMIT

	// RESET OMIT
	draw.Draw(m, m.Bounds(), image.Transparent, image.ZP, draw.Src)
	// STOP OMIT
}

これらの// OMITコメントは、godocツールがコードスニペットを抽出する際に使用するマーカーです。これにより、記事の文脈に合わせて関連するコードのみを表示し、完全なプログラムコードは別のファイルで管理するという、Goのドキュメントにおける一般的なプラクティスが実現されています。

doc/Makefileの変更

godoc -url /doc/$< >$@への変更は、godocがHTMLファイルを処理する際の入力パスの指定方法をより正確にするためのものです。$<はMakefileの自動変数で、現在のルールの最初の前提条件のファイル名を表します。この場合、%.htmlファイルがこれに該当します。これにより、godocは正しいHTMLファイルを読み込み、それをrawhtml形式に変換して、Goのドキュメントサーバーが提供できるようにします。

これらの変更は、Goのドキュメントがどのように生成され、コード例がどのように管理されているかを示す良い例です。Go 1のリリースに向けて、ドキュメントの品質と正確性を高めるための重要なステップでした。

関連リンク

• Go言語公式ブログ: http://blog.golang.org/
• Go 1リリースアナウンス: https://go.dev/blog/go1
• Go imageパッケージドキュメント: https://pkg.go.dev/image
• Go image/drawパッケージドキュメント: https://pkg.go.dev/image/draw

参考にした情報源リンク

• The Go Programming Language Blog, "The Go image/draw package" (Original article): http://blog.golang.org/2011/09/go-imagedraw-package.html
• Go image/draw package article in Go documentation: https://golang.org/doc/articles/image_draw.html (This is the URL that the commit adds/updates)
• Porter, T., & Duff, T. (1984). Compositing Digital Images. ACM SIGGRAPH Computer Graphics, 18(3), 253-259.
• Go 1 Release Notes: https://go.dev/doc/go1
• Go godoc command documentation: https://pkg.go.dev/cmd/godoc
• Makefile automatic variables: https://www.gnu.org/software/make/manual/html_node/Automatic-Variables.html