画像変換パラメータリファレンスlink

ImageFluxで利用できる画像変換機能とそのパラメーターリファレンス

ImageFluxでは画像変換のパラメータをURLの先頭につけることができます。 各パラメータはキーとその値からなり、イコール(=)で結合されています。 複数のパラメータをカンマ(,)で結合することにより、複数の画像変換パラメータを指定できます。 たとえば次の画像では、画像を幅400pxに縮小し、その上に幅300pxのImageFluxのロゴをオーバーレイ合成したうえでWebPに変換して配信しています。

ImageFluxによる画像変換の例

このときのリクエストURLは次のようになります。

https://demo.imageflux.jp/w=400,l=(w=300%2fimages%2f1.png),f=webp:auto/bridge.jpg

HTML中でsrcset属性のように、カンマ区切りのリストを利用しておりURL内にカンマを含むことができない場合、パーセントエンコードした%2C(または%2c)に置き換えられます。

https://demo.imageflux.jp/w=400%2cl=(w=300%2fimages%2f1.png)%2cf=webp:auto/bridge.jpg

URLの先頭にはパラメータの前に /c もしくは /c! を付与できます。 これらのプレフィックスを用いることで、画像変換を行うURLであることを明示的に示すことができます。 プレフィックスを付与しても画像変換の結果自体に影響はありません。 つまり、次の3つのURLはどれも同じ画像変換結果になります。

https://demo.imageflux.jp/w=400/bridge.jpg
https://demo.imageflux.jp/c/w=400/bridge.jpg
https://demo.imageflux.jp/c!/w=400/bridge.jpg

拡大・縮小link

拡大・縮小に関するパラメータ
Key Value Type Default Description
w integer (なし) スケーリング後の幅を指定する(ピクセル単位)
h integer (なし) スケーリング後の高さを指定する(ピクセル単位)
a integer 1 出力画像のアスペクトモードを設定する
  • 0: 入力のアスペクト比に合わせ、出力の幅、高さにおさめる(scale)
  • 1: 入力のアスペクト比を無視し、出力の幅、高さに合わせる(force-scale)
  • 2: 出力を満たすように入力を拡大・縮小し、はみだした領域を切り取る(crop)
  • 3: 入力のアスペクト比に合わせ、埋まらない部分を背景色で埋める(pad)
b string ffffff 背景色を指定する(16進数)
  • 6桁で指定: 24ビットRGB値 (RRGGBB)
  • 8桁で指定: 32ビットRGBA値 (RRGGBBAA)
g integer 5 領域の原点を指定する
  • 1: 左上
  • 2: 上
  • 3: 右上
  • 4: 左
  • 5: 中央
  • 6: 右
  • 7: 左下
  • 8: 下
  • 9: 右下
u boolean 1 出力画像が入力画像より拡大されることを許可する
  • 0: 許可しない
  • 1: 許可する

出力サイズの指定link

出力画像の大きさは横幅をw、縦幅をhパラメータで指定します。 横幅、縦幅のどちらかのみを指定した場合、オリジナルの縦横比を維持して指定された横幅または縦幅に拡大・縮小します。

アスペクトモードの指定link

wとhの両方を指定した場合に画像をどう処理するかはaパラメータで設定します。 aパラメータには4つのモードがあります。 たとえばa=2を指定した場合はw、hパラメータで指定した領域を満たすように画像を拡大・縮小し、はみだした部分を切り取って出力します。

拡大・縮小の各モードによる出力結果

背景色の指定link

a=3を指定した場合、入力画像で埋まらなかった出力領域を指定された背景色で塗り足します。 このときの背景色はbパラメータで指定できます。

bパラメータには6桁の16進数で24ビットRGB値を指定します。また8桁の指定を行うことで、32ビットRGBA値を指定できます。

原点の指定link

a=2とa=3を指定した場合、gパラメータを用いることで原点を指定できます。 この原点は入力画像と出力領域の位置を合わせる基準点として使われます。

