画像処理

画像のリサイズ、クロップ (切り抜き)、回転、フィルタリング、および変換を行います。

On this page

画像リソース

画像を処理するには、ページリソースまたはグローバルリソースとして画像にアクセスする必要があります。

ページリソース

ページリソースは、ページバンドル内のファイルです。ページバンドルは、 index.md または _index.md ファイルをルートとするディレクトリです。

content/
└── posts/
    └── post-1/           <-- page bundle
        ├── index.md
        └── sunset.jpg    <-- page resource

グローバルリソース

グローバルリソースとは、以下のファイルのことです。

assets ディレクトリ内、または
assets ディレクトリにマウントされた任意のディレクトリ内、または
http または https 経由でアクセス可能なリモートサーバー上にある

assets/
└── images/
    └── sunset.jpg    <-- global resource

ローカル画像にグローバルリソースとしてアクセスするには、以下のように指定します。

{{ $image := resources.Get "images/sunset.jpg" }}

リモート画像にグローバルリソースとしてアクセスするには、以下のように指定します。

{{ $image := resources.GetRemote "https://gohugo.io/img/hugo-logo.png" }}

画像レンダリング

ページリソースまたはグローバルリソースとして画像にアクセスしたら、 Permalink、RelPermalink、Width、Height プロパティを使用してテンプレートで画像をレンダリングします。

例 1: リソースが見つからない場合、エラーをスローします。

{{ $image := .Resources.GetMatch "sunset.jpg" }}
<img src="{{ $image.RelPermalink }}" width="{{ $image.Width }}" height="{{ $image.Height }}">

例 2: リソースが見つからない場合、画像のレンダリングをスキップします。

{{ $image := .Resources.GetMatch "sunset.jpg" }}
{{ with $image }}
  <img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}">
{{ end }}

例3: リソースが見つからない場合、画像のレンダリングをスキップする、より簡潔な方法。

{{ with .Resources.GetMatch "sunset.jpg" }}
  <img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}">
{{ end }}

画像処理方法

image リソースは、Resize 、Fit 、Fill 、Crop 、Filter 、Colors 、Exif メソッドを実装しています。

Resize

指定された幅および/または高さに画像のサイズを変更します。

幅と高さの両方を指定すると、元の画像の縦横比が同じでない限り、結果の画像は不均衡にスケーリング (拡大縮小) されます。

{{/* Resize to a width of 600px and preserve aspect ratio */}}
{{ $image := $image.Resize "600x" }}

{{/* Resize to a height of 400px and preserve aspect ratio */}}
{{ $image := $image.Resize "x400" }}

{{/* Resize to a width of 600px and a height of 400px */}}
{{ $image := $image.Resize "600x400" }}

Fit

アスペクト比を維持したまま、指定された寸法に合うように画像を縮小します。幅と高さの両方を指定する必要があります。

{{ $image := $image.Fit "600x400" }}

Fill

指定された寸法に合うように画像を切り抜き、サイズを変更します。幅と高さの両方を指定する必要があります。クロップボックスのアンカーポイントを変更するには、anchor オプションを使用します。

{{ $image := $image.Fill "600x400" }}

Crop

サイズを変更せずに、指定された寸法に合わせて画像をクロップ (切り抜き) します。幅と高さの両方を指定する必要があります。 anchor オプションを使用して、クロップボックスのアンカーポイントを変更します。

{{ $image := $image.Crop "600x400" }}

Filter

画像に 1 つ以上のフィルターを適用します。

{{ $image := $image.Filter (images.GaussianBlur 6) (images.Pixelate 8) }}

パイプを使用して、より機能的なスタイルで上記を記述してみましょう。 Hugo は指定された順序でフィルターを適用します。

{{ $image := $image | images.Filter (images.GaussianBlur 6) (images.Pixelate 8) }}

フィルターチェーンを一度作成し、再利用すると便利な場合があります。

{{ $filters := slice  (images.GaussianBlur 6) (images.Pixelate 8) }}
{{ $image1 := $image1.Filter $filters }}
{{ $image2 := $image2.Filter $filters }}

