{"_id":"@blazediff/ssim","_rev":"3-67ff31750bf4b92c17f4198099c5131f","name":"@blazediff/ssim","dist-tags":{"latest":"1.7.1"},"versions":{"1.6.0":{"name":"@blazediff/ssim","version":"1.6.0","keywords":["image","comparison","ssim","gradient","similarity","visual-testing","ci"],"author":{"url":"https://github.com/teimurjan","name":"Teimur Gasanov","email":"me@teimurjan.dev"},"license":"MIT","_id":"@blazediff/ssim@1.6.0","maintainers":[{"name":"teimurjan","email":"teymurgg321@gmail.com"}],"homepage":"https://blazediff.dev","bugs":{"url":"https://github.com/teimurjan/blazediff/issues"},"dist":{"shasum":"73159a57dbabda1175ac3fcb0d20f73978cc0350","tarball":"https://registry.npmjs.org/@blazediff/ssim/-/ssim-1.6.0.tgz","fileCount":17,"integrity":"sha512-9LZUY47+fCam4GsaEQcCIyWbxdAYTVarvn09UsIs2ShFgeQfzu4QSvk9Ji10pk+EATtiHHZAFIeiYpgvL0nbFQ==","signatures":[{"sig":"MEUCIQDztpb9Gy2SLSJQoH6iljl+DiFXzHXSysZHiAKrPviLsgIgLksQhoWjHZf8cXsoq7lv2Qty2TIxOR+NJn8kGsBv5as=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":42014},"main":"dist/ssim.js","_from":"file:blazediff-ssim-1.6.0.tgz","types":"dist/ssim.d.ts","module":"dist/ssim.mjs","exports":{".":{"types":"./dist/ssim.d.ts","import":"./dist/ssim.mjs","require":"./dist/ssim.js"},"./ssim":{"types":"./dist/ssim.d.ts","import":"./dist/ssim.mjs","require":"./dist/ssim.js"},"./msssim":{"types":"./dist/msssim.d.ts","import":"./dist/msssim.mjs","require":"./dist/msssim.js"},"./hitchhikers-ssim":{"types":"./dist/hitchhikers-ssim.d.ts","import":"./dist/hitchhikers-ssim.mjs","require":"./dist/hitchhikers-ssim.js"}},"private":false,"scripts":{"dev":"tsup --watch","test":"vitest run","build":"tsup","clean":"rm -rf dist","test:watch":"vitest"},"_npmUser":{"name":"teimurjan","email":"teymurgg321@gmail.com"},"_resolved":"/tmp/7dee093bb870f7b2dcfb8efb46e45a24/blazediff-ssim-1.6.0.tgz","_integrity":"sha512-9LZUY47+fCam4GsaEQcCIyWbxdAYTVarvn09UsIs2ShFgeQfzu4QSvk9Ji10pk+EATtiHHZAFIeiYpgvL0nbFQ==","repository":{"url":"git+https://github.com/teimurjan/blazediff.git","type":"git"},"_npmVersion":"10.9.2","description":"Fast single-threaded SSIM (Structural Similarity Index) metric for CI visual testing","directories":{},"_nodeVersion":"22.14.0","publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"tsup":"8.5.0","pngjs":"^7.0.0","vitest":"^3.2.4","ssim.js":"^3.5.0","@vitest/ui":"^3.2.4","typescript":"5.9.2","@types/node":"^24.3.0","@blazediff/pngjs-transformer":"1.6.0"},"_npmOperationalInternal":{"tmp":"tmp/ssim_1.6.0_1761057733628_0.2857815222271214","host":"s3://npm-registry-packages-npm-production"}},"1.7.0":{"name":"@blazediff/ssim","version":"1.7.0","keywords":["image","comparison","ssim","gradient","similarity","visual-testing","ci"],"author":{"url":"https://github.com/teimurjan","name":"Teimur Gasanov","email":"me@teimurjan.dev"},"license":"MIT","_id":"@blazediff/ssim@1.7.0","maintainers":[{"name":"teimurjan","email":"teymurgg321@gmail.com"}],"homepage":"https://blazediff.dev","bugs":{"url":"https://github.com/teimurjan/blazediff/issues"},"dist":{"shasum":"df8a7a21f92f1da69209005380e695d5e1776898","tarball":"https://registry.npmjs.org/@blazediff/ssim/-/ssim-1.7.0.tgz","fileCount":17,"integrity":"sha512-OWSOr6AElb0+dimEzQe35kzJqBeVmRepgMitrlm1TmoDJuQOlObegtPLK4LQWAroW7Ss28L5A1DF7bNeDCSDgw==","signatures":[{"sig":"MEUCIQDFzrjO/fEiagiBakRHTrR7niUPPt0Jm32s+mTDXoftEgIgG5w2fY+MGfhqge8i4fvO5cr9U+ezKShWrfbRrjVmsnY=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":42479},"main":"dist/ssim.js","_from":"file:blazediff-ssim-1.7.0.tgz","types":"dist/ssim.d.ts","module":"dist/ssim.mjs","exports":{".":{"types":"./dist/ssim.d.ts","import":"./dist/ssim.mjs","require":"./dist/ssim.js"},"./ssim":{"types":"./dist/ssim.d.ts","import":"./dist/ssim.mjs","require":"./dist/ssim.js"},"./msssim":{"types":"./dist/msssim.d.ts","import":"./dist/msssim.mjs","require":"./dist/msssim.js"},"./hitchhikers-ssim":{"types":"./dist/hitchhikers-ssim.d.ts","import":"./dist/hitchhikers-ssim.mjs","require":"./dist/hitchhikers-ssim.js"}},"private":false,"scripts":{"dev":"tsup --watch","test":"vitest run","build":"tsup","clean":"rm -rf dist","analyze":"tsx scripts/analyze-with-imgdiff.ts","test:watch":"vitest"},"_npmUser":{"name":"teimurjan","email":"teymurgg321@gmail.com"},"_resolved":"/tmp/5da5aa6288e24d852816b518cd370fe7/blazediff-ssim-1.7.0.tgz","_integrity":"sha512-OWSOr6AElb0+dimEzQe35kzJqBeVmRepgMitrlm1TmoDJuQOlObegtPLK4LQWAroW7Ss28L5A1DF7bNeDCSDgw==","repository":{"url":"git+https://github.com/teimurjan/blazediff.git","type":"git"},"_npmVersion":"10.9.2","description":"Fast single-threaded SSIM (Structural Similarity Index) metric for CI visual testing","directories":{},"_nodeVersion":"22.14.0","publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"tsx":"^4.20.6","tsup":"8.5.0","pngjs":"^7.0.0","vitest":"^3.2.4","ssim.js":"^3.5.0","@vitest/ui":"^3.2.4","typescript":"5.9.2","@types/node":"^24.3.0","@blazediff/pngjs-transformer":"2.0.0"},"_npmOperationalInternal":{"tmp":"tmp/ssim_1.7.0_1763823679096_0.423088900452522","host":"s3://npm-registry-packages-npm-production"}},"1.7.1":{"name":"@blazediff/ssim","version":"1.7.1","description":"Fast single-threaded SSIM (Structural Similarity Index) metric for CI visual testing","private":false,"publishConfig":{"access":"public"},"main":"dist/ssim.js","module":"dist/ssim.mjs","types":"dist/ssim.d.ts","exports":{".":{"types":"./dist/ssim.d.ts","import":"./dist/ssim.mjs","require":"./dist/ssim.js"},"./ssim":{"types":"./dist/ssim.d.ts","import":"./dist/ssim.mjs","require":"./dist/ssim.js"},"./msssim":{"types":"./dist/msssim.d.ts","import":"./dist/msssim.mjs","require":"./dist/msssim.js"},"./hitchhikers-ssim":{"types":"./dist/hitchhikers-ssim.d.ts","import":"./dist/hitchhikers-ssim.mjs","require":"./dist/hitchhikers-ssim.js"}},"keywords":["image","comparison","ssim","gradient","similarity","visual-testing","ci"],"author":{"name":"Teimur Gasanov","email":"me@teimurjan.dev","url":"https://github.com/teimurjan"},"repository":{"type":"git","url":"git+https://github.com/teimurjan/blazediff.git"},"homepage":"https://blazediff.dev","license":"MIT","devDependencies":{"@types/node":"^24.3.0","@vitest/ui":"^3.2.4","pngjs":"^7.0.0","ssim.js":"^3.5.0","tsup":"8.5.0","tsx":"^4.20.6","typescript":"5.9.2","vitest":"^3.2.4","@blazediff/pngjs-transformer":"2.1.1"},"scripts":{"typecheck":"tsc --noEmit","build":"tsup","dev":"tsup --watch","clean":"rm -rf dist","test":"vitest run","test:watch":"vitest","analyze":"tsx scripts/analyze-with-imgdiff.ts"},"_id":"@blazediff/ssim@1.7.1","bugs":{"url":"https://github.com/teimurjan/blazediff/issues"},"_integrity":"sha512-CxdtlPLijlp2tbwDavEOlDCtonWroHpXBfp/Ptue8IRTKeKnuDCotWZliH0tFJRYpsORxBUKXAc4vWVBrPUnPw==","_resolved":"/tmp/cbdcf33184f2662f063ea262a39c2caa/blazediff-ssim-1.7.1.tgz","_from":"file:blazediff-ssim-1.7.1.tgz","_nodeVersion":"22.14.0","_npmVersion":"10.9.2","dist":{"integrity":"sha512-CxdtlPLijlp2tbwDavEOlDCtonWroHpXBfp/Ptue8IRTKeKnuDCotWZliH0tFJRYpsORxBUKXAc4vWVBrPUnPw==","shasum":"3689731dfda80f61190ac12ca0f57cb106e0a463","tarball":"https://registry.npmjs.org/@blazediff/ssim/-/ssim-1.7.1.tgz","fileCount":13,"unpackedSize":35806,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQDfSwUGM9ZmKh306kzLXIM3aicf1t+YEwNnd4IPph0fAQIgCVLOoEz4IxKRkrfrtJs0wct18PybXQG3EKKT54rrOa0="}]},"_npmUser":{"name":"teimurjan","email":"teymurgg321@gmail.com"},"directories":{},"maintainers":[{"name":"teimurjan","email":"teymurgg321@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/ssim_1.7.1_1768152203751_0.296151068310468"},"_hasShrinkwrap":false}},"time":{"created":"2025-10-21T14:42:13.497Z","modified":"2026-01-11T17:23:24.145Z","1.6.0":"2025-10-21T14:42:13.804Z","1.7.0":"2025-11-22T15:01:19.299Z","1.7.1":"2026-01-11T17:23:23.900Z"},"bugs":{"url":"https://github.com/teimurjan/blazediff/issues"},"author":{"name":"Teimur Gasanov","email":"me@teimurjan.dev","url":"https://github.com/teimurjan"},"license":"MIT","homepage":"https://blazediff.dev","keywords":["image","comparison","ssim","gradient","similarity","visual-testing","ci"],"repository":{"type":"git","url":"git+https://github.com/teimurjan/blazediff.git"},"description":"Fast single-threaded SSIM (Structural Similarity Index) metric for CI visual testing","maintainers":[{"name":"teimurjan","email":"teymurgg321@gmail.com"}],"readme":"# @blazediff/ssim\n\n
\n\n[![npm bundle size](https://img.shields.io/bundlephobia/min/%40blazediff%2Fssim)](https://www.npmjs.com/package/@blazediff/ssim)\n[![NPM Downloads](https://img.shields.io/npm/dy/%40blazediff%2Fssim)](https://www.npmjs.com/package/@blazediff/ssim)\n\n
\n\nFast SSIM (Structural Similarity Index) implementations for perceptual image quality assessment. Includes standard SSIM, MS-SSIM (Multi-Scale SSIM), and Hitchhiker's SSIM for various use cases and performance requirements.\n\n**Features:**\n- **Three SSIM Variants** - Standard SSIM, MS-SSIM, and Hitchhiker's SSIM\n- **MATLAB-compatible** - Matches reference implementation with <0.01% error\n- **High Performance** - Optimized implementations with ~4x faster Hitchhiker's SSIM\n- **Perceptual Metrics** - Structural similarity scoring (0-1 scale)\n- **SSIM Map Output** - Optional grayscale visualization\n- **Zero Dependencies**\n- **TypeScript Support** out of the box\n\nFor detailed algorithm explanation and mathematical formulas, see [FORMULA.md](./FORMULA.md).\n\n## Installation\n\n```bash\nnpm install @blazediff/ssim\n```\n\n## API\n\n### `ssim(image1, image2, output, width, height, options?)`\n\nCompares two images using the standard SSIM algorithm with automatic downsampling and returns a similarity score.\n\n\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n
ParameterTypeDescription
image1Uint8Array, Uint8ClampedArray, or BufferFirst image data (RGBA format, 4 bytes per pixel)
image2Uint8Array, Uint8ClampedArray, or BufferSecond image data (RGBA format, 4 bytes per pixel)
outputUint8Array, Uint8ClampedArray, Buffer, or undefinedOptional output buffer for SSIM map visualization (RGBA format)
widthnumberImage width in pixels
heightnumberImage height in pixels
optionsSsimOptionsExtendedSSIM computation options (optional)
\n\n**Returns:** `number` - SSIM score (0-1, where 1 is identical)\n\n#### Options\n\n\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n
OptionTypeDefaultDescription
windowSizenumber11Size of the Gaussian window
k1number0.01Algorithm parameter for luminance
k2number0.03Algorithm parameter for contrast
Lnumber255Dynamic range of pixel values
\n\n### `msssim(image1, image2, output, width, height, options?)`\n\nCompares two images using the Multi-Scale SSIM (MS-SSIM) algorithm and returns a similarity score.\n\nSame parameters as `ssim()`, but analyzes images at multiple scales (default: 5 levels) for better perceptual accuracy.\n\n**Returns:** `number` - MS-SSIM score (0-1, where 1 is identical)\n\n#### Options\n\n\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n
OptionTypeDefaultDescription
windowSizenumber11Size of the Gaussian window
scalesnumber5Number of scales to use
weightsnumber[][0.0448, 0.2856, 0.3001, 0.2363, 0.1333]Weights for each scale
method'product' or 'sum''product'Aggregation method
\n\n### `hitchhikersSSIM(image1, image2, output, width, height, options?)`\n\nCompares two images using Hitchhiker's SSIM (fast rectangular-window version with integral images).\n\n**Performance:** ~4x faster than standard SSIM using integral images for O(1) window computation.\n\n\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n
ParameterTypeDescription
image1Uint8Array, Uint8ClampedArray, or BufferFirst image data (RGBA format, 4 bytes per pixel)
image2Uint8Array, Uint8ClampedArray, or BufferSecond image data (RGBA format, 4 bytes per pixel)
outputUint8Array, Uint8ClampedArray, Buffer, or undefinedOptional output buffer for SSIM map
widthnumberImage width in pixels
heightnumberImage height in pixels
optionsHitchhikersSsimOptionsSSIM computation options (optional)
\n\n**Returns:** `number` - SSIM score (0-1, where 1 is identical)\n\n#### Options\n\n\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n
OptionTypeDefaultDescription
windowSizenumber11Size of the rectangular window
windowStridenumberwindowSizeStride for window sliding (non-overlapping by default)
covPoolingbooleantrueUse Coefficient of Variation pooling (recommended)
k1number0.01Algorithm parameter for luminance
k2number0.03Algorithm parameter for contrast
Lnumber255Dynamic range of pixel values
\n\n## Usage\n\n### Basic SSIM Comparison\n\n```typescript\nimport ssim from '@blazediff/ssim/ssim';\n\nconst score = ssim(image1.data, image2.data, undefined, width, height);\n\nconsole.log(`Similarity: ${score.toFixed(4)}`); // e.g., \"Similarity: 0.9823\"\n\n// Use in tests\nif (score < 0.95) {\n throw new Error(`Images differ too much: ${score}`);\n}\n```\n\n### Multi-Scale SSIM (MS-SSIM)\n\n```typescript\nimport msssim from '@blazediff/ssim/msssim';\n\n// MS-SSIM provides better perceptual accuracy by analyzing at multiple scales\nconst score = msssim(image1.data, image2.data, undefined, width, height);\n\nconsole.log(`MS-SSIM: ${score.toFixed(4)}`);\n```\n\n### Hitchhiker's SSIM (Fast)\n\n```typescript\nimport hitchhikersSSIM from '@blazediff/ssim/hitchhikers-ssim';\n\n// ~4x faster than standard SSIM\nconst score = hitchhikersSSIM(image1.data, image2.data, undefined, width, height);\n\nconsole.log(`Hitchhiker's SSIM: ${score.toFixed(4)}`);\n\n// With custom options\nconst scoreCustom = hitchhikersSSIM(image1.data, image2.data, undefined, width, height, {\n windowSize: 16,\n windowStride: 8, // Overlapping windows\n covPooling: true, // CoV pooling (recommended)\n});\n```\n\n### Custom Options\n\n```typescript\nimport ssim from '@blazediff/ssim/ssim';\n\n// Basic SSIM with custom window size\nconst score = ssim(image1, image2, undefined, width, height, {\n windowSize: 7, // Smaller window for more local detail\n k1: 0.01,\n k2: 0.03,\n L: 255\n});\n\n// MS-SSIM with custom scales and method\nimport msssim from '@blazediff/ssim/msssim';\n\nconst msScore = msssim(image1, image2, undefined, width, height, {\n scales: 5, // Number of scales (default: 5)\n method: 'product', // 'product' or 'sum'\n windowSize: 11\n});\n```\n\n### SSIM Map Visualization\n\nThe SSIM map shows local similarity values as a grayscale image:\n\n```typescript\nimport ssim from '@blazediff/ssim/ssim';\n\n// Create output buffer for SSIM map\nconst output = new Uint8ClampedArray(width * height * 4);\n\nconst score = ssim(image1, image2, output, width, height);\n\n// output now contains grayscale SSIM map\n// White (255) = high similarity, Black (0) = low similarity\n// Can be saved as PNG or displayed for debugging\n```\n\n## When to Use Each Variant\n\n**Use SSIM when:**\n- You need **MATLAB-compatible results** for research or comparison\n- You want **high accuracy** with Gaussian weighting\n- You need **automatic downsampling** for large images\n- Performance is not critical\n\n**Use MS-SSIM when:**\n- You need **multi-scale analysis** for better perceptual correlation\n- You're working with images at **different resolutions**\n- You want **better correlation with human perception**\n- You can afford the ~2-3x computation cost\n\n**Use Hitchhiker's SSIM when:**\n- You need **maximum performance** (~4x faster than standard SSIM)\n- You're processing **large images** or **many images**\n- You want **O(1) window computation** regardless of window size\n- You need **flexible window stride** for overlapping/non-overlapping windows\n- CoV pooling provides better perceptual correlation than mean\n\n## Score Interpretation\n\n| Score Range | Similarity Level | Description |\n| ----------- | ---------------- | ----------- |\n| `1.0` | Identical | Images are identical or perceptually identical |\n| `0.99+` | Excellent | Extremely high similarity (minor compression artifacts) |\n| `0.95-0.99` | Very Good | High similarity (small compression or noise) |\n| `0.90-0.95` | Good | Noticeable but acceptable differences |\n| `0.80-0.90` | Fair | Significant but tolerable differences |\n| `<0.80` | Poor | Major structural differences |\n\n## References\n\n### SSIM & MS-SSIM\n- **Wang, Z., Bovik, A. C., Sheikh, H. R., & Simoncelli, E. P.** (2004). [Image quality assessment: from error visibility to structural similarity](https://ieeexplore.ieee.org/document/1284395). IEEE Transactions on Image Processing, 13(4), 600-612.\n- **Wang, Z., Simoncelli, E. P., & Bovik, A. C.** (2003). [Multi-scale structural similarity for image quality assessment](https://ieeexplore.ieee.org/document/1292216). IEEE Asilomar Conference on Signals, Systems & Computers.\n- **MATLAB Reference Implementations**: [Zhou Wang's Research Group](https://ece.uwaterloo.ca/~z70wang/research/ssim/)\n\n### Hitchhiker's SSIM\n- **Venkataramanan, A. K., Wu, C., Bovik, A. C., Katsavounidis, I., & Shahid, Z.** (2021). [A Hitchhiker's Guide to Structural Similarity](https://ieeexplore.ieee.org/document/9345560). IEEE Access, 9, 28872-28896.\n- **Reference Implementation**: [utlive/enhanced_ssim](https://github.com/utlive/enhanced_ssim)\n- **License**: BSD-2-Clause-Patent (Netflix, Inc.)\n\n## License\n\nSee [../../licenses](../../licenses) for algorithm attribution and licensing information.\n","readmeFilename":"README.md"}