gdaladdo

オーバービュー画像を構築または再構築します.

概要

gdaladdo [--help] [--help-general]
         [-r {nearest|average|rms|gauss|bilinear|cubic|cubicspline|lanczos|average_mp|average_magphase|mode}]
         [-ro] [-clean] [-q] [-oo <NAME>=<VALUE>]... [-minsize <val>]
         [--partial-refresh-from-source-timestamp]
         [--partial-refresh-from-projwin <ulx> <uly> <lrx> <lry>]
         [--partial-refresh-from-source-extent <filename1>[,<filenameN>]...]
         <filename> [<levels>]...

説明

gdaladdo ユーティリティは,いくつかのダウンサンプリングアルゴリズムの1つを使用して,ほとんどのサポートされているファイル形式のオーバービュー画像を構築または再構築するために使用できます.

--help

このヘルプメッセージを表示して終了します

--help-general

一般的なGDALコマンドラインオプションの簡単な使用メッセージを表示して終了します.

-r {nearest|average|rms|gauss|bilinear|cubic|cubicspline|lanczos|average_magphase|mode}

リサンプリングアルゴリズムを選択します.デフォルトは nearest で,これは一般的にサブピクセルの精度が必要な場合に適していません.

GDAL 3.9以降,既存のTIFFオーバービューを更新する場合,オプション -r が指定されていない場合,オーバービューの RESAMPLING メタデータ項目に記載されている以前に使用されたメソッドが使用されます.

利用可能なメソッドは次のとおりです:

nearest は最近傍（単純サンプリング）リサンプラを適用します.

average はすべての非-NODATA寄与ピクセルの平均を計算します. GDAL 3.1以降,これは,ターゲットピクセルに完全に寄与していないソースピクセルの重みを適切に考慮した重み付き平均です.

rms はすべての非-NODATA寄与ピクセルの平均二乗平方根/二乗平均を計算します(GDAL >= 3.3)

gauss は,オーバービューを計算する前にガウスカーネルを適用します. これは,例えば鮮明なエッジや高コントラストまたはノイズの多いパターンの場合に,単純な平均よりも良い結果をもたらすことがあります. 推奨されるレベル値は2, 4, 8, ... であるべきです. これにより,3x3リサンプリングガウスカーネルが選択されます.

bilinear はバイリニア畳み込みカーネルを適用します.

cubic は立方体畳み込みカーネルを適用します.

cubicspline はB-Spline畳み込みカーネルを適用します.

lanczos はランチョス窓付きシンク畳み込みカーネルを適用します.

average_magphase は複素データを mag/phase 空間で平均化します.

mode はサンプリングされたすべての点の中で最も頻繁に現れる値を選択します.

-b <band>

オーバービューの生成のための入力バンド band を選択します. バンド番号は1から始まります. オーバービューを生成するために複数の -b スイッチを使用できます.

-ro

外部オーバービューを生成するためにデータセットを読み取り専用モードで開きます(特にGeoTIFFの場合).

-clean

すべてのオーバービューを削除します.

-oo <NAME>=<VALUE>

データセットオープンオプション（フォーマット固有）

-minsize <val>

最小のオーバービューレベルの最大幅または高さ. 明示的なレベルが指定されていない場合にのみ考慮されます. デフォルトは256です.

Added in version 2.3.

--partial-refresh-from-source-timestamp

Added in version 3.8.

このオプションは,外部オーバービューを持つVRTファイルの既存のオーバービューの部分的な更新を行います. VRTのすべてのソースの変更タイムスタンプをチェックし,VRTの外部オーバービューよりも新しいタイムスタンプのソースに対応する領域のオーバービューを再生成します. デフォルトでは,明示的なレベルが指定されていない限り,すべての既存のオーバービューレベルが更新されます.

--partial-refresh-from-projwin <ulx> <uly> <lrx> <lry>

Added in version 3.8.

このオプションは,ジオリファレンス座標で指定された関心領域で既存のオーバービューの部分的な更新を行います. <ulx> は左上隅のX値, <uly> は左上隅のY値, <lrx> は右下隅のX値, <lry> は右下隅のY値です. デフォルトでは,明示的なレベルが指定されていない限り,すべての既存のオーバービューレベルが更新されます.

