scad-to-png/UPDATING.md

Updating OpenSCAD Dependencies

This guide explains how to update the OpenSCAD WebAssembly files used by scad-to-png.

Current Version

The project currently uses OpenSCAD WASM files from:

• Source: https://files.openscad.org/playground/
• Version: OpenSCAD-2025.03.25.wasm24456-WebAssembly-web.zip
• Location: openscad-web/ directory

Checking for Updates

1. OpenSCAD Playground Builds: Visit https://files.openscad.org/playground/ to see available WebAssembly builds.

2. OpenSCAD Development Snapshots: Check https://openscad.org/downloads.html#snapshots for the latest development builds.

3. GitHub Releases: Monitor https://github.com/openscad/openscad-wasm/releases for official releases.

Update Process

Step 1: Download the Latest Web Build

# Navigate to project directory
cd /path/to/scad-to-png

# Download the latest web build (adjust URL as needed)
curl -L -o openscad-web-new.zip "https://files.openscad.org/playground/OpenSCAD-YYYY.MM.DD.wasmXXXXX-WebAssembly-web.zip"

Important: Always download the web version, not the node version. The file should have -WebAssembly-web.zip in its name.

Step 2: Backup Current Version

# Backup existing files
mv openscad-web openscad-web-backup

Step 3: Extract New Version

# Extract new files
unzip openscad-web-new.zip -d openscad-web

# Verify contents
ls -la openscad-web/

You should see:

• openscad.js - The JavaScript wrapper
• openscad.wasm - The WebAssembly binary

Step 4: Test the Update

# Run test
npm test

# Run examples
npm run example:box
npm run example:gear

# Test with your own files
./scad-to-png your-file.scad

Step 5: Verify Compatibility

Check for:

1. Successful initialization: No "GUI mode" errors
2. STL generation: Files are created correctly
3. Rendering: PNG images are generated properly

Step 6: Update Documentation

If the update is successful:

1. Update this file with the new version info
2. Update CLAUDE.md if there are any API changes
3. Commit the changes

Rollback Process

If issues occur:

# Remove problematic version
rm -rf openscad-web

# Restore backup
mv openscad-web-backup openscad-web

# Test to ensure it works
npm test

Version History

Date	Version	Notes
2024-03-25	OpenSCAD-2025.03.25.wasm24456-WebAssembly-web	Initial version used

Troubleshooting Updates

Common Issues

1. "Requested GUI mode but can't open display!"

   • You downloaded the node version instead of the web version
   • Solution: Download the -WebAssembly-web.zip file

2. Module loading errors

   • The API might have changed
   • Check if initialization parameters need updating in openscad-wrapper.mjs

3. Missing features

   • New versions might require additional configuration
   • Check the OpenSCAD WASM changelog for breaking changes

Testing Checklist

• Basic shapes (cube, sphere, cylinder)
• Boolean operations (difference, union, intersection)
• Complex models (gears, threads)
• Large models (performance test)
• All 8 view angles generate correctly
• Error handling still works

Automated Update Script

Save this as update-openscad.sh:

#!/bin/bash

# Configuration
PLAYGROUND_URL="https://files.openscad.org/playground/"
BACKUP_DIR="openscad-web-backup-$(date +%Y%m%d)"

echo "Checking for latest OpenSCAD WASM build..."

# Get latest web build URL (requires parsing HTML)
# This is a simplified example - you'd need to parse the actual HTML
LATEST_URL="$PLAYGROUND_URL/OpenSCAD-2025.03.25.wasm24456-WebAssembly-web.zip"

echo "Downloading from: $LATEST_URL"

# Backup current version
if [ -d "openscad-web" ]; then
    echo "Backing up current version to $BACKUP_DIR"
    mv openscad-web "$BACKUP_DIR"
fi

# Download and extract
curl -L -o openscad-web-new.zip "$LATEST_URL"
unzip openscad-web-new.zip -d openscad-web

# Test
echo "Running tests..."
npm test

if [ $? -eq 0 ]; then
    echo "Update successful!"
    rm openscad-web-new.zip
else
    echo "Tests failed, rolling back..."
    rm -rf openscad-web
    mv "$BACKUP_DIR" openscad-web
    exit 1
fi

Alternative Sources

1. Build from source: Follow instructions at https://github.com/openscad/openscad-wasm
2. OpenSCAD Playground: The playground might have newer experimental builds
3. Custom builds: You can build with specific features enabled/disabled

Notes for Maintainers

• Always test with the test.scad file first
• Keep at least one backup of a known working version
• Document any API changes in CLAUDE.md
• Update the version history table after successful updates