hyperdims

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

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

Note

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

• Thumbor

• Cloudflare - Transform images

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

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 로 표현된다.

• 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/resizef/600x400;bgcolor=yellow
https://example.com/sample.jpg/hdims/resizemc/600x400
https://example.com/sample.jpg/hdims/resizemc/600x400;bgcolor=0xFFFF00
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 동작을 수행한다. 입력값이 원본보다 클 경우 투명 캔버스를 확장한다. Warning jpeg 은 투명색을 지원하지 않으므로 png 포맷으로 자동 변환된다. png , gif , webp , avif 와 같이 투명색 지원시 원본 포맷을 유지한다.
resizef	가로x세로	입력값에 맞춰 resize 를 먼저 진행한다. resize 된 크기에서 입력값만큼 부족한 여백의 캔버스를 확장한다.
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
https://example.com/sample.jpg/hdims/extent/700x500;bgcolor=yellow

명령어	파라미터	동작
trim	true , false	이미지 가장자리의 배경을 삭제한다. 알파 채널(투명)이 있다면 알파 및 비알파 채널의 경계선을 가장자리로 한다.
extent	가로x세로	입력값에 맞춰 캔버스의 크기를 조절한다. 입력값이 원본보다 작을 경우 cropcenter 와 동일한 결과를 얻을 수 있다. 입력값이 원본보다 클경우 캔버스크기만 확장된다.

배경색 지정

이미지가 확장되는 경우 배경색을 지정한다. 미지정시 기본값은 white 이다.

# extent, resizef, resizemc 명령어는 캔버스가 확장될 수 있다.
https://example.com/sample.jpg/hdims/extent/700x500;bgcolor=yellow
https://example.com/sample.jpg/hdims/extent/700x500;bgcolor=0xFFFF00
https://example.com/sample.jpg/hdims/resizef/700x500;bgcolor=red
https://example.com/sample.jpg/hdims/resizemc/700x500;bgcolor=blue

옵션	동작
bgcolor=색상명	색상명으로 배경색을 지정한다. 색상명 목록
bgcolor=색상코드	16진수 색상코드로 배경색을 지정한다. 0xFFFFFF 와 같이 0x 문자로 시작한다.

Note

bgcolor 옵션은 다음의 3종 명령어와 함께 동작한다.

• extent , resizef , resizemc

회전

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 명령을 통한 영역 축소시 변환을 허용한다.

• 최대 해상도는 아래 표의 이미지 포맷 규격의 해상도를 초과할 수 없다.

포맷	해상도	maxDestResolution 기본값
jpeg	65,535 x 65,535	8192 x 65535
gif	65,535 x 65,535	8192 x 65535
avif	32,768 x 32,768	8192 x 32768
webp	16,383 x 16,383	8192 x 16383

• 포맷별 최대 해상도 제한시 다음과 같이 설정한다.

  "meta": {
      "maxDestResolution": "8192x65535;avif=8192x32768;webp=8192x16383"
  }
  

session

"session" : {
  "proxyTimeout": 0
}

proxyTimeout (기본: 0)

proxy 를 이용한 원본 이미지 다운로드 타임아웃

• 0 Cache 엔진의 타임아웃 설정에 따른다.

• {n} 지정된 시간(초) 이후 타임아웃 처리한다.

Note

타임아웃 처리시 504 Gateway Timeout 응답한다.

Content-Type: application/json

{
  "function": "hyperdims",
  "error": "timeout",
  "elapsed": 10
}

image

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

"image": {
  "defaultQuality": {
    "jpeg": 85,
    "webp": 85,
    "avif": 70
  },
  "autorotate": true,
  "forceQuality": false,
  "optimize": {
    "priority": "size"
  },
  "resizebr": [
    ...
  ]
}

defaultQuality (기본: jpeg=85, webp=85, avif=70)

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

Note

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

autorotate (기본: true)

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

forceQuality (기본: false)

quality 강제 적용 여부.

• false 일 때, 입력 quality보다 원본 quality가 더 낮다면 원본 quality를 유지한다.

• true 라면 원본의 quality 정보를 무시하고 defaultQuality 값과 입력값에 의존하여 quality 변경을 진행한다.

Important

• forceQuality 활성화 시, 하기와 같은 표와 같은 형태로 quality 값을 조정한다.

원본 quality	default Quality	입력 quality	결과 quality
95	85	70	70
20	85	70	70
95	85	90	90
20	85	90	85

optimize

"optimize": {
  "priority": "size"
}

priority

최적화 우선순위

• size (기본값) 보통 품질로 최적화하여 용량을 절감한다.

• quality 우수한 품질을 유지하며 용량을 소폭 절감한다.

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가 변경되더라도 조건판단에 영향을 주지 않는다.