gパラメータは左上を基準に1(左上)から9(右下)の整数で指定します。 デフォルトは5(中央)です。

原点による領域の違い

入力画像の拡大を制限link

ファイルサイズの増加や拡大による画質の劣化を抑えるために、出力画像のサイズを入力画像のサイズに制限したいことがあります。 uパラメータを用いることで、入力画像のサイズよりも大きな画像を出力しないように制限できます。 これはブラウザやクライアントアプリケーションが自動的に拡大して表示してくれる場合に有効な機能です。

クリッピングlink

クリッピングに関するパラメータ一
Key Value Type Default Description
ic integer:integer:integer:integer (なし) 入力画像を指定したサイズに切り抜く(x1:y1:x2:y2)
icr float:float:float:float 0:0:1:1 入力画像を指定したサイズに切り抜く (割合で指定)
例: 0.25:0.25:0.75:0.75=25%:25%:75%:75%
icと同時に使用できません
ig integer gの値 入力画像を切り抜く領域の原点を指定する
  • 1: 左上
  • 2: 上
  • 3: 右上
  • 4: 左
  • 5: 中央
  • 6: 右
  • 7: 左下
  • 8: 下
  • 9: 右下
oc / c integer:integer:integer:integer (なし) 拡大・縮小後の出力画像を切り抜く (x1:y1:x2:y2)
ocr / cr float:float:float:float 0:0:1:1 拡大・縮小後の出力画像を切り抜く (割合で指定)
例: 0.25:0.25:0.75:0.75=25%:25%:75%:75%
ocと同時に使用できません
og integer gの値 拡大・縮小後の出力画像を切り抜く領域の原点を指定する
  • 1: 左上
  • 2: 上
  • 3: 右上
  • 4: 左
  • 5: 中央
  • 6: 右
  • 7: 左下
  • 8: 下
  • 9: 右下

ic、oc パラメータは画像の指定された領域を切り抜きます。 icパラメータは拡大・縮小を行う前の入力画像を、oc(またはc)パラメータは拡大・縮小を行った後の出力画像を切り抜きます。

領域の原点はig、ogパラメータで指定します。たとえば0:0:150:100と指定した場合、ig、ogパラメータによって切り抜かれる位置は次のようになります。 ig、ogパラメータを指定しなかった場合はgパラメータで指定した値が利用されます。

原点による切り抜かれる領域の違い

切り抜く領域はピクセル単位で指定するほか、icr、ocr(またはcr)パラメータを用いることで、画像サイズに対する割合で指定できます。 ピクセル指定(ic、oc)と割合指定(icr、ocr)は同時に指定できません。 入力画像のクリッピングと拡大・縮小後のクリッピングで別々の指定を行うこと(たとえばicとocrの組み合わせ)は問題ありません。

回転・反転link

画像の回転・反転に関するパラメーター
Key Value Type Default Description
ir integer 1 入力画像を回転・反転させる
  • 1: 回転・反転させない (top-left)
  • 2: 1を左右反転 (top-right)
  • 3: 1を180度回転、2を上下反転 (bottom-right)
  • 4: 1を上下反転、2を180度回転 (bottom-left)
  • 5: 2を反時計回りに90度回転 (left-top)
  • 6: 1を反時計回りに90度回転 (right-top)
  • 7: 2を時計回りに90度回転 (right-bottom)
  • 8: 1を時計回りに90度回転 (left-bottom)
  • auto: ExifのOrientation情報があれば、それを反映(逆変換)
or / r integer 1 拡大・縮小後の画像を回転・反転させる
  • 1: 回転・反転させない (top-left)
  • 2: 1を左右反転 (top-right)
  • 3: 1を180度回転、2を上下反転 (bottom-right)
  • 4: 1を上下反転、2を180度回転 (bottom-left)
  • 5: 2を反時計回りに90度回転 (left-top)
  • 6: 1を反時計回りに90度回転 (right-top)
  • 7: 2を時計回りに90度回転 (right-bottom)
  • 8: 1を時計回りに90度回転 (left-bottom)
  • auto: ExifのOrientation情報があれば、それを反映(逆変換)

