lightdrift-libraw 1.0.0-alpha.2 → 1.0.0-alpha.4

package/README.md

@@ -20,6 +20,8 @@ A high-performance Node.js Native Addon for processing RAW image files using the
 - ✅ **AI-Powered Settings** - 🆕 Automatic quality optimization based on image analysis
 - ✅ **Memory Operations** - Process images entirely in memory
 - ✅ **Multiple Output Formats** - PPM, TIFF, JPEG with advanced compression options
+- ✅ **Buffer Creation API** - 🆕 Create image buffers directly in memory (JPEG, PNG, WebP, AVIF, TIFF, PPM, Thumbnails)
+- ✅ **Stream-based Processing** - 🆕 Return data streams instead of writing to files
 - ✅ **Buffer Support** - Load RAW data from memory buffers
 - ✅ **Configuration Control** - Gamma, brightness, color space settings
 - ✅ **High Performance** - Native C++ processing with JavaScript convenience
@@ -55,16 +57,89 @@ LibRaw supports 100+ RAW formats including:
 npm install lightdrift-libraw
 ```
 
-**Version 1.0.0-alpha.1** is now available on [npmjs.com](https://www.npmjs.com/package/lightdrift-libraw)! 🎉
+**Version 1.0.0-alpha.3** is now available on [npmjs.com](https://www.npmjs.com/package/lightdrift-libraw)! 🎉
 
-### 🛠️ Build Requirements
+### 🛠️ System Requirements
+
+#### **Windows**
+
+- **Node.js** 14.0.0 or higher
+- **Python** 3.6+ (for node-gyp)
+- **Visual Studio Build Tools** 2019+ or Visual Studio Community
+- LibRaw is bundled (no additional dependencies needed)
+
+#### **Linux (Alpine/Debian/Ubuntu)**
 
 - **Node.js** 14.0.0 or higher
 - **Python** 3.6+ (for node-gyp)
-- **C++ Build Tools**:
-  - Windows: Visual Studio 2019+ or VS Build Tools
-  - macOS: Xcode Command Line Tools
-  - Linux: GCC 8+ or equivalent
+- **LibRaw development package**:
+
+  ```bash
+  # Alpine
+  apk add libraw-dev build-base
+
+  # Debian/Ubuntu
+  apt-get install libraw-dev build-essential
+
+  # Then install the package
+  npm install lightdrift-libraw
+  ```
+
+#### **macOS**
+
+- **Node.js** 14.0.0 or higher
+- **Xcode Command Line Tools**: `xcode-select --install`
+- **LibRaw**:
+  ```bash
+  brew install libraw
+  npm install lightdrift-libraw
+  ```
+
+### 🐳 Docker Usage
+
+When using Docker or pnpm, you may need to explicitly rebuild native modules:
+
+```dockerfile
+FROM node:18-alpine
+
+# Install system dependencies
+RUN apk add --no-cache \
+    python3 \
+    make \
+    g++ \
+    libraw-dev
+
+WORKDIR /app
+
+# Copy package files
+COPY package*.json ./
+
+# Install dependencies
+RUN npm install --frozen-lockfile
+
+# Explicitly rebuild native module
+RUN npm rebuild lightdrift-libraw
+
+# Copy application
+COPY . .
+
+CMD ["node", "app.js"]
+```
+
+#### **pnpm in Docker**
+
+If using pnpm, add `.npmrc` to your project:
+
+```
+enable-pre-post-scripts=true
+```
+
+Or rebuild manually:
+
+```dockerfile
+RUN pnpm install --frozen-lockfile
+RUN pnpm rebuild lightdrift-libraw
+```
 
 ### 🚀 Quick Verification
 
@@ -76,14 +151,6 @@ node -e "const LibRaw = require('lightdrift-libraw'); console.log('LibRaw versio
 
 Expected output: `LibRaw version: 0.21.4-Release`
 
-## Prerequisites (for building from source)
-
-- **Node.js** 14.0.0 or higher
-- **Python** 3.x (for node-gyp)
-- **Visual Studio Build Tools** (Windows)
-- **Xcode Command Line Tools** (macOS)
-- **build-essential** (Linux)
-
 ## Quick Start
 
 ```javascript
