Refactor dimension handling and the transformation pipeline

[mbklein]

This is a pretty big refactoring of how node-iiif retrieves and makes use of image dimensions, as well as the pipeline setup. It was done to facilitate two things:

• Splitting out the Calculator (the parts of the library that do transformation calculations) from the Transformer (which actually does the image manipulation). This is an important step in allowing consumers to use the Calculator to get additional information about what the processor will do, without actually executing the transformation. It was written to support the functionality discussed in samvera/serverless-iiif#98, specifically this comment.
• Making better use of pyramidal TIFF files (or other multi-resolution source images). Up until now, the processor has always fed the image stream directly to the sharp pipeline on the (incorrect) assumption that sharp would use the most efficient resolution available to perform the requested transformation. This change allows the transformer to pick the frame with the resolution closest in size (without going under) to the desired output size. I've seen some enormous gains in performance when delivering full-frame or cropped images from large sources at 50% scale or less.

In the process, I also learned how to use sharp's internal metadata() method when the source is a stream, something I had experimented with previously without success. Not only is it possible, but benchmarks showed it to be about 40-60% faster than the probe-image-size package the default dimension function had been using. More efficiency, fewer dependencies.

Despite the extensive changes, the module is still interface-compatible with v3.x. I think a minor version bump would be warranted on release.

[mbklein]

Some benchmarks:

node-iiif v3.1.2:

$ time curl -svo /dev/null http://localhost:3000/iiif/2/98-pyramid/full/3000,/0/default.jpg
*   Trying 127.0.0.1:3000...
* Connected to localhost (127.0.0.1) port 3000 (#0)
> GET /iiif/2/98-pyramid/full/3000,/0/default.jpg HTTP/1.1
> Host: localhost:3000
> User-Agent: curl/7.82.0
> Accept: */*
> 
* Mark bundle as not supporting multiuse
< HTTP/1.1 200 OK
< X-Powered-By: tinyhttp
< Access-Control-Allow-Headers: *
< Access-Control-Allow-Methods: OPTIONS, HEAD, GET, POST, PUT, DELETE
< Access-Control-Allow-Origin: *
< Content-Type: image/jpeg
< etag: W/"107d67-dXEkzjCmTRpc/pInIctorvC6MG4"
< Date: Tue, 21 Mar 2023 15:03:28 GMT
< Connection: keep-alive
< Keep-Alive: timeout=5
< Content-Length: 1080679
< 
* Closing connection 0

curl 0.00s user 0.01s system 0% cpu 40.512 total

node-iiif from this PR branch:

✗ time curl -svo /dev/null http://localhost:3000/iiif/2/98-pyramid/full/3000,/0/default.jpg
*   Trying 127.0.0.1:3000...
* Connected to localhost (127.0.0.1) port 3000 (#0)
> GET /iiif/2/98-pyramid/full/3000,/0/default.jpg HTTP/1.1
> Host: localhost:3000
> User-Agent: curl/7.82.0
> Accept: */*
> 
* Mark bundle as not supporting multiuse
< HTTP/1.1 200 OK
< X-Powered-By: tinyhttp
< Access-Control-Allow-Headers: *
< Access-Control-Allow-Methods: OPTIONS, HEAD, GET, POST, PUT, DELETE
< Access-Control-Allow-Origin: *
< Content-Type: image/jpeg
< etag: W/"10554c-yt9DtAPYwz7Z57N3wYf8EEKQJyQ"
< Date: Tue, 21 Mar 2023 15:06:19 GMT
< Connection: keep-alive
< Keep-Alive: timeout=5
< Content-Length: 1070412
< 
* Connection #0 to host localhost left intact

curl 0.00s user 0.01s system 1% cpu 0.651 total

40.5s down to 651ms seems like a decent return on investment. 😄

[orangewolf]

I think the answer to both my questions is likely "yes this works the right way". if that's the case then Im happily in approval

[mbklein]

Benchmarked using Benchmark.js, via this test script. Test images were fed to the benchmark script via a text file called s3Urls.txt, containing one s3://bucket/key URI per line.

$ ./tiff_metadata_benchmarks.js
sharp.metadata() x 4,141 ops/sec ±35.51% (24 runs sampled)
probe() x 2,372 ops/sec ±25.77% (27 runs sampled)
Fastest is [ 'sharp.metadata()' ]