JPEG画像の自動回転link

デジタルカメラやスマートフォンが出力したExif規格 (PDF)のJPEGにはオリエンテーション情報(画像方向情報)が含まれていることがあります。 ir=auto(またはor=auto)と指定すると、画像のオリエンテーション情報を用いて逆変換を行い、オリエンテーション情報が反映された(オリエンテーション情報を含まない)画像を出力します。

パラメータによる回転・反転link

値を指定して回転・反転する場合は、ir、or(またはr)パラメータにどの端点を基準点として画像を回転・反転させるかを1から8で指定します。 ir、orパラメータに指定する値はExifが用いているTIFF Tag Orientationの値の逆変換になっています。 例としてImageFluxのロゴ画像をそれぞれの値で回転・反転させると次のようになります。

1 (top-left) 2 (top-right) 3 (bottom-right) 4 (bottom-left)
5 (left-top) 6 (right-top) 7 (right-bottom) 8 (left-bottom)

irとorは同時に指定可能ですが、一部、意味のない組み合わせが存在します。具体的には、一方の指定がautoのない場合、autoの指定は無視されます。

フィルタlink

フィルタのパラメータ一覧
Name Value Type Default Description
unsharp integerxfloat
integerxfloat+float+float 		(なし) 拡大縮小後の画像に対してアンシャープマスクを適用する
blur integerxfloat (なし) 拡大縮小後の画像に対してガウシアンぼかしを適用する
grayscale integer 0 指定された割合(%)に応じて、彩度を落としてグレースケール化する
0で無変換、100で完全なグレースケールとなる
sepia integer 0 指定された割合(%)に応じて、彩度を落とした上でセピア風に変換する
0で無変換、100で完全なセピア風となる
brightness integer 100 画像の明度を指定された比(%)で変更する
0で完全な黒、100で無変換となる。100より大きい値を指定すると元画像より明るくなる
contrast integer 100 画像のコントラストを指定された比(%)で変更する
0で完全なグレー、100で無変換となる。100より大きい値を指定すると元画像よりコントラストが強調される
invert integer 0 1を指定した場合、画像をネガポジ反転する

アンシャープマスクlink

アンシャープマスクフィルタはシャープネス処理を行うフィルタのひとつで、エッジを強調しメリハリが付いた画像にします。 アンシャープマスクフィルタはunsharpパラメータを用いて次の書式で指定します。 この書式はImageMagickの-unsharpオプションと互換性があります。 gain、thresholdは省略可能です。

unsharp=radiusxsigma+gain+threshold
アンシャープマスクの指定
Name Value Type Default Description
radius integer 必須 ガウシアンぼかし半径(ピクセル単位)。0より大きい値
sigma float 必須 ガウシアンぼかしの標準偏差。0.0より大きい値
gain float 1.0 強調時の係数。thresholdを省略した場合のみ省略可
threshold float 0.05 強調時の閾値(比)。0.0より大きく1.0より小さい値
アンシャープマスクフィルタの適用例 (unsharp=3x3.0+1.0+0.0)

ブラーlink

ブラーフィルタは出力画像に対してガウシアンぼかしを適用することで、出力画像をぼかします。

ブラーの指定
Name Value Type Default Description
radius integer 必須 ガウシアンぼかし半径(ピクセル単位)。0より大きい値
sigma float 必須 ガウシアンぼかしの標準偏差。0.0より大きい値
ブラーフィルタの適用例 (blur=3x3.0)

グレースケール化link

グレースケール化フィルタは出力画像に対して指定された割合で彩度を落とし、出力画像をグレースケール化します。 0の場合は無変換、100の場合に完全なグレースケール画像となります。その間の値を指定した場合、その値に応じた比率で彩度を落とします。

グレースケール化フィルタの適用例 (grayscale=100)

セピア風link