@@ -96,7 +163,34 @@ async function processRAW() {
     // Load RAW file
     await processor.loadFile("photo.cr2");
 
-    // 🆕 NEW: High-Performance JPEG Conversion
+    // 🆕 NEW: Buffer Creation API - Create images directly in memory
+    // Process the RAW data first
+    await processor.processImage();
+
+    // Create JPEG buffer without writing to file
+    const jpegBuffer = await processor.createJPEGBuffer({
+      quality: 85,
+      width: 1920,
+      progressive: true,
+    });
+
+    console.log(`JPEG buffer created: ${jpegBuffer.buffer.length} bytes`);
+
+    // Create multiple formats in parallel
+    const [pngResult, webpResult, thumbResult] = await Promise.all([
+      processor.createPNGBuffer({ width: 1200, compressionLevel: 6 }),
+      processor.createWebPBuffer({ quality: 80, width: 1200 }),
+      processor.createThumbnailJPEGBuffer({ maxSize: 300 }),
+    ]);
+
+    // Use buffers directly (e.g., send via HTTP, store in database, etc.)
+    // No temporary files needed!
+
+    console.log(`PNG: ${pngResult.buffer.length} bytes`);
+    console.log(`WebP: ${webpResult.buffer.length} bytes`);
+    console.log(`Thumbnail: ${thumbResult.buffer.length} bytes`);
+
+    // 🆕 NEW: High-Performance JPEG Conversion (Legacy method still available)
     // Convert RAW to JPEG with advanced options
     const jpegResult = await processor.convertToJPEG("output.jpg", {
       quality: 85, // JPEG quality (1-100)
@@ -226,7 +320,228 @@ This wrapper provides comprehensive LibRaw functionality with **50+ methods** ac
 
 **All methods are thoroughly tested and production-ready!**
 
-## 🆕 JPEG Conversion (New Feature)
+## 🆕 Buffer Creation API (New Feature)
+
+### Direct Memory Buffer Creation
+
+Create image buffers directly in memory without writing to files. Perfect for web applications, APIs, and streaming workflows.
+
+#### Available Buffer Methods
+
+```javascript
+const processor = new LibRaw();
+await processor.loadFile("photo.cr2");
+await processor.processImage();
+
+// Create different format buffers
+const jpegBuffer = await processor.createJPEGBuffer(options);
+const pngBuffer = await processor.createPNGBuffer(options);
+const webpBuffer = await processor.createWebPBuffer(options);
+const avifBuffer = await processor.createAVIFBuffer(options);
+const tiffBuffer = await processor.createTIFFBuffer(options);
+const ppmBuffer = await processor.createPPMBuffer();
+
+// Extract thumbnail buffer without full processing
+const processor2 = new LibRaw();
+await processor2.loadFile("photo.cr2");
+const thumbBuffer = await processor2.createThumbnailJPEGBuffer(options);
+```
+
+#### Buffer Creation Options
+
+##### JPEG Buffer Options
+
+```javascript
+{
+  quality: 85,          // 1-100 (default: 85)
+  width: 1200,         // Target width
+  height: 800,         // Target height
+  progressive: true,   // Progressive JPEG
+  fastMode: false,     // Speed vs quality trade-off
+  effort: 4           // Encoding effort 1-8
+}
+```
+
+##### PNG Buffer Options
+
+```javascript
+{
+  width: 1200,           // Target width
+  height: 800,          // Target height
+  compressionLevel: 6,  // 0-9 (default: 6)
+  fastMode: false       // Speed vs size trade-off
+}
+```
+
+##### WebP Buffer Options
+
+```javascript
+{
+  quality: 80,         // 1-100 (default: 80)
+  width: 1200,        // Target width
+  height: 800,        // Target height
+  lossless: false,    // Lossless mode
+  effort: 4,          // Encoding effort 0-6
+  fastMode: false     // Speed optimization
+}
+```
+
+##### AVIF Buffer Options
+
+```javascript
+{
+  quality: 50,         // 1-100 (default: 50)
+  width: 1200,        // Target width
+  height: 800,        // Target height
+  lossless: false,    // Lossless mode
+  effort: 4           // Encoding effort 0-9
+}
+```
+
+##### TIFF Buffer Options
+
+```javascript
+{
+  width: 1200,              // Target width
+  height: 800,             // Target height
+  compression: 'lzw',      // 'none', 'lzw', 'zip'
+  predictor: 'horizontal'  // Compression predictor
+}
+```
+
+##### Thumbnail Buffer Options
+
+```javascript
+{
+  maxSize: 300,       // Maximum dimension
+  quality: 85,        // JPEG quality 1-100
+  fastMode: false     // Speed optimization
+}
+```
+
+#### Usage Examples
+
+##### Web API Response
+
+```javascript
+app.get("/api/photo/:id/thumbnail", async (req, res) => {
+  const processor = new LibRaw();
+  try {
+    await processor.loadFile(`photos/${req.params.id}.cr2`);
+
+    const result = await processor.createThumbnailJPEGBuffer({
+      maxSize: 300,
+      quality: 85,
+    });
+
+    res.set({
+      "Content-Type": "image/jpeg",
+      "Content-Length": result.buffer.length,
+      "Cache-Control": "public, max-age=86400",
+    });
+
+    res.send(result.buffer);
+  } finally {
+    await processor.close();
+  }
+});
+```
+
+##### Multiple Format Generation
+
+```javascript
+async function generateFormats(rawFile, outputDir) {
+  const processor = new LibRaw();
+  await processor.loadFile(rawFile);
+  await processor.processImage();
+
+  // Generate all formats in parallel
+  const [jpeg, png, webp, avif] = await Promise.all([
+    processor.createJPEGBuffer({ quality: 85, width: 1920 }),
+    processor.createPNGBuffer({ width: 1200, compressionLevel: 6 }),
+    processor.createWebPBuffer({ quality: 80, width: 1920 }),
+    processor.createAVIFBuffer({ quality: 50, width: 1200 }),
+  ]);
+
+  // Save or process buffers as needed
+  fs.writeFileSync(`${outputDir}/image.jpg`, jpeg.buffer);
+  fs.writeFileSync(`${outputDir}/image.png`, png.buffer);
+  fs.writeFileSync(`${outputDir}/image.webp`, webp.buffer);
+  fs.writeFileSync(`${outputDir}/image.avif`, avif.buffer);
+
+  await processor.close();
+}
+```
+
+##### Streaming Upload
+
+```javascript
+async function uploadToCloud(rawFile) {
+  const processor = new LibRaw();
+  await processor.loadFile(rawFile);
+  await processor.processImage();
+
+  const webpResult = await processor.createWebPBuffer({
+    quality: 80,
+    width: 1600,
+  });
+
+  // Upload buffer directly to cloud storage
+  const uploadResult = await cloudStorage.upload(webpResult.buffer, {
+    contentType: "image/webp",
+    fileName: "processed-image.webp",
+  });
+
+  await processor.close();
+  return uploadResult;
+}
+```
+
+#### Buffer Result Structure
+
+All buffer creation methods return a consistent result structure:
+
+```javascript
+{
+  success: true,
+  buffer: Buffer,              // The created image buffer
+  metadata: {
+    format: "JPEG",            // Output format
+    outputDimensions: {        // Final image dimensions
+      width: 1920,
+      height: 1280
+    },
+    fileSize: {
+      original: 50331648,      // Original processed image size
+      compressed: 245760,      // Buffer size
+      compressionRatio: "204.8" // Compression ratio
+    },
+    processing: {
+      timeMs: "45.23",         // Processing time
+      throughputMBps: "15.4"   // Processing throughput
+    },
+    options: {                 // Applied options
+      quality: 85,
+      width: 1920,
+      // ... other options
+    }
+  }
+}
+```
+
+#### Performance Characteristics
+
+| Format     | Typical Size (1920px) | Creation Time | Compression Ratio |
+| ---------- | --------------------- | ------------- | ----------------- |
+| JPEG       | 80-400KB              | 200-500ms     | 50-200x           |
+| PNG        | 1-4MB                 | 400-800ms     | 12-50x            |
+| WebP       | 50-300KB              | 100-300ms     | 60-300x           |
+| AVIF       | 30-150KB              | 300-800ms     | 100-500x          |
+| TIFF (LZW) | 2-8MB                 | 100-200ms     | 6-25x             |
+| PPM        | 11-45MB               | 50-100ms      | 1x (uncompressed) |
+| Thumbnail  | 5-50KB                | 50-150ms      | 200-1000x         |
+
+## 🆕 JPEG Conversion (Enhanced Feature)
 
 ### High-Performance RAW to JPEG Conversion
 
@@ -698,6 +1013,9 @@ npm run test:quick
 # Comprehensive API coverage test
 npm run test:comprehensive
 
+# New buffer creation methods test
+npm run test:buffer-creation
+
 # Individual test suites
 npm run test:image-processing    # Image conversion and processing
 npm run test:format-conversion   # Output formats and color spaces
@@ -717,6 +1035,9 @@ npm run test:performance
 # Test all supported formats
 npm run test:formats
 
+# Buffer creation test suites
+npm run test:buffer-creation     # Comprehensive buffer method testing
+
 # Test with your own RAW file
 npm test path/to/your/photo.cr2
 ```
@@ -727,12 +1048,14 @@ The test suites provide comprehensive validation across:
 
 - ✅ **21 RAW files tested** (Canon CR3, Nikon NEF, Sony ARW, Fujifilm RAF, Panasonic RW2, Leica DNG)
 - ✅ **100% thumbnail extraction success rate**
+- ✅ **100% buffer creation success rate** (7 new buffer methods)
 - ✅ **6 camera brands validated** (Canon, Nikon, Sony, Fujifilm, Panasonic, Leica)
-- ✅ **Multiple output formats tested** (PPM, TIFF, JPEG thumbnails)
+- ✅ **Multiple output formats tested** (PPM, TIFF, JPEG, PNG, WebP, AVIF buffers)
 - ✅ **Color space conversion** (sRGB, Adobe RGB, Wide Gamut, ProPhoto, XYZ)
 - ✅ **Bit depth variations** (8-bit, 16-bit processing)
-- ✅ **Memory operations** (buffer management, image copying)
-- ✅ **Error handling** (invalid files, corrupted data)
+- ✅ **Memory operations** (buffer management, image copying, direct buffer creation)
+- ✅ **Error handling** (invalid files, corrupted data, parameter validation)
+- ✅ **Performance benchmarking** (buffer creation speed and compression ratios)
 
 ## Thumbnail Extraction
 
@@ -984,8 +1307,8 @@ npm run build  # Rebuilds and copies DLL
 
 **✅ Published to NPM Registry!**
 
-- **Package**: [`lightdrift-libraw@1.0.0-alpha.1`](https://www.npmjs.com/package/lightdrift-libraw)
-- **Published**: August 23, 2025
+- **Package**: [`lightdrift-libraw@1.0.0-alpha.3`](https://www.npmjs.com/package/lightdrift-libraw)
+- **Published**: August 30, 2025
 - **Total Files**: 487 files (4.0 MB package, 18.1 MB unpacked)
 - **Registry**: [npmjs.com](https://www.npmjs.com/package/lightdrift-libraw)
 

package/binding.gyp

@@ -7,31 +7,50 @@
         "src/libraw_wrapper.cpp"
       ],
       "include_dirs": [
-        "<!@(node -p \"require('node-addon-api').include\")",
-        "deps/LibRaw-Win64/LibRaw-0.21.4/libraw",
-        "deps/LibRaw-Win64/LibRaw-0.21.4"
-      ],
-      "libraries": [
-        "<(module_root_dir)/deps/LibRaw-Win64/LibRaw-0.21.4/lib/libraw.lib"
+        "<!@(node -p \"require('node-addon-api').include\")"
       ],
       "defines": [
         "NAPI_DISABLE_CPP_EXCEPTIONS"
       ],
       "cflags!": [ "-fno-exceptions" ],
       "cflags_cc!": [ "-fno-exceptions" ],
-      "msvs_settings": {
-        "VCCLCompilerTool": {
-          "ExceptionHandling": 1,
-          "RuntimeLibrary": 2
-        }
-      },
-      "copies": [
-        {
-          "destination": "<(module_root_dir)/build/Release/",
-          "files": [
-            "<(module_root_dir)/deps/LibRaw-Win64/LibRaw-0.21.4/bin/libraw.dll"
+      "conditions": [
+        ['OS=="win"', {
+          "include_dirs": [
+            "deps/LibRaw-Win64/LibRaw-0.21.4/libraw",
+            "deps/LibRaw-Win64/LibRaw-0.21.4"
+          ],
+          "libraries": [
+            "<(module_root_dir)/deps/LibRaw-Win64/LibRaw-0.21.4/lib/libraw.lib"
+          ],
+          "msvs_settings": {
+            "VCCLCompilerTool": {
+              "ExceptionHandling": 1,
+              "RuntimeLibrary": 2
+            }
+          },
+          "copies": [
+            {
+              "destination": "<(module_root_dir)/build/Release/",
+              "files": [
+                "<(module_root_dir)/deps/LibRaw-Win64/LibRaw-0.21.4/bin/libraw.dll"
+              ]
+            }
           ]
-        }
+        }],
+        ['OS=="linux"', {
+          "libraries": ["-lraw"],
+          "cflags": ["-fexceptions"],
+          "cflags_cc": ["-fexceptions"]
+        }],
+        ['OS=="mac"', {
+          "libraries": ["-lraw"],
+          "xcode_settings": {
+            "GCC_ENABLE_CPP_EXCEPTIONS": "YES",
+            "CLANG_CXX_LIBRARY": "libc++",
+            "MACOSX_DEPLOYMENT_TARGET": "10.9"
+          }
+        }]
       ]
     }
   ]