v0.4.0: Nearest-Neighbor Pixel Scaling, True-Black LED Post-Processing & Agent Skill Enhancements

What's New in v0.4.0

👾 Nearest-Neighbor Sampling Mode (--nearest / --sampling-mode)

• Crisp Pixel Art Scaling: Added SamplingMode (BILINEAR default, NEAREST_NEIGHBOR) across PixooImage, ImageProcessor, GifDecoder, PixooClient, and pixoo-cli (#2).
• Zero Anti-Aliasing Blur: Preserves razor-sharp 1px edges and exact palette colors when downscaling high-resolution AI-generated sprite sheets or upscaling 16×16 / 32×32 retro sprites to the 64×64 matrix.
• CLI Flags: Added -n, --nearest and --sampling-mode <bilinear|nearest> to both pixoo-cli image and pixoo-cli gif.

💡 Physical LED Matrix Post-Processor (--led-optimize / LedPostProcessor)

• True-Black (#000000) Clamping: Added LedPostProcessor to clamp near-black dark/shadow background pixels (max(R, G, B) <= blackThreshold, default 15) to exact #000000 so unlit LEDs physically power off instead of firing at minimum PWM duty cycle and causing gray diffuser haze (#3).
• Semi-Transparent Alpha Compositing: Automatically composites semi-transparent pixels over black before applying the True-Black threshold.
• Pure-Java Diffuser Saturation Boost: Optional zero-allocation, AWT-free HSV saturation boost (saturationBoost) to help colors punch through the matte diffuser while preserving GraalVM native-image compatibility on macOS.
• CLI Flags: Added -o, --led-optimize and --black-threshold <0..255> (which automatically enables LED optimization) to pixoo-cli image and pixoo-cli gif (including remote --url GIF streams).

🧩 Unified Java API Overloads

• Added complete (ScaleMode, SamplingMode, LedPostProcessor) overload combinations across PixooClient.sendImage(PixooImage/BufferedImage/Path) and PixooClient.sendGif(InputStream/Path/URI) + sendGifUrl(String).

🤖 Enhanced pixoo64 Agent Skill & AI Prompt Blueprints

• Physical LED Optical & Temporal Bible (skills/pixoo64/references/pixoo64-led-bible.md): Documented the True-Black (#000000) LED-off law, diffuser saturation rules (HSV Saturation >= 0.65), 3-step neon bloom ramp, 32-frame hardware ceiling, and static background locking (#1).
• Empirical Animation Archetypes (skills/pixoo64/references/discovered-patterns.md): Added scenic-loop, character-sprite, abstract-shader, widget-hud, and typography-marquee design patterns.
• Gemini Nano Banana Prompt Templates (skills/pixoo64/references/nano-banana-prompts.md): Added ready-to-use prompt blueprints and ffmpeg 2×2 sprite-sheet slicing workflows.
• Curated LED Palettes (skills/pixoo64/references/palettes.json): Added 9 high-saturation, True-Black-anchored palettes tailored for the 64×64 matrix.

🛠️ Build & Developer Experience

• Added AGENTS.md coding agent guide at the repository root.
• Added Maven Wrapper (./mvnw) configured with Maven 3.10.0.

🙏 Contributors

Special thanks to @alexismp for contributing PRs #1, #2, and #3!

---

📦 Pre-compiled Native Binaries

Instantaneous startup (<5ms) without requiring a JVM:

• macOS (Apple Silicon / aarch64): pixoo-cli-macos-aarch64.zip
• Linux (x86_64): pixoo-cli-linux-amd64.zip
• Windows (x86_64): pixoo-cli-windows-amd64.zip

v0.3.0: Pure-Java Image Engine, Cloud Gallery & Watchfaces, Weather, Hardware Tools

What's New in v0.3.0

🎨 Pure-Java Image Engine (Zero AWT / java.desktop dependencies)

• AWT Independence: Replaced all java.desktop/AWT image dependencies with a custom, lightweight PixooImage ARGB buffer supporting bilinear scaling, letterboxing, and cropping.
• Built-in Pure-Java Decoders:
  • PNG: Decoded via lightweight pngj.
  • Animated GIF: Built-in LZW decoder with full support for local/global color tables, transparent index handling, disposal methods, and variable frame delays.
  • BMP: Native decoder for 24-bit and 32-bit uncompressed bitmaps.
• Pure-Java GIF89a Multi-Frame Encoder (GifEncoder): Built-in multi-frame GIF encoder with color quantization, adaptive palettes, and LZW compression (verified with 100% roundtrip accuracy).
• Native Image on Apple Silicon: Completely fixes GraalVM native binary compilation on macOS (macos-14 / arm64) by eliminating libawt / libawt_lwawt library links.

🖼️ Enhanced Image & GIF Options (--crop and --scale-mode)

• Added -c, --crop option to crop images to 64x64 or custom bounds.
• Added -s, --scale-mode <fit|stretch> option to select between aspect-ratio preserving letterboxing (fit) or matrix-filling stretch (stretch).
• Fast path in PixooImage.resizeAndFit for native 64x64 inputs to avoid unnecessary resampling.

🌐 Client-Side Remote GIF Streaming

• Remote GIFs (pixoo-cli gif https://...) are now downloaded, decoded, scaled, and streamed frame-by-frame client-side via Draw/SendHttpGif.
• Eliminates ESP32 memory exhaustion and device reboots when fetching large or non-optimized GIFs over HTTP.

☁️ Divoom Cloud Gallery, Artist Profiles & Watch Faces

• Community Gallery Search: Search and browse animations with sorting options (pixoo-cli cloud search).
• Watch Face Store: Browse community clock dials and watch faces (pixoo-cli cloud clock-faces).
• Artist Profiles: Query public creations and profile statistics (pixoo-cli cloud artist).
• Strict 64x64 Filtering: Automatically filters cloud queries to 64x64 pixel matrices to prevent matrix distortion.
• Cloud Timeout: Increased HTTP client timeout to 60s for improved stability on slower connections.

🧩 Divoom Binary Asset Decoder (.bin)

• Added DivoomAssetDecoder capable of unpacking Divoom's proprietary binary animations (macroblocks, compressed palette tables) into PixooImage frames and standard GIFs.

⏱️ Expanded Hardware Tools Engine

• Sleep Timer: Schedule automatic display shutdown from 1 to 120 minutes (pixoo-cli tool sleep-timer).
• Pomodoro Timer: Configure focus and rest cycles (pixoo-cli tool pomodoro).
• Multi-Alarm Clock: Set, inspect, enable, and delete up to 8 independent hardware alarms with weekday recurrence and alarm tone styles (pixoo-cli tool alarm).

🌤️ Zero-Auth Divoom Weather Client

• Added DivoomWeatherClient and pixoo-cli weather to retrieve real-time weather conditions and forecasts via latitude and longitude without requiring API keys.

📚 Documentation & Protocol Specifications

• Cleaned up SPECIFICATION.md into a strictly language-agnostic HTTP protocol reference for Pixoo 64.
• Updated README.md, RECIPES.md, and the pixoo64 agent skill.
• Reflected all new records and CLI models in GraalVM reflect-config.json.

---

📦 Pre-compiled Native Binaries

Instantaneous startup (<5ms) without requiring a JVM:

• macOS (Apple Silicon / aarch64): pixoo-cli-macos-aarch64.zip
• Linux (x86_64): pixoo-cli-linux-amd64.zip
• Windows (x86_64): pixoo-cli-windows-amd64.zip

v0.2.0: Divoom Cloud API, Hardware Tools & Protocol Enhancements

What's New in v0.2.0

☁️ Divoom Cloud API & Persistent Custom Channels

• Cloud Authentication & Session Management: Login to Divoom Cloud (pixoo-cli cloud login) and manage authenticated sessions.
• Custom Gallery Channels: Upload animations and static pixel art into device persistent custom channels/pages (pixoo-cli cloud upload --slot 0..2).
• Binary Animation Encoder: Built-in DivoomAnimationEncoder converting 64x64 animations into Divoom-compatible binary format.
• Modernized Models: 100% Java 21 immutable records with sealed interface DivoomResponse for type-safe pattern matching.

⏱️ Hardware Interactive Tools Engine

• Stopwatch: Reset, start, stop, and query on-screen stopwatch status (pixoo-cli tool stopwatch).
• Countdown Timer: Configure minutes/seconds countdown timer (pixoo-cli tool timer).
• Scoreboard: Live Blue vs Red score tracker (pixoo-cli tool scoreboard).
• Noise Meter: Real-time ambient noise decibel meter (pixoo-cli tool noise).

⚙️ System & Channel Management

• RTC Clock Sync: Direct hardware real-time clock synchronization (pixoo-cli time sync).
• System Config: Read and update 24h format, temperature unit, auto-off timers, mirroring (pixoo-cli config).
• Channel Configuration: Set boot channel, select clock faces, switch gallery pages (pixoo-cli channel).

🐛 Protocol Fixes & Enhancements

• Strict cJSON Ordering: Enforced "Command" as first JSON key required by ESP32 micro-webserver.
• Screen Status & Rotation: Fixed display state query and rotation mode indices.
• 64-bit Device IDs: Fixed integer overflow for cloud device IDs.

---

📦 Pre-compiled Native Binaries

Native executables (GraalVM 21) with instantaneous startup (<5ms):

• macOS (Apple Silicon): pixoo-cli-macos-aarch64.zip
• Linux (x86_64): pixoo-cli-linux-amd64.zip
• Windows (x86_64): pixoo-cli-windows-amd64.zip

v0.1.0

chore: compress native binaries as zip and rename CLI to pixoo-cli