セピア風フィルタは出力画像に対して指定された割合で彩度を落としたうえでセピア色を重ね、出力画像をセピア風画像にします。 0の場合は無変換、100の場合に完全なセピア風画像となります。その間の値を指定した場合、その値に応じた比率で彩度を落としてセピア色を重ねます。

セピア風フィルタの適用例 (sepia=100)

ブライトネスlink

ブライトネスフィルタは出力画像に対して指定された割合で明度を変更します。 0の場合は完全な黒、100の場合は元と同じ明度の画像を出力します。100未満の値を指定した場合はその値に応じて暗い画像となり、100より大きい値を指定した場合は明るい画像となります。

ブライトネスフィルタの適用例 (brightness=200)

コントラストlink

コントラストフィルタは出力画像に対して指定された割合でコントラストを変更します。 0の場合は完全なグレー、100の場合は元と同じコントラストの画像を出力します。100未満の値を指定した場合はその値に応じてコントラストの弱い画像となり、100より大きい値を指定した場合はコントラストを強調します。

コントラストフィルタの適用例 (contrast=200)

ネガポジ反転link

ネガポジ反転フィルタは出力画像に対して輝度・色を反転します。

0の場合は無変換、1の場合は反転した画像を出力します。

ネガポジ反転フィルタの適用例 (invert=1)

フィルタの適用順序link

アンシャープマスクフィルタとブラーフィルタは同時には適用できませんが、そのほかのフィルタは任意に複数組み合わせることが可能です。 その場合、以下の順序でフィルタが適用されます。

  1. アンシャープマスクまたはブラー
  2. グレースケール化
  3. セピア風
  4. ブライトネス
  5. コントラスト
  6. ネガポジ反転

オーバーレイ合成link

オーバーレイ合成に関するパラメーター
Key Value Type Default Description
l (string) 合成する画像とその変換パラメーターを指定する
値はURLエンコードされている必要がある

オーバーレイ画像の指定link

オーバーレイ画像はlパラメータを用いて指定します。lパラメータには先頭に画像変換パラメータを指定できます。 値はすべてURLエンコードされており、かつ()でくくる必要があります。 たとえば、横幅300pxに縮小した画像をオーバーレイ合成する場合は次のようになります。

https://demo.imageflux.jp/w=400,l=(w=300%2fimages%2f1.png)/bridge.jpg
オーバーレイ合成の例

オーバーレイする画像には各種画像変換パラメータを指定できます。また、オーバーレイする位置を指定するために、以下のパラメータを利用できます。 fパラメータやthroughパラメータといった入力や出力フォーマットに関したパラメータはオーバーレイ画像に対して指定できません。

オーバーレイ画像の変換パラメーター
Key Value Type Default Description
x integer 0 横方向のオフセットを指定する
xr float 0.0 横方向のオフセットを指定する(画像幅に対する割合)
y integer 0 縦方向のオフセットを指定する
yr float 0.0 縦方向のオフセットを指定する(画像高さに対する割合)
lg integer 5 原点を指定する
  • 1: 左上
  • 2: 上
  • 3: 右上
  • 4: 左
  • 5: 中央
  • 6: 右
  • 7: 左下
  • 8: 下
  • 9: 右下
mask string
string:integer 		なし 指定された画像をマスクとしてクリッピングマスク処理を行う

クリッピングマスクlink

maskパラメータを指定することで、lパラメータに指定された画像をマスクとしてクリッピングマスク処理を行うことができます。 maskパラメータは次のように指定します。

mask=type
mask=type:padding

クリッピングマスクの種類(type)にはwhite、black、そしてalphaがあります。 whiteは画像中の白い領域、blackは黒い領域をマスクとして扱います。つまり、マスクとなる画像の輝度情報をアルファ値として扱います。 指定画像がグレースケールではなくカラー画像だった場合は、グレースケールに変換してから処理します。

alphaを指定した場合、マスク画像のアルファチャンネルをマスクとして用います。 ただし、指定された画像がアルファチャンネルを含んでいなかった場合、whiteが指定されていると見なし、輝度情報をマスクとして用います。