--partial-refresh-from-source-extent <filename1>[,<filenameN>]...

Added in version 3.8.

このオプションは,1つまたは複数のファイル名（カンマで区切られた名前）で指定された関心領域で既存のオーバービューの部分的な更新を行います. ファイル名は,更新する関心領域を決定するためにのみ使用されることに注意してください. 参照ソースピクセルはメインデータセットのものです. デフォルトでは,明示的なレベルが指定されていない限り,すべての既存のオーバービューレベルが更新されます.

<filename>

オーバービューを構築するファイル（またはオーバービューを削除する必要があるファイル）です.

<levels>

構築する整数のオーバービューレベルのリストです. -clean オプションとは無視されます.

Added in version 2.3: オーバービューを構築するためにレベルはもはや必要ありません. この場合,適切なオーバービューの2の累乗の要素が選択され,最小のオーバービューが -minsize スイッチの値より小さくなるまで続きます.

GDAL 3.9以降,既存のオーバービューがすでにある場合,明示的なレベルが指定されていない場合,それらを更新するために対応するレベルが使用されます.

gdaladdo は,特別なデータセットメタデータである NODATA_VALUES タプルを適切に尊重します. そのため,RGB画像の場合,特定のRGB三重組だけがノーデータ値として考慮され,各バンドごとに三重組の値が独立して考慮されません.

2 のようなレベル値を選択すると,基本レイヤーの解像度の1/2(各次元で)のオーバービューレベルが計算されます. ファイルに選択されたレベルの既存のオーバービューレベルがある場合,それらのレベルが再計算されてその場で書き換えられます.

内部GeoTIFFオーバービュー(またはGeoTIFF形式の外部オーバービュー)の場合, -clean はファイルを縮小しません. 後でオーバービューレベルを持つgdaladdoの実行は,以前に削除されたオーバービューのスペースを再利用するのではなく,ファイルを拡張します. 既に計算されたオーバービューを持つファイルのリサンプリング方法を変更したい場合,既存のオーバービューをクリーンアップする必要はありません.

一部のフォーマットドライバはオーバービューを全くサポートしていません. 多くのフォーマットドライバは,実際にはTIFF形式である拡張子 .ovr を持つセカンダリファイルにオーバービューを格納します. デフォルトでは,GeoTIFFドライバは,書き込み可能な場合には,操作されたファイルにオーバービューを内部的に格納します. ただし, -ro フラグが指定されていない限り.

ほとんどのドライバは,Erdas Imagine形式を使用した代替オーバービューフォーマットもサポートしています. これをトリガーするには, USE_RRD=YES 構成オプションを使用します. これにより,ImagineやArcGISとGDALアプリケーションの両方で直接使用できる関連する .aux ファイルにオーバービューが配置されます. (例: --config USE_RRD YES)

GeoTIFF形式の外部オーバービュー

TIFF形式で作成された外部オーバービューは, COMPRESS_OVERVIEW 構成オプションを使用して圧縮できます. GeoTIFFドライバでサポートされているすべての圧縮方法がここで利用可能です. (例: --config COMPRESS_OVERVIEW DEFLATE). フォトメトリックインタープリテーションは, PHOTOMETRIC_OVERVIEW =RGB/YCBCR/... 構成オプションで設定できます. また,インターリーブは, INTERLEAVE_OVERVIEW =PIXEL/BAND 構成オプションで設定できます.

GDAL 3.6以降, COMPRESS_OVERVIEW と INTERLEAVE_OVERVIEW は, TIFFファイルの内部オーバービューを作成する際に尊重されます.

JPEG圧縮された外部および内部オーバービューの場合, JPEG品質は --config JPEG_QUALITY_OVERVIEW value で設定できます.

WEBP圧縮された外部および内部オーバービューの場合, WEBP品質レベルは --config WEBP_LEVEL_OVERVIEW value で設定できます. 設定されていない場合,デフォルトは75になります.

WEBP圧縮された外部および内部オーバービューの場合, WEBPロスレス/ロシー切り替えは --config WEBP_LOSSLESS_OVERVIEW value で設定できます. 設定されていない場合,デフォルトはNO(ロスレス)になります. GDAL 3.6.0で追加されました.