Colors

.Colors は，単純なヒストグラム法を用いて，画像中の主要な色を表す 16 進文字列のスライスを返します．

{{ $colors := $image.Colors }}

この方法は高速ですが、画像を縮小する場合は、縮小した画像から色を抽出するとパフォーマンスが向上します。

EXIF

画像のメタデータを含む EXIF オブジェクトを提供します。

JPEG や TIFF の画像に含まれる EXIF データにアクセスすることができます。EXIF データのない画像を処理する際のエラーを防ぐため、 with ステートメントでアクセスをラップします。

{{ with $image.Exif }}
  Date: {{ .Date }}
  Lat/Long: {{ .Lat }}/{{ .Long }}
  Tags:
  {{ range $k, $v := .Tags }}
    TAG: {{ $k }}: {{ $v }}
  {{ end }}
{{ end }}

また、EXIF フィールドに個別にアクセスし、必要に応じて lang.FormatNumber 関数を使ってフィールドをフォーマットできます。

{{ with $image.Exif }}
  <ul>
    {{ with .Date }}<li>Date: {{ .Format "January 02, 2006" }}</li>{{ end }}
    {{ with .Tags.ApertureValue }}<li>Aperture: {{ lang.FormatNumber 2 . }}</li>{{ end }}
    {{ with .Tags.BrightnessValue }}<li>Brightness: {{ lang.FormatNumber 2 . }}</li>{{ end }}
    {{ with .Tags.ExposureTime }}<li>Exposure Time: {{ . }}</li>{{ end }}
    {{ with .Tags.FNumber }}<li>F Number: {{ . }}</li>{{ end }}
    {{ with .Tags.FocalLength }}<li>Focal Length: {{ . }}</li>{{ end }}
    {{ with .Tags.ISOSpeedRatings }}<li>ISO Speed Ratings: {{ . }}</li>{{ end }}
    {{ with .Tags.LensModel }}<li>Lens Model: {{ . }}</li>{{ end }}
  </ul>
{{ end }}

EXIF 変数

.Date: 画像の作成日時です。time.Format 関数でフォーマットします。
.Lat: GPS の緯度 (度) です。
.Long: GPS の経度 (度) です。
.Tags: この画像で使用可能な EXIF タグのコレクションです。サイト設定で、このコレクションから特定のタグを含めたり除外したりできます。

画像処理オプション

Resize 、Fit 、Fill 、Crop メソッドには、スペースで区切られた、大文字と小文字を区別しないオプションのリストを指定できます。リスト内のオプションの順序は関係ありません。

寸法

Resize メソッドでは、幅、高さ、またはその両方を指定する必要があります。 Fit 、Fill 、Crop メソッドでは、幅と高さの両方を指定する必要があります。すべての寸法はピクセル単位です。

{{ $image := $image.Resize "600x" }}
{{ $image := $image.Resize "x400" }}
{{ $image := $image.Resize "600x400" }}
{{ $image := $image.Fit "600x400" }}
{{ $image := $image.Fill "600x400" }}
{{ $image := $image.Crop "600x400" }}

回転

指定された角度だけ反時計回りに画像を回転させます。 Hugo は、スケーリング (拡大縮小) の前に 回転を実行します。たとえば、元の画像が 600x400 で、画像を 50% 拡大しながら反時計回りに 90 度回転させたい場合は、以下のように指定します。

{{ $image = $image.Resize "200x r90" }}

上記の例では、幅は回転後の幅を表しています。

スケーリング (拡大縮小) せずに画像を回転するには、以下のように元の画像の寸法を使用します。

{{ with .Resources.GetMatch "sunset.jpg" }}
  {{ with .Resize (printf "%dx%d r90" .Height .Width) }}
    <img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}">
  {{ end }}
{{ end }}

上記の例では、2 行目で、幅と高さを逆にして、回転後の希望の寸法を反映しています。

アンカー

Crop または Fill メソッドを使用する場合、アンカー がクロップボックスの配置を決定します。 TopLeft、Top、TopRight、Left、Center、Right、BottomLeft、Bottom、BottomRight または Smart を指定できます。

