hyperdims

/usr/local/m2/setting.json 다음 영역에 대해 기술한다.

{
  "functions": {
    "contents": {
      "hyperdims": {
        ...
      }
    }
  }
}

Note

hyperdims는 DIMS 와 동일한 규격을 지원할 뿐만 아니라, 다음 오픈소스에 대한 연동모듈을 제공한다.

기타 규격에 대한 커스터마이징 지원을 제공한다.

How to use

원본 URL 뒤에 가공하고 싶은 HYPERDIMS 명령어를 추가한다.

# 원본
https://example.com/sample.jpg

# 원본 + 키워드(hdims) + 명령어/옵션
https://example.com/sample.jpg/hdims/resize/600x400

Note

만약 M2 완전장애 상황이 발생하더라도 원본이미지가 보이도록 구성하고 싶다면, 임의의 QueryString 파라미터를 통해 HYPERDIMS 명령을 제공한다.

https://example.com/sample.jpg?m2param=/hdims/resize/800x600
https://example.com/sample.jpg?key=value&m2param=/hdims/resize/800x600

  • M2 파라미터는 반드시 QueryString 맨 마지막에 위치해야 하며 URL 인코딩을 하지 않는다.

  • 원본서버는 Unknown QueryString을 해석하지 않는다.

  • HYPERDIMS에 의해 해석된 원본은 아래와 같다.

    https://example.com/sample.jpg?m2param=

위와 같이 불완전한 원본 URL이 싫다면 urlRewrites 를 통해 제거한다.

명령어 리스트

명령어에 이미지를 처리하는 기준점은 9가지의 Gravity 로 표현된다.

../../../../_images/conf_dims2.png

  • North (N) 0° = 360°

  • East (E) 90°

  • South (S) 180°

  • West (W) 270°

  • Northeast (NE) 45°

  • Southeast (SE) 135°

  • Southwest (SW) 225°

  • Northwest (NW) 315°

  • Center (C) -

기준점을 지칭할 때는 North 또는 NorthGravity 로 표현된다.

크기변경

# 기호 = (없음)
# 설명 = 원본비율 유지. 변경된 가로/세로 중 더 작은 길이로 서비스.
https://example.com/sample.jpg/hdims/resize/600x400
https://example.com/sample.jpg/hdims/resizec/600x400
https://example.com/sample.jpg/hdims/resizef/600x400
https://example.com/sample.jpg/hdims/resizemc/600x400
https://example.com/sample.jpg/hdims/resizecrop/600x400+10+40
https://example.com/sample.jpg/hdims/resizebr/size1

# 기호 = !
# 설명 = 원본비율 무시. 입력 값대로 크기변경
https://example.com/sample.jpg/hdims/resize/!600x400

# 기호 = ^
# 설명 = 가로, 세로 기준 리사이즈된 크기가 더 큰 이미지로 서비스
# 예제 =  1000 x 667 또는 750 x 500 중 더 큰 이미지로 서비스
https://example.com/sample.jpg/hdims/resize/^1000x500

# 기호 = > 또는 <
# 설명 = 해상도가 입력 값보다 크거나 작을 경우 크기를 변경
# 예제(1) = 가로가 1000보다 크면 1000으로 리사이즈
https://example.com/sample.jpg/hdims/resize/>1000x500

# 예제(2) = 세로가 500보다 크면 500으로 리사이즈
https://example.com/sample.jpg/hdims/resize/1000x>500

# 기호 = %
# 설명 = 가로, 세로 기준 원본 Width, Height 에서 N% 만큼 크기를 변경
# 예제 = 가로를 50% 크기로 줄여서 리사이즈
https://example.com/sample.jpg/hdims/resize/50%25

명령어

파라미터

동작

resize

가로x세로

  • 이미지를 가로 x 세로 크기로 resize 한다.

  • 반환되는 이미지는 가로 기준 or 세로 기준으로 변환 했을 때 더 작은 이미지를 반환한다.