LERC圧縮された外部および内部オーバービューの場合,最大誤差しきい値は --config MAX_Z_ERROR_OVERVIEW value で設定できます. 設定されていない場合,デフォルトは0(ロスレス)になります. GDAL 3.4.1で追加されました.

DEFLATEまたはLERC_DEFLATE圧縮された外部および内部オーバービューの場合,圧縮レベルは --config ZLEVEL_OVERVIEW value で設定できます. 設定されていない場合,デフォルトは6になります. GDAL 3.4.1で追加されました.

ZSTDまたはLERC_ZSTD圧縮された外部および内部オーバービューの場合,圧縮レベルは --config ZSTD_LEVEL_OVERVIEW value で設定できます. 設定されていない場合,デフォルトは9になります. GDAL 3.4.1で追加されました.

JPEG-XL圧縮された外部および内部オーバービューの場合,以下の設定がGDAL 3.9.0以降で設定できます:

  • 圧縮がロスレスであるかどうかは --config JXL_LOSSLESS_OVERVIEW YES|NO で設定できます. デフォルトはYESです

  • 努力レベルは --config JXL_EFFORT_OVERVIEW value で設定できます. 値は1(高速)から9(高品質)の間です. デフォルトは5です

  • 損失圧縮のための距離レベルは --config JXL_DISTANCE_OVERVIEW value で設定できます. 値は: 0=数学的にロスレス, 1.0=視覚的にロスレス, 通常の範囲[0.5,3]. デフォルトは1.0です. JXL_LOSSLESS_OVERVIEW がYESの場合は無視されます

  • アルファチャンネルの損失圧縮のための距離レベルは --config JXL_ALPHA_DISTANCE_OVERVIEW value で設定できます. 値は: 0=数学的にロスレス, 1.0=視覚的にロスレス, 通常の範囲[0.5,3]. デフォルトはJXL_DISTANCE_OVERVIEWと同じ値です. JXL_LOSSLESS_OVERVIEW がYESの場合は無視されます

LZW, ZSTDまたはDEFLATE圧縮された外部オーバービューの場合,予測子値は --config PREDICTOR_OVERVIEW 1|2|3 で設定できます.

可能な限り小さなJPEG-In-TIFFオーバービューを生成するには,次のようにします:

--config COMPRESS_OVERVIEW JPEG --config PHOTOMETRIC_OVERVIEW YCBCR --config INTERLEAVE_OVERVIEW PIXEL

外部オーバービューは, BIGTIFF_OVERVIEW 構成オプションを使用してBigTIFF形式で作成できます: --config BIGTIFF_OVERVIEW {IF_NEEDED|IF_SAFER|YES|NO}.

デフォルト値はGDAL 2.3.0以降はIF_SAFERです(以前はIF_NEEDEDでした). このオプションの動作は,GeoTIFFドライバのドキュメントに記載されているBIGTIFF作成オプションとまったく同じです.

  • YES はBigTIFFを強制します.

  • NO はクラシックTIFFを強制します.

  • IF_NEEDED は,明らかに必要な場合のみBigTIFFを作成します(非圧縮であり,オーバービューが4GBを超える場合).

  • IF_SAFER は,結果のファイルが4GBを超える可能性がある場合にBigTIFFを作成します.

疎なGeoTIFFオーバービューファイル(つまり,すべてのピクセルがノーデータ値である場合に省略されるタイル,ノーデータ値がある場合,または0である場合)は, --config SPARSE_OK_OVERVIEW ON で取得できます. GDAL 3.4.1で追加されました

これらのオプションの詳細については, GTiff -- GeoTIFF File Format ドライバのドキュメントを参照してください.

Geotiffオーバービューでのブロックサイズの設定

--config GDAL_TIFF_OVR_BLOCKSIZE <size>

例: --config GDAL_TIFF_OVR_BLOCKSIZE 256

デフォルト値は128です. またはGDAL 3.1以降,タイルGeoTIFFファイルでオーバービューを作成する場合,フル解像度画像のタイルサイズです. 注意:この設定がない場合,ファイルはオーバービューブロックサイズと異なるブロックサイズでフル解像度画像を持つことがあります. (例: ブロックサイズ256のフル解像度画像,ブロックサイズ128のオーバービュー)