デフォルト値は Smart で、Smartcrop 画像解析によりクロップボックスの最適な配置を決定します。サイト設定でデフォルト値をオーバーライドすることができます。

たとえば、400×200 の画像で左上に鳥がいる場合、以下の指定で、鳥を含む 200×100 のサムネイルを作成することができます。

{{ $image.Crop "200x100 TopLeft" }}

Crop または Fill メソッドを使用する際に回転を適用する場合、回転した画像からの相対的なアンカーを指定します。

ターゲットフォーマット

デフォルトでは、Hugo は画像をソース形式でエンコードします。 bmp、gif、jpeg、jpg、png、tif または webp を指定すると、画像を別の形式に変換できます。

{{ $image.Resize "600x webp" }}

スケーリング (拡大縮小) せずに画像を変換するには、以下のように、元の画像の寸法を使用します。

{{ with .Resources.GetMatch "sunset.jpg" }}
  {{ with .Resize (printf "%dx%d webp" .Width .Height) }}
    <img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}">
  {{ end }}
{{ end }}

品質

JPEG と WebP 画像に適用され、q 値は変換された画像の品質を決定します。値を大きくすると画像の品質が向上し、値を小さくするとファイルが小さくなります。この値を 1 から 100 までの整数に設定します。

デフォルト値は 75 です。サイト設定でデフォルト値をオーバーライドできます。

{{ $image.Resize "600x webp q50" }}

ヒント

WebP 画像に適用できるこのオプションは、定義済みのエンコードパラメータのセットに対応します。

値	例
`drawing`	コントラストの高いディテールの手描きまたは線画
`icon`	小さなカラフルな画像
`photo`	自然光を取り入れた屋外撮影
`picture`	ポートレートなどの室内写真
`text`	テキストを主体とした画像

デフォルト値は photo です。サイト設定でデフォルト値をオーバーライドできます。

{{ $image.Resize "600x webp picture" }}

背景色

透明度をサポートする形式 (PNG など) から透明度をサポート しない 形式 (JPEG など) に画像を変換する場合、結果の画像の背景色を指定できます。