resizec

가로x세로

  • 입력값이 원본보다 작은 요청일 경우 resize 동작을 수행한다.

  • 입력값이 원본보다 클 경우 투명 캔버스를 확장한다. ( 이미지는 png )

resizef

가로x세로

  • 입력값에 맞춰 resize 를 먼저 진행한다.

  • resize 된 크기에서 입력 값만큼 부족한 여백을 캔버스를 확장한다. ( 이미지는 jpg )

resizemc

가로x세로

  • 입력값이 원본보다 작을 경우 resize 를 먼저 진행한다.

  • resize된 크기에서 입력값만큼 부족한 여백을 캔버스를 확장한다.

  • 입력값이 원본보다 클 경우 resize를 하지 않는다.

  • 입력값 만큼 캔버스를 만든 후 원본을 CenterGravity로 합성한다.

resizecrop

가로x세로+X+Y

  • 입력값이 원본보다 작은 경우 ^ 옵션으로 resize 한다.

  • NorthGravity 기준으로 입력값에 맞춰 crop 을 진행한다.

  • 입력값이 원본보다 큰 경우 NorthGravity 기준으로 crop 한다.

  • 이후 입력값에 맞춰 resizemc 동작을 수행한다.

resizebr

{{name}}

  • 입력값을 설정에 존재하는 resizebr 판단 조건과 매칭한다.

  • 매칭리스트와 원본이 maxWidth 및 maxHeight 값에 충족되는지 확인한다.

  • 충족 시 command 명령어를 실행한다.

잘라내기

https://example.com/sample.jpg/hdims/crop/500x300+10+40
https://example.com/sample.jpg/hdims/cropcenter/500x300+10+10
https://example.com/sample.jpg/hdims/cropc/min
https://example.com/sample.jpg/hdims/cropc/max

명령어

파라미터

동작

crop

가로x세로+X+Y

  • 이미지를 가로x세로 크기만큼 잘라낸다.

  • X , Y 값에 따라 기준점이 이동한다. ( 기본값은 0,0 위치 )

cropcenter

가로x세로+X+Y

  • 이미지를 가로x세로 크기만큼 잘라낸다.

  • X , Y 값에 따라 기준점이 이동한다. ( 기본값은 이미지의 정중앙 위치 )

cropc

min 또는 max

  • min 입력 시 가로, 세로 크기 중에서 작은 값으로 이미지 가운데를 기준으로 crop 한다.

  • max 입력 시 가로, 세로 크기 중에서 큰 값을 기준으로 사용하는데 이 경우 원본 보다 crop 할 영역이 커지거나 같아지기 때문에 성능을 고려하여 원본을 그대로 서비스 한다.

crophm

가로x세로+X+Y

  • 이미지를 가로 변경 기준 (세로 값 - 리사이즈 할 세로 값) / 10 으로 margin을 주어 잘라낸다.

  • NorthGravity 기준으로 crop 한다.

최적화/품질 변경

https://example.com/sample.jpg/hdims/quality/85
https://example.com/sample.jpg/hdims/strip/true
https://example.com/sample.jpg/hdims/optimize

명령어

파라미터

동작

quality

1 ~ 100

  • 이미지의 품질을 변환한다. ( jpeg , png , webp , avif (beta) 지원 )

  • png 품질 조절시 팔레트 형식으로 자동 변환된다.

strip

true , false

  • 이미지의 비가시 정보를 삭제한다.

  • strip 명령 부재시 기본값 ``true``로 자동 설정된다.

optimize

(없음)

  • 이미지를 최적화한다.

포맷 변경

# 이미지 포맷을 WEBP로 변환
https://example.com/sample.jpg/hdims/format/webp

명령어

파라미터

동작

format

png , gif , jpg , webp , avif

  • 이미지 포맷을 변경한다.
포맷별 최대 해상도

포맷

최대 해상도

