Go-библиотека для отдачи тайлов Deep Zoom Image из ZIP-архивов в S3 и для сборки диапазона тайлов в одно изображение.
- принимает DZI URL с hex-encoded именем ZIP
- скачивает ZIP из S3 при первом запросе
- распаковывает архив в локальный cache directory
- отдаёт отдельные тайлы из локального кеша
- умеет собирать диапазон тайлов в одно JPEG-изображение через отдельный
/composite/...endpoint
Ожидается ZIP-архив с DZI-структурой уровней:
archive.zip
page_1_files/
0/
0_0.webp
1/
0_0.webp
1_0.webp
При распаковке .dzi и .xml файлы пропускаются. Тайлы сохраняются в локальный кеш по пути:
{CacheDir}/{md5(zip_key)}/{level}/{col}_{row}.{ext}
type Config struct {
Listen string
S3AccessKey string
S3SecretKey string
S3Region string
S3Bucket string
S3Host string
S3UseSSL bool
CleanupTimeoutCfg int
CleanupTimeout time.Duration
CacheDir string
HttpCacheDays int
Silent bool
Debug bool
}Минимально нужно задать:
ListenS3AccessKeyS3SecretKeyS3RegionS3BucketS3HostCacheDirHttpCacheDaysDebug
cfg := &dziproxylib.Config{
Listen: ":8080",
S3AccessKey: "...",
S3SecretKey: "...",
S3Region: "us-east-1",
S3Bucket: "my-bucket",
S3Host: "https://s3.example.com",
S3UseSSL: true,
CacheDir: "./cache",
HttpCacheDays: 7,
CleanupTimeout: time.Hour,
}
srv, err := dziproxylib.DziProxyServer(cfg)
if err != nil {
panic(err)
}
go dziproxylib.CleanupCache()
panic(srv.ListenAndServe())Сервер принимает исходный DZI-путь и отдаёт конкретный тайл:
/18/dzi/page_1/{hex_zip_name}/12/34_56.jpg
или:
/18/dzi_bw/page_1/{hex_zip_name}/12/34_56.webp
Где {hex_zip_name} это hex-encoded строка вида:
98d0393e-4b23-4884-b38f-9b55d4a1e906(Yellow).zip
После декодирования сервер использует этот путь как S3 key.
Для сборки диапазона тайлов используется отдельный route:
/composite/18/dzi_bw/page_1/{hex_zip_name}?level={int}&col_min={int}&col_max={int}&row_min={int}&row_max={int}&overlap={int}&max_size={int}&is_color={bool}
col_mincol_maxrow_minrow_max
levelесли не передан, берётся максимальный доступный уровень из распакованного архиваoverlapпо умолчанию1max_sizeограничение на большую сторону итогового изображения с сохранением пропорцийis_colorпо умолчаниюtrueеслиfalse, итоговый буфер собирается какimage.Gray
- итог всегда отдаётся как
image/jpeg - overlap учитывается при склейке соседних тайлов
- если задан
max_size, изображение собирается сразу в уменьшённый размер - перед финальным resize для
image.YCbCrиimage.Grayиспользуется progressive downscaling: изображение последовательно уменьшается в 2 раза, пока это выгодно, и только потом применяется финальныйApproxBiLinear - для
webpтайлов используется декодерgolang.org/x/image/webp
/composite/18/dzi_bw/page_1/39386430333933652d346232332d343838342d623338662d3962353564346131653930362859656c6c6f77292e7a6970?col_min=10&col_max=20&row_min=5&row_max=12&max_size=2000&is_color=false
- ZIP скачивается и распаковывается один раз на
key - параллельные запросы к одному и тому же архиву синхронизируются через mutex + wait group
- максимальный
levelдля/composite/...кешируется в памяти поkey - фоновая очистка удаляет старые директории из кеша по
CleanupTimeout
Для half-downscale проходов в composite pipeline есть SIMD-реализация под Go 1.26:
- scalar fallback используется по умолчанию
- SIMD-вариант собирается только при
GOEXPERIMENT=simd - текущая SIMD-реализация включается только на
amd64
Пример сборки или запуска тестов с SIMD:
GOEXPERIMENT=simd go test ./...На arm64 и в обычной сборке библиотека автоматически использует scalar fallback без дополнительных настроек.
Для /composite/... включены memory trace логи:
composite.after_prepare_archivecomposite.before_buildcomposite.after_buildcomposite.after_encode
Логи выводятся только если Config.Debug == true.
Функция логирования находится в memstats.go.
- composite endpoint возвращает только JPEG
- обычный tile endpoint сейчас выставляет
Content-Type: image/jpeg, даже если файл тайла имеет другое расширение - библиотека хранит распакованные архивы на локальном диске
- SIMD-ускорение half-downscale сейчас недоступно на
arm64