freecad-preview-extractor 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Andrew Kondratev
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,143 @@
+# FreeCAD preview extractor
+
+[![Tests and Lint](https://github.com/andruhon/freecad-preview-extractor/actions/workflows/unit-tests.yml/badge.svg)](https://github.com/andruhon/freecad-preview-extractor/actions/workflows/unit-tests.yml) [![Integration Tests](https://github.com/andruhon/freecad-preview-extractor/actions/workflows/integration-tests.yml/badge.svg?event=push)](https://github.com/andruhon/freecad-preview-extractor/actions/workflows/integration-tests.yml)
+
+A CLI tool for extracting and generating preview thumbnails from FreeCAD files.
+
+Preview is extracted for each `FILENAME.FCStd` file as `FILENAME-preview.png`
+
+## Features
+
+- **Extract existing previews**: Quickly extract embedded thumbnail images from `.FCStd` files
+- **Generate new previews**: Use FreeCAD to create fresh previews with isometric view and fit-to-view
+- **Batch processing**: Process all FreeCAD files in a directory recursively
+- **Single file mode**: Extract or generate previews for specific files
+- **Ignore patterns**: Use an ignore config file (like `.gitignore`) to exclude specific files from batch processing
+
+## Installation
+```bash
+git clone https://github.com/andruhon/freecad-preview-extractor.git
+cd ./freecad-preview-extractor
+npm ci
+sudo npm install -g ./
+```
+
+## Usage
+
+### Extract existing previews from all FreeCAD files
+```bash
+fcxtc
+```
+
+or 
+
+```bash
+freecad-preview-extractor
+```
+
+### Extract preview from a specific file
+```bash
+fcxtc filename.FCStd
+```
+
+### Generate preview with FreeCAD before extraction (requires FreeCAD and desktop environment)
+
+Adding `--fit` argument will trigger `src/isofit.FCMacro` FreeCAD macros for each file,
+the macros sets model to the isometric view, does "fit into view", and saves the file.
+
+```bash
+fcxtc --fit
+```
+
+or for a specific file:
+
+```bash
+fcxtc --fit filename.FCStd
+```
+
+### Ignore specific files during batch processing
+```bash
+fcxtc --ignore-config .myignore
+```
+
+Create an ignore file (e.g., `.myignore`) with patterns to exclude:
+```
+# Ignore all files in the archived directory
+archived/*.FCStd
+
+# Ignore specific files
+test-model.FCStd
+
+# Ignore files with specific naming pattern
+*backup*.FCStd
+```
+
+The `--fit` option will:
+1. Open each FreeCAD file with FreeCAD
+2. Run the `isofit.FCMacro` macro to set Isometric View and Fit All
+3. Save the file with the updated preview
+4. Extract the preview image as usual
+
+The `--ignore-config` option allows you to exclude specific files from batch processing using pattern matching similar to `.gitignore`:
+- Supports wildcards (`*`, `?`)
+- Supports `**` for recursive matching
+- Supports character ranges (`[abc]`)
+- Lines starting with `#` are treated as comments
+- Empty lines are ignored
+
+**Note:** The `--fit` option requires:
+- FreeCAD installed and available in your system PATH
+- A desktop environment / X server (cannot run headless)
+- UI access for FreeCAD to render the view
+
+**Note:** The `--ignore-config` option only works in batch processing mode (when no specific file is provided). It is ignored in single-file mode.
+
+## Testing
+
+The project has comprehensive test suites covering unit logic and integration scenarios.
+
+### Unit Tests
+Run unit tests for core logic (path handling, ignore patterns, etc.):
+```bash
+npm test
+```
+
+### Integration Tests
+Integration tests are split into two categories based on whether they require a local FreeCAD installation.
+
+**1. Standard Integration Tests (No FreeCAD required)**
+These tests check file extraction, CLI behavior, and ignore patterns without invoking FreeCAD.
+```bash
+npm run test:integration-no-freecad
+```
+
+**2. Full Integration Tests (FreeCAD required)**
+These tests involve the `--fit` flag and spawning the FreeCAD process. They require FreeCAD to be installed and available in the system PATH.
+```bash
+npm run test:integration
+```
+
+**Note for Developers:**
+- Tests ending in `.test.js` do not require FreeCAD.
+- Tests ending in `.test-freecad.js` require FreeCAD.
+
+## Utilities
+
+The project exports utility functions that can be used programmatically:
+
+- `loadIgnoreConfig(filePath, cwd)` - Load ignore patterns from a file
+- `filterIgnoredFiles(filePaths, rootDir, patterns, enabled)` - Filter files based on patterns
+- `shouldIgnoreFile(filePath, rootDir, patterns, enabled)` - Check if a single file should be ignored
+
+## Project Files
+
+Key files of the project (not including all files):
+
+- `src/index.js` - Main CLI entry point
+- `src/extract-png-from-fcstd.js` - Thumbnail extraction logic
+- `src/isofit.FCMacro` - FreeCAD macro for isometric view and fit (used by `--fit` option)
+- `tests/` - Unit tests for ignore functionality
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "freecad-preview-extractor",
+  "version": "0.1.0",
+  "description": "Script extracting freecad previews",
+  "keywords": [
+    "FreeCAD"
+  ],
+  "license": "MIT",
+  "author": "Andrew Kondratev",
+  "type": "module",
+  "main": "src/index.js",
+  "bin": {
+    "fcxtc": "src/index.js",
+    "freecad-preview-extractor": "src/index.js"
+  },
+  "scripts": {
+    "test": "node --test --test-concurrency=1 tests/*.js",
+    "test:integration": "node --test --test-concurrency=1 integration-tests/*.js",
+    "test:integration-no-freecad": "node --test --test-concurrency=1 integration-tests/*.test.js"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/andruhon/freecad-preview-extractor.git"
+  },
+  "bugs": {
+    "url": "https://github.com/andruhon/freecad-preview-extractor/issues"
+  },
+  "homepage": "https://github.com/andruhon/freecad-preview-extractor#readme",
+  "files": [
+    "src",
+    "LICENSE",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=24.0.0"
+  },
+  "dependencies": {
+    "glob": "^13.0.0",
+    "yauzl": "^3.2.0",
+    "minimatch": "^10.1.1"
+  }
+}

package/src/extract-png-from-fcstd.js

@@ -0,0 +1,120 @@
+import fs from 'fs';
+import path from 'path';
+import yauzl from 'yauzl';
+
+// Constants
+const THUMBNAIL_PATH = 'thumbnails/Thumbnail.png';
+
+// Helper to promisify yauzl's zip opening
+function openZipPromise(filename) {
+  return new Promise((resolve, reject) => {
+    yauzl.open(filename, { lazyEntries: true }, (err, zipfile) => {
+      if (err) return reject(err);
+      resolve(zipfile);
+    });
+  });
+}
+
+/**
+ * Extract thumbnail from a FreeCAD file
+ * @param {string} zipFilePath - Path to the .FCStd file
+ * @param {string} outputPath - Path where to save the extracted PNG
+ * @returns {Promise<boolean>} True if thumbnail was found and extracted
+ */
+export async function extractThumbnailFromFCStd(zipFilePath, outputPath) {
+  const zipfile = await openZipPromise(zipFilePath);
+  let foundThumbnail = false;
+  
+  return new Promise((resolve, reject) => {
+    zipfile.on('entry', (entry) => {
+      // Look specifically for thumbnails/Thumbnail.png
+      if (entry.fileName === THUMBNAIL_PATH) {
+        console.log(`✅ Found Thumbnail in ${path.basename(zipFilePath)}`);
+        foundThumbnail = true;
+        
+        zipfile.openReadStream(entry, (err, readStream) => {
+          if (err) {
+            zipfile.close();
+            return reject(err);
+          }
+          
+          // Create directory if it doesn't exist
+          const outputDir = path.dirname(outputPath);
+          if (!fs.existsSync(outputDir)) {
+            fs.mkdirSync(outputDir, { recursive: true });
+          }
+          
+          const writeStream = fs.createWriteStream(outputPath);
+          readStream.pipe(writeStream);
+          
+          // Handle readStream errors to prevent resource leaks
+          readStream.on('error', (err) => {
+            zipfile.close();
+            reject(err);
+          });
+          
+          writeStream.on('finish', () => {
+            console.log(`✅ Extracted thumbnail to: ${outputPath}`);
+            zipfile.close();
+            resolve(true);
+          });
+          
+          writeStream.on('error', (err) => {
+            zipfile.close();
+            reject(err);
+          });
+        });
+      } else {
+        zipfile.readEntry();
+      }
+    });
+    
+    zipfile.on('end', () => {
+      if (!foundThumbnail) {
+        console.log(`⚠️ No thumbnail found in ${path.basename(zipFilePath)}`);
+        resolve(false);
+      }
+    });
+    
+    zipfile.on('error', (err) => {
+      reject(err);
+    });
+    
+    zipfile.readEntry();
+  });
+}
+
+/**
+ * Process a single .FCStd file to extract its preview
+ * @param {string} filePath - Path to the .FCStd file
+ * @returns {Promise<boolean>} True if processing was successful
+ */
+export async function processSingleFile(filePath) {
+  try {
+    // Verify file exists
+    if (!fs.existsSync(filePath)) {
+      console.log(`❌ File not found: ${filePath}`);
+      return false;
+    }
+    
+    // Verify it's a .FCStd file
+    const ext = path.extname(filePath).toLowerCase();
+    if (ext !== '.fcstd') {
+      console.log(`❌ Not a .FCStd file: ${filePath}`);
+      return false;
+    }
+    
+    // Prepare output path - same directory, same name but with .png extension
+    const dir = path.dirname(filePath);
+    const baseName = path.basename(filePath, path.extname(filePath));
+    const pngPath = path.join(dir, `${baseName}-preview.png`);
+    
+    // Try to extract thumbnail from the file
+    await extractThumbnailFromFCStd(filePath, pngPath);
+    return true;
+    
+  } catch (err) {
+    console.log(`❌ Error processing ${filePath}: ${err.message}`);
+    return false;
+  }
+}

package/src/ignore-utils.js

@@ -0,0 +1,97 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { minimatch } from 'minimatch';
+import path from 'node:path';
+
+/**
+ * Load ignore patterns from a file
+ * @param {string} ignoreFilePath - Path to the ignore file
+ * @returns {string[]} Array of ignore patterns
+ */
+export function loadIgnorePatterns(ignoreFilePath) {
+  if (!existsSync(ignoreFilePath)) {
+    // Return empty array if file doesn't exist
+    return [];
+  }
+
+  try {
+    const content = readFileSync(ignoreFilePath, 'utf-8');
+    const patterns = content
+      .split('\n')
+      .map((line) => line.trim())
+      .filter((line) => line.length > 0 && !line.startsWith('#'));
+
+    return patterns;
+  } catch (error) {
+    console.warn(`⚠️ Warning: Could not read ignore file ${ignoreFilePath}: ${error.message}`);
+    return [];
+  }
+}
+
+/**
+ * Check if a file path should be ignored based on patterns
+ * @param {string} filePath - The file path to check
+ * @param {string} rootDir - The root directory for relative pattern matching
+ * @param {string[] | undefined} customPatterns - Optional custom patterns to use
+ * @param {boolean} enabled - Whether ignore functionality is enabled
+ * @returns {boolean} True if the file should be ignored, false otherwise
+ */
+export function shouldIgnoreFile(filePath, rootDir, customPatterns = undefined, enabled = true) {
+  if (!enabled) {
+    return false;
+  }
+
+  const patterns = customPatterns ?? [];
+
+  if (patterns.length === 0) {
+    return false;
+  }
+
+  // Convert file path to relative path for pattern matching
+  const relativePath = path.relative(rootDir, filePath);
+
+  // Check if any pattern matches
+  for (const pattern of patterns) {
+    try {
+      if (minimatch(relativePath, pattern, { dot: true })) {
+        return true;
+      }
+    } catch (error) {
+      console.warn(`⚠️ Warning: Error matching pattern '${pattern}': ${error.message}`);
+    }
+  }
+
+  return false;
+}
+
+/**
+ * Filter an array of file paths based on ignore patterns
+ * @param {string[]} filePaths - Array of file paths to filter
+ * @param {string} rootDir - The root directory for relative pattern matching
+ * @param {string[] | undefined} customPatterns - Optional custom patterns to use
+ * @param {boolean} enabled - Whether ignore functionality is enabled
+ * @returns {string[]} Filtered array of file paths that should not be ignored
+ */
+export function filterIgnoredFiles(filePaths, rootDir, customPatterns = undefined, enabled = true) {
+  if (!enabled) {
+    return filePaths;
+  }
+
+  return filePaths.filter((filePath) => !shouldIgnoreFile(filePath, rootDir, customPatterns, enabled));
+}
+
+/**
+ * Load ignore patterns and resolve to absolute paths if needed
+ * @param {string} ignoreFilePath - Path to the ignore config file
+ * @param {string} cwd - Current working directory for relative resolution
+ * @returns {string[]} Array of patterns
+ */
+export function loadIgnoreConfig(ignoreFilePath, cwd = process.cwd()) {
+  if (!existsSync(ignoreFilePath)) {
+    console.warn(`⚠️ Warning: Ignore config file not found: ${ignoreFilePath}`);
+    return [];
+  }
+
+  const patterns = loadIgnorePatterns(ignoreFilePath);
+  console.log(`🔍 Loaded ${patterns.length} ignore patterns from ${ignoreFilePath}`);
+  return patterns;
+}

package/src/index.js

@@ -0,0 +1,223 @@
+#!/usr/bin/env node
+import path from "path";
+import { fileURLToPath } from "url";
+import { spawn } from "child_process";
+import { glob } from "glob";
+import {
+  processSingleFile,
+  extractThumbnailFromFCStd,
+} from "./extract-png-from-fcstd.js";
+import { loadIgnoreConfig, filterIgnoredFiles } from "./ignore-utils.js";
+import { readFileSync } from "fs";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
+// Get root directory for pattern matching
+function getRootDir(cwd = process.cwd()) {
+  return cwd;
+}
+
+// Run FreeCAD with isofit macro to generate preview
+async function runFreeCADIsofit(fcstdFile) {
+  const macroPath = path.join(__dirname, "isofit.FCMacro");
+
+  return new Promise((resolve, reject) => {
+    console.log(
+      `🔧 Running FreeCAD with Isometric, Fit All macro on ${fcstdFile}...`,
+    );
+
+    const freecad = spawn("freecad", [fcstdFile, macroPath]);
+
+    freecad.stdout.on("data", (data) => {
+      // Log FreeCAD output if needed for debugging
+      // console.log(`FreeCAD: ${data}`);
+    });
+
+    freecad.stderr.on("data", (data) => {
+      // Log errors but don't fail immediately
+      // console.error(`FreeCAD stderr: ${data}`);
+    });
+
+    freecad.on("close", (code) => {
+      if (code === 0) {
+        console.log(`✅ FreeCAD processing complete for ${fcstdFile}`);
+        resolve();
+      } else {
+        reject(new Error(`FreeCAD exited with code ${code}`));
+      }
+    });
+
+    freecad.on("error", (err) => {
+      reject(
+        new Error(
+          `Failed to start FreeCAD: ${err.message}. Make sure FreeCAD is installed and available in PATH.`,
+        ),
+      );
+    });
+  });
+}
+
+// Process all .FCStd files in current directory and subdirectories
+async function processAllFiles(runFit = false, ignoreConfig = null) {
+  try {
+    // Find all .FCStd files in the current directory and subdirectories (case insensitive)
+    let fcstdFiles = await glob("**/*.FCStd", { nocase: true });
+
+    if (fcstdFiles.length === 0) {
+      console.log("❌ No .FCStd files found");
+      return;
+    }
+
+    // Apply ignore patterns if config is provided
+    let ignorePatterns = [];
+    if (ignoreConfig) {
+      const rootDir = getRootDir();
+      ignorePatterns = loadIgnoreConfig(ignoreConfig, rootDir);
+      if (ignorePatterns.length > 0) {
+        const originalCount = fcstdFiles.length;
+        fcstdFiles = filterIgnoredFiles(fcstdFiles, rootDir, ignorePatterns, true);
+        const ignoredCount = originalCount - fcstdFiles.length;
+        if (ignoredCount > 0) {
+          console.log(`🔍 Ignored ${ignoredCount} files based on ${ignoreConfig}`);
+        }
+      }
+    }
+
+    if (fcstdFiles.length === 0) {
+      console.log("❌ All files were filtered out by ignore patterns");
+      return;
+    }
+
+    console.log(`✅ Found ${fcstdFiles.length} .FCStd files to check`);
+
+    let processedCount = 0;
+    let successCount = 0;
+    let failureCount = 0;
+
+    for (const file of fcstdFiles) {
+      try {
+        // If --fit flag is set, run FreeCAD with isofit macro first
+        if (runFit) {
+          await runFreeCADIsofit(file);
+        }
+
+        // Prepare output path - same directory, same name but with .png extension
+        const dir = path.dirname(file);
+        const baseName = path.basename(file, path.extname(file));
+        const pngPath = path.join(dir, `${baseName}-preview.png`);
+
+        // Try to extract thumbnail from the file
+        await extractThumbnailFromFCStd(file, pngPath);
+        successCount++;
+      } catch (err) {
+        console.log(`❌ Error processing ${file}: ${err.message}`);
+        failureCount++;
+      }
+      processedCount++;
+      console.log(`📊 Progress: ${processedCount}/${fcstdFiles.length} (${successCount} succeeded, ${failureCount} failed)`);
+    }
+
+    if (failureCount > 0) {
+      console.log(`⚠️ Processing completed with ${failureCount} failures out of ${processedCount} files`);
+      return false; // Indicate partial failure
+    } else {
+      console.log("✅ Processing complete - all files processed successfully");
+      return true; // Indicate success
+    }
+  } catch (err) {
+    console.error("❌ Error:", err);
+    return false; // Indicate failure
+  }
+}
+
+// Main entry point
+async function main() {
+  const args = process.argv.slice(2);
+
+  // Check for --version or --help flags
+  if (args.includes("--version") || args.includes("-v")) {
+    const pkg = JSON.parse(readFileSync(new URL("../package.json", import.meta.url)));
+    console.log(pkg.version);
+    process.exit(0);
+  }
+
+  if (args.includes("--help") || args.includes("-h")) {
+    console.log(`FreeCAD Preview Extractor v0.0.2-alpha
+
+Usage: fcxtc [options] [file]
+
+Options:
+  --fit               Run FreeCAD with isometric fit macro before extracting
+  --ignore-config     Path to ignore config file (e.g., .fcignore)
+  --version, -v       Show version number
+  --help, -h          Show this help message
+
+Examples:
+  fcxtc               Extract previews from all .FCStd files in current directory
+  fcxtc myfile.FCStd  Extract preview from specific file
+  fcxtc --fit         Run isometric fit macro on all files before extracting
+  fcxtc --ignore-config .fcignore  Use ignore config file
+  fcxtc --fit --ignore-config .fcignore  Combine flags`);
+    process.exit(0);
+  }
+
+  // Check for --fit flag
+  const fitIndex = args.indexOf("--fit");
+  const runFit = fitIndex !== -1;
+
+  // Check for --ignore-config flag
+  let ignoreConfig = null;
+  const ignoreConfigIndex = args.indexOf("--ignore-config");
+  if (ignoreConfigIndex !== -1 && ignoreConfigIndex + 1 < args.length) {
+    ignoreConfig = args[ignoreConfigIndex + 1];
+  }
+
+  // Filter out --fit, --ignore-config and its value to get file arguments
+  const fileArgs = args.filter((arg, index) => {
+    if (arg === "--fit") return false;
+    if (arg === "--ignore-config") return false;
+    if (ignoreConfigIndex !== -1 && index === ignoreConfigIndex + 1) return false;
+    return true;
+  });
+
+  if (fileArgs.length === 0) {
+    // No arguments - process all files
+    if (runFit) {
+      console.log(
+        "🔍 Running FreeCAD isofit and extracting images from all FreeCAD files in current directory...",
+      );
+    } else {
+      console.log(
+        "🔍 Extracting images from all FreeCAD files in current directory...",
+      );
+    }
+    if (ignoreConfig) {
+      console.log(`🔍 Using ignore config: ${ignoreConfig}`);
+    }
+    const success = await processAllFiles(runFit, ignoreConfig);
+    if (!success) {
+      process.exit(1); // Exit with error code if batch processing failed
+    }
+  } else {
+    // Process specific file(s)
+    const file = fileArgs[0];
+
+    // For single file mode, ignore config is not applied
+    if (runFit) {
+      console.log(`🔧 Running FreeCAD isofit on: ${file}`);
+      await runFreeCADIsofit(file);
+    }
+
+    console.log(`🔍 Extracting image from: ${file}`);
+    await processSingleFile(file);
+  }
+}
+
+export { processAllFiles, runFreeCADIsofit };
+export { loadIgnoreConfig, filterIgnoredFiles } from "./ignore-utils.js";
+
+// Run the script
+main().catch((err) => {
+  console.error("❌ Fatal error:", err);
+  process.exit(1);
+});

package/src/isofit.FCMacro

@@ -0,0 +1,18 @@
+# -*- coding: utf-8 -*-
+
+# Macro Begin: isofit.FCMacro +++++++++++++++++++++++++++++++++++++++++++++++++
+import FreeCAD
+
+try:
+    view = Gui.activeDocument().activeView()
+    view.setAnimationEnabled(False)
+    view.viewIsometric()
+    Gui.SendMsgToActiveView("ViewFit")
+    Gui.updateGui()
+    Gui.SendMsgToActiveView("Save")
+    Gui.getMainWindow().close()
+except Exception as e:
+    print("Error in isofit macro: {}".format(e))
+    Gui.getMainWindow().close()
+
+# Macro End: isofit.FCMacro +++++++++++++++++++++++++++++++++++++++++++++++++