3桁または 6桁の 16進数のカラーコード (たとえば、#00f、#0000ff) を使用します。

デフォルト値は #ffffff (白) です。サイト設定でデフォルト値をオーバーライドできます。

{{ $image.Resize "600x jpg #b31280" }}

リサンプリングフィルター

画像のサイズ変更時に使用するリサンプリングフィルターを指定できます。一般的に使用されるリサンプリングフィルターには、以下のものがあります。

フィルター	説明
`Box`	ダウンスケーリングに適したシンプルで高速な平均化フィルター
`Lanczos`	写真画像をシャープに再現する高画質リサンプリングフィルター
`CatmullRom`	同様の結果を提供しながら、Lanczos フィルターより高速なシャープキュービックフィルター
`MitchellNetravali`	CatmullRom よりもリンギングアーティファクトが少なく、よりスムーズな結果を生成するキュービックフィルター
`Linear`	バイリニアリサンプリングフィルター、キュービックフィルターよりも高速で滑らかな出力を生成します
`NearestNeighbor`	最速のリサンプリングフィルターで、アンチエイリアシングなし

デフォルト値は Box です。サイト設定でデフォルト値をオーバーライドできます。

{{ $image.Resize "600x400 Lanczos" }}

リサンプリングフィルターの完全なリストは、github.com/disintegration/imaging を参照してください。パフォーマンスを犠牲にしてでも画質を向上させたい場合は、代替フィルターを試してみてください。

画像処理の例

以下の例で使用されている夕日の写真は、著作権 Bjørn Erik Pedersen (クリエイティブコモンズ表示-継承 4.0 国際ライセンス - CC BY-SA 4.0) です。

以下は、上記の例を生成するために使用されるショートコードです。

layouts/shortcodes/imgproc.html

{{ $img := .Page.Resources.GetMatch (printf "*%s*" (.Get 0)) }}
{{ $command := .Get 1 }}
{{ $options := .Get 2 }}
{{ if eq $command "Fit"}}
  {{ $img = $img.Fit $options }}
{{ else if eq $command "Resize"}}
  {{ $img = $img.Resize $options }}
{{ else if eq $command "Fill"}}
  {{ $img = $img.Fill $options }}
{{ else if eq $command "Crop"}}
  {{ $img = $img.Crop $options }}
{{ else }}
  {{ errorf "Invalid image processing command: Must be one of Crop, Fit, Fill or Resize."}}
{{ end }}
<figure style="padding: 0.25rem; margin: 2rem 0; background-color: #cccc">
  <img style="max-width: 100%; width: auto; height: auto;" src="{{ $img.RelPermalink }}" width="{{ $img.Width }}" height="{{ $img.Height }}">
  <figcaption>
  <small>
    {{ with .Inner }}
      {{ . }}
    {{ else }}
      .{{ $command }} "{{ $options }}"
    {{ end }}
  </small>
  </figcaption>
</figure>

以下のように、Markdown からショートコードを呼び出します。

{{< imgproc sunset Resize "300x" />}}

画像設定

処理オプション

デフォルトの画像処理オプションを設定するには、サイト設定で imaging セクションを定義します。

imaging:
  anchor: Smart
  bgColor: '#ffffff'
  hint: photo
  quality: 75
  resampleFilter: Box

[imaging]
  anchor = 'Smart'
  bgColor = '#ffffff'
  hint = 'photo'
  quality = 75
  resampleFilter = 'Box'

{
   "imaging": {
      "anchor": "Smart",
      "bgColor": "#ffffff",
      "hint": "photo",
      "quality": 75,
      "resampleFilter": "Box"
   }
}

anchor: 画像処理オプションのアンカーを参照してください
bgColor: 画像処理オプションの背景色を参照してください
hint: 画像処理オプションのヒントを参照してください
quality: 画像処理オプションの品質を参照してください
resampleFilter: 画像処理オプションのリサンプリングフィルターを参照してください

EXIF データ

サイト設定に imaging.exif セクションを定義して、EXIF データの利用可能性を制御します。

imaging:
  exif:
    disableDate: false
    disableLatLong: false
    excludeFields: ""
    includeFields: ""

[imaging]
  [imaging.exif]
    disableDate = false
    disableLatLong = false
    excludeFields = ''
    includeFields = ''

{
   "imaging": {
      "exif": {
         "disableDate": false,
         "disableLatLong": false,
         "excludeFields": "",
         "includeFields": ""
      }
   }
}

disableDate: Hugo は画像の作成日時を .Date に抽出します。無効にするには、これを true に設定します。デフォルトは false です。
disableLatLong: Hugo は GPS の緯度と経度を .Lat と .Long に抽出します。無効にするには、これを true に設定します。デフォルトは false です。
excludeFields: .Tags コレクションから除外する EXIF タグに一致する正規表現です。デフォルトは "" です。
includeFields: .Tags コレクションに含める EXIF タグに一致する正規表現です。デフォルトは "" です。使用可能なすべてのタグを含めるには、この値を ".*" に設定します。

画像のスマートクロップ

デフォルトでは、Hugo は Crop または Fill メソッドで画像をクロップ (切り抜き) するときに Smartcrop ライブラリを使用します。アンカーポイントを手動で設定することもできますが、ほとんどの場合、 Smart オプションが適しています。

上図の夕焼け画像を使用した例:

画像処理性能に関する考慮事項

Hugo は処理した画像を resources ディレクトリにキャッシュします。このディレクトリをソース管理に含めると、CI/CD ワークフロー (GitHub Pages、GitLab Pages、Netlify など) で Hugo が画像を再生成する必要がなくなります。その結果、ビルドが高速化されます。

画像処理の方法やオプションを変更したり、画像の名前を変更したり削除したりすると、 resources ディレクトリに未使用の画像が残ります。未使用の画像を削除するには、以下のようにしてガベージコレクションを実行します。

hugo --gc