padding modeは指定された画像の領域からはみ出た部分をどのように処理するかを指定します。 デフォルトは0で、マスクとして指定された画像からはみ出た部分はマスク外とみなし、すべて透明にして出力します。

マスクパラメータの指定
Name Value Type Default Description
mask type string 必須 マスクとして扱う領域を指定する
  • white: 白(輝度情報をアルファ値として用いる)
  • black: 黒
  • alpha: 指定画像のアルファ値を用いて切り抜く
padding mode integer 0 指定画像が入力画像より小さい場合の処理を指定する
  • 0: 指定画像からはみ出た部分を透明にする
  • 1: 指定画像からはみ出た部分をそのまま残す

画像位置の指定 (古い形式)link

以下のパラメーターは互換性のために維持されています。
オーバーレイ画像の変換パラメーター(古い形式)
Key Value Type Default Description
l string (なし) 重ねる画像のファイルパス(URLエンコード形式)
lx integer 0 横方向のオフセットを指定する
lxr integer 0 横方向のオフセットを指定する(画像幅に対する割合)
ly integer 0 縦方向のオフセットを指定する
lyr integer 0 縦方向のオフセットを指定する(画像高さに対する割合)
lg integer 5 原点を指定する
  • 1: 左上
  • 2: 上
  • 3: 右上
  • 4: 左
  • 5: 中央
  • 6: 右
  • 7: 左下
  • 8: 下
  • 9: 右下

出力link

出力フォーマットに関するパラメーター
Key Value Type Default Description
f string auto 出力する画像フォーマットを指定する
  • auto: 入力画像と同じフォーマット
  • jpg: JPEG
  • png: PNG
  • gif: GIF
  • webp: WebP
  • webp:auto: WebP(クライアントが対応していない場合入力画像と同じフォーマット)
  • webp:jpg: WebP(クライアントが対応していない場合JPEG)
  • webp:png: WebP(クライアントが対応していない場合PNG)
  • webp:gif: WebP(クライアントが対応していない場合GIF)
q integer 75 クォリティパラメータ(0..100)
出力フォーマットがJPEGまたはWebPの場合に適用される。数値が大きい方が高画質となる。
0の場合はデフォルト値として扱われる
o boolean 1 出力フォーマットがJPEGの場合に、出力画像のハフマン符号化テーブルの最適化を行う
  • 0: 最適化を行わない
  • 1: 最適化を行う
lossless boolean 0 出力フォーマットがWebPの場合に、ロスレス形式で出力する
  • 0: ロスレス形式で出力しない
  • 1: ロスレス形式で出力する
s integer 1 入出力フォーマットが共にJPEGの場合、Exif情報をどう取り扱うかを指定する
  • 1: Exif情報を削除する
  • 2: Exif情報のうち、Orientation以外を削除する
    ただし、ir・or等の回転指定と併用した場合は、このパラメータの指定に関わらずOrientationも含めてExif情報が削除される

対応フォーマットの判別は、クライアントからのAcceptヘッダフィールドの値を用いて判定します。 そのためAcceptヘッダが正しく送られない場合や、レスポンスに含まれるVaryヘッダフィールドを扱えないキャッシュでは正しく動作しません。

背景色の指定link

アルファチャンネルをサポートしていない画像フォーマットに変換する場合、bパラメータで指定された背景色と合成して出力します。

画像フォーマットによる除外link

画像フォーマットによる除外に関するパラメーター
Key Value Type Default Description
through string (なし) 入力画像が指定されたフォーマットだった場合は一切の変換を行わない
jpg/png/gifのいずれか、またはこれらのうち複数を:区切りで並べる
例: png:gif

throughパラメータは特定の画像フォーマットで画像変換を無効にするとき使用します。 具体的にはthrough=gifと指定することで、GIF形式の画像変換を無効にし、アニメーションGIFをそのまま配信できます。