リサンプリング中のノーデータ/ソース有効マスクの処理

ソースピクセルの無効な値は,ソースバンドに設定されたノーデータ値メタデータ,マスクバンド,アルファバンドを通じて識別された場合,リサンプリング中に使用されません.

それがどのように考慮されるかの詳細は,リサンプリングカーネルに依存します:

  • 最近傍リサンプリングの場合,各ターゲットピクセルに対して,潜在的な寄与ソースピクセルの1つが選択されます(実装固有の方法で). その値は,有効であろうと無効であろうとそのまま使用されます.

  • バイリニア,キュービック,キュービックスプラインおよびランチョスの場合,各ターゲットピクセルに対して,マスクされた場合に無視するために寄与ソースピクセルの重みがゼロに設定されます. キュービックの場合,カーネル内の一部の重みが負であるため,有効なピクセルと無効なピクセルの交互がある場合,強いオーバーシュート/アンダーシュートにつながる可能性があります. そのため,水平または垂直方向のいずれかで,各次元のリサンプリングカーネルの半径よりも有効なソースピクセルの最大数が少ない場合,ターゲットピクセルはノーデータと見なされます.

  • その他のリサンプリング方法の場合,マスクされた場合に寄与するソースピクセルは無視されます. 有効なものだけが考慮されます. それがない場合,ターゲットピクセルはノーデータと見なされます.

マルチスレッディング

Added in version 3.2.

GDAL_NUM_THREADS 構成オプションは,オーバービュー計算に使用するスレッド数を指定するために ALL_CPUS または整数値に設定できます.

C言語API

このユーティリティの機能は,C言語で GDALBuildOverviews() で行うことができます.

例

オーバービューを作成し,レベルの自動計算を行いTIFFファイルに埋め込みます. (GDAL 2.3以降）

gdaladdo -r average abc.tif

TIFFファイルに埋め込まれたオーバービューを作成します:

gdaladdo -r average abc.tif 2 4 8 16

ERDAS .IMG ファイルから外部圧縮されたGeoTIFFオーバービューファイルを作成します:

gdaladdo -ro --config COMPRESS_OVERVIEW DEFLATE erdas.img 2 4 8 16

3バンドRGBデータセットから外部JPEG圧縮GeoTIFFオーバービューファイルを作成します(データセットが書き込み可能なGeoTIFFの場合,外部オーバービューの生成を強制するために -ro オプションを追加する必要があります):

gdaladdo --config COMPRESS_OVERVIEW JPEG --config PHOTOMETRIC_OVERVIEW YCBCR
         --config INTERLEAVE_OVERVIEW PIXEL rgb_dataset.ext 2 4 8 16

指定されたJPEGファイルのErdas Imagine形式のオーバービューを作成します:

gdaladdo --config USE_RRD YES airphoto.jpg 3 9 27 81

GeoPackage内の複数のラスタレイヤーの1つのような特定のサブデータセットのオーバービューを作成します("filename" パラメータは,ドライバプレフィックス,ファイル名,サブデータセット名のように,gdalinfoで表示されるようになります):

gdaladdo GPKG:file.gpkg:layer

.vrt.ovr 生成後に変更されたソースのVRTファイルのオーバービューを更新します:

gdalbuildvrt my.vrt tile1.tif tile2.tif                          # create VRT
gdaladdo -r cubic my.vrt                                         # initial overview generation
touch tile1.tif                                                  # simulate update of one of the source tiles
gdaladdo --partial-refresh-from-source-timestamp -r cubic my.vrt # refresh overviews

TIFFファイルのオーバービューを更新します:

gdalwarp -overwrite tile1.tif tile2.tif mosaic.tif                      # create mosaic
gdaladdo -r cubic mosaic.tif                                            # initial overview generation
touch tile1.tif                                                         # simulate update of one of the source tiles
gdalwarp tile1.tif mosaic.tif                                           # update mosaic
gdaladdo --partial-refresh-from-source-extent tile1.tif -r cubic my.vrt # refresh overviews