png

  • 제한 없음

jpg , gif

  • 65,536 x 65,536

webp

  • 16,383 x 16,383

avif

  • 16,384 x 16,384

Note

avif 포맷의 제약사항

  • 브라우저 호환을 위해 다음과 같은 명령어 옵션을 가진다.

옵션

동작

stillonly

  • 스틸이미지만 처리한다.

  • 애니매이션이라면 원본을 응답한다.

fallback

  • 처리불가시 다른 포맷으로 변경한다.

  • 만약 fallback 실패시 원본을 응답한다.

 
# 애니매이션 GIF를 AVIF 변환한다.
http://example.com/animate.gif/hdims/format/avif

# 스틸이미지 GIF를 AVIF 변환한다. (애니매이션 AVIF 미지원 브라우저 호환 옵션)
http://example.com/still.gif/hdims/format/avif;stillonly

# AVIF 변환 불가시 WEBP로 변환한다. WEBP 변환 불가시 원본 응답한다.
http://example.com/animate.gif/hdims/format/avif;stillonly;fallback=webp

Warning

애니매이션 avif 포맷의 제한사항

  • 본 함수는 애니매이션 avif 포맷 지원을 위해 transcoder 함수를 필요로 한다.

    • 이로인해 애니매이션 avif 변환시 본 함수의 resize 및 crop 명령어만 지원한다.

  • 만약 transcoder 함수 비활성 시 fallback 또는 원본 을 응답한다.

색감 변경

https://example.com/sample.jpg/hdims/grayscale/true
https://example.com/sample.jpg/hdims/brightness/40
https://example.com/sample.jpg/hdims/sepia/true
https://example.com/sample.jpg/hdims/invert/true
https://example.com/sample.jpg/hdims/sharpen/0x1

명령어

파라미터

동작

grayscale

true , false

  • 이미지를 흑백으로 변경한다.

brightness

-100 ~ 100

  • 이미지 명도를 조절한다.

sepia

true , false

  • 이미지를 세피아 색조로 변경한다.

invert

true , false

  • 이미지 색상을 반전시킨다.

sharpen

Radius x sigma

  • 이미지 선명도를 조절한다.

캔버스 조절

https://example.com/sample.jpg/hdims/trim/true
https://example.com/sample.jpg/hdims/extent/700x500

명령어

파라미터

동작

trim

true , false

  • 이미지 가장자리의 배경을 삭제한다.

  • 알파 채널(투명)이 있다면 알파 및 비알파 채널의 경계선을 가장자리로 한다.

extent

가로x세로

  • 입력값에 맞춰 캔버스의 크기를 조절한다.

  • 입력값이 원본보다 작을 경우 cropcenter 와 동일한 결과를 얻을 수 있다.

  • 입력값이 원본보다 클경우 캔버스크기만 확장된다.

회전

https://example.com/sample.jpg/hdims/rotate/90
https://example.com/sample.jpg/hdims/autorotate/true
https://example.com/sample.jpg/hdims/flipflop/vertical

명령어

파라미터

동작

rotate

0 ~ 360

  • 이미지를 각도만큼 회전시킨다.

autorotate

true , false

  • 이미지를 올바른 방향으로 회전시킨다.

Note

이 기능은 원본 이미지 메타를 분석하여 동작한다. 따라서 다른 기능들과 함께 사용될 때는 가장 먼저 적용되도록 구성한다.

https://example.com/img.jpg/hdims/autorotate/on/resize/200x200/...

flipflop

horizontal , vertical

  • 이미지를 수평, 수직으로 대칭이동시킨다.

Animated WEBP, GIF 프레임 제한

https://example.com/sample.gif/hdims/limit/10
https://example.com/sample.gif/hdims/frame/7

명령어

파라미터

동작

limit

프레임 수

  • Animated WEBP, GIF 의 프레임 수를 제한한다.

frame

프레임 번호

  • Animated WEBP, GIF 의 특정 프레임을 추출한다.

썸네일 생성

https://example.com/sample.jpg/hdims/thumbnail/400x300+10+40

명령어

파라미터

동작

thumbnail

가로x세로+X+Y

  • 이미지의 썸네일을 생성한다.

이미지 분석

이미지 분석정보를 JSON 형식으로 응답한다. 이 명령어는 단독으로 수행되어야 한다.

https://example.com/sample.jpg/hdims/analyze/src

# resize된 이미지의 정보
https://example.com/sample.jpg/hdims/resize/100/hdims/analyze/src

명령어

파라미터

동작

analyze

src

이미지 분석정보를 제공한다.

analyse

src

고~급스럽게 영국식 명령어를 제공한다.

 
{
  "enable": true,
  "url": "/image.jpg",
  "result": {
    "image": {
        "size": 3866,
        "format": "jpeg",
        "width": 477,
        "height": 776,
        "animated": false,
        "quality": 85,
        "colorspace": "srgb",
        "chromaSubsampling": "4:4:4"
    },
    "elapsed": {
        "init": 2,
        "complete": 14
    },
    "function": {
        "keyword": "hdims",
        "minSourceSize": 0,
        "maxSourceSize": 104857600,
        "optimizable": [
          "png", "jpeg", "gif", "webp", "avif"
        ]
    }
  }
}
enable

HYPERDIMS 모듈에 적재/처리 가능하다면 true , 불가하다면 false

url

원본 URL

result

분석결과

image

이미지 정보. HYPERDIMS 모듈에 적재할 수 없더라도 가능한 범위에서 분석정보를 제공한다.

size  (단위: bytes)

용량

format

포맷

width  (단위: px)

가로길이

height  (단위: px)

세로길이

animated

animated 여부

quality

이미지 압축품질. 이미지 제공시 존재.

colorspace

색 공간. 이미지 제공시 존재.

chromaSubsampling

크로마 서브샘플링. 이미지 제공시 존재.

elapsed

경과시간

init (단위: ms)

호출시점 ~ 원본이미지 초기화

complete (단위: ms)

호출시점 ~ 완료

function

HYPERDIMS 설정

keyword

호출 키워드

minSourceSize

최소 사이즈

maxSourceSize

최대 사이즈

optimizable

최적화 가능한 포맷

Note

meta.maxSourceSize 설정으로 용량 제한된 이미지의 경우 아래와 같이 처리는 불가 enable: false 하지만 result.image 정보를 제공한다.

{
  "enable": false,
  "error": "maxsize",
  "url": "/big/img.gif",
  "result": {
    "image": {
      "size": 43474428,
      "format": "gif",
      "width": 477,
      "height": 776,
      "animated": true
    },
    "function": {
      "keyword": "hdims",
      "minSourceSize": 0,
      "maxSourceSize": 10485760,
      "optimizable": [
          "png", "jpeg", "gif", "webp", "avif"
      ]
    }
  }
}

유사성 비교

원본과 가공된 이미지의 유사성을 SSIM(Structural Similarity Index Measure) 방식으로 비교한다.

Warning

동일 해상도에서만 동작함에 주의한다.

# optimize 된 이미지와 원본 이미지 비교
https://example.com/sample.jpg/hdims/optimize/analyze/ssim

# quality 50의 이미지와 원본 이미지 비교
https://example.com/sample.jpg/hdims/quality/50/analyze/ssim

명령어

파라미터

동작

analyze

ssim

원본과 가공된 이미지의 유사성을 비교한다.

 
{
  "enable": true,
  "url": "/sample.jpg",
  "result": {
    "ssim": 0.95
  }
}
enable

SSIM 비교가 정상처리되었다. 실패라면 false 로 응답하다.

url

원본 URL

result

분석결과

ssim (범위: 0~1)

원본과 가공된 이미지가 유사성으로 완전히 동일하다면 1 이다.

예외처리

이미지 처리 중 예외상황/오류가 발생했을 때 정책을 지정한다.

Note

기본정책은 원본 이미지를 전달한다.

# 오류 발생시 원본 이미지를 전달한다. (기본)
https://example.com/sample.jpg/hdims/resize/999999999x999999999/exception/origin

# 오류 발생시 510 Not Extended를 응답한다. 이 때 Body는 디버깅을 위한 분석정보가 노출된다.
https://example.com/sample.jpg/hdims/resize/999999999x999999999/exception/debug

# debug 응답

{
  # 원본이 200 OK라면 분석 정보를 제공한다.
  "origin": {
    ...
  },

  # error - 표준 에러리스트 정보
  "error": {
    "code": 31400001,
    "x-sc-chain": "failop",
    "vhost": "image.example.com",
    "url": "/sample.jpg",
    "x-ctx-id": "454ecfb6-13d8-496d-b137-8b0d411caa21",
    "command": "/resize/100x100",
    "content-length": 3120382,
    "reason": "unknown format"
  }
}

기타

https://example.com/sample.jpg/hdims/interlace/true
https://example.com/sample.jpg/hdims/noop

명령어

파라미터

동작

interlace

true , false

  • JPEG , PNG 포맷에 한해 포맷에 맞는 Interlace 정보를 추가한다.

noop

(없음)

  • 아무동작하지 않고 반환한다.

meta

"meta" : {
  "enable": false,
  "keyword": "hdims",
  "maxSourceSize": 100,
  "maxDestResolution": "8192x65535"
}
enable (기본: false)

HYPERDIMS 활성화

keyword (기본: hdims)

키워드

maxSourceSize (기본: 100MB)

변환을 허용할 최대 원본 이미지 크기 (단위: MB)

maxDestResolution (기본: 8192x65535)

변환을 허용할 최대 결과 이미지 해상도 (단위: 픽셀)

Note

  • 결과 이미지의 폭, 높이 중 1가지 이상 초과시 원본을 응답한다.

  • 최대 해상도보다 넓은 영역의 resize 명령시 원본을 응답한다.

  • 원본 이미지가 최대 해상도보다 넓은 경우, crop 또는 resize 명령을 통한 영역 축소시 변환을 허용한다.

image

입출력 이미지 규격을 정의한다.

"image": {
  "defaultQuality": {
    "jpeg": 85,
    "webp": 85,
    "avif": 70
  },
  "autorotate": true,
  "resizebr": [
    ...
  ]
}
defaultQuality (기본: jpeg=85, webp=85, avif=70)

이미지 생성시 퀄리티 기본값 1 ~ 100. 이 값은 quality, optimize 명령에 의해 오버라이드 될 수 있다.

Note

100 으로 설정할 경우 무손실 변환으로 진행된다. 이로 인해 얻는 시각적인 이득보다는 성능적 손해가 커 기본 값을 포맷별 적정값으로 설정한다.

autorotate (기본: true)

원본 회전 정보에 따라 자동 회전시킨다.

resizebr

"resizebr": [
  {
    "name": "size1",
    "matchingList": [
      {
        "maxWidth": 1024,
        "maxHeight": 768,
        "command": "/resize/720x538"
      },
      {
        "command": "/resize/480x240"
      }
    ]
  }
]
name

조건 판단 이름

matchingList

조건판단 리스트. 하위 maxWidth , maxHeight 조건이 없다면 조건을 이미지 크기에 상관없이 변환된다.

maxWidth

가로 길이가 설정 값보다 작으면 적용된다.

maxHeight

세로 길이가 설정 값보다 작으면 적용된다.

command

조건 판단 시 변환에 적용할 command

Note

resizebr 의 maxWidth 및 maxHeight 는 원본을 기준으로 판단한다.

resize를 통해 width x height가 변경되더라도 조건판단에 영향을 주지 않는다.