3D Plotting with GUI - Complete Implementation

Date: October 22, 2025

Overview

Completed full 3D plotting with PNG generation AND GUI window display support. All 3D plots now automatically open in interactive windows when using xdl-gui.

✅ Features Implemented

1. PNG File Generation

  • All 3D plots save to PNG files
  • High-quality output with plotters library
  • Automatic coordinate generation
  • Height-based coloring

2. GUI Window Display

  • NEW: Automatic image window display in xdl-gui
  • Images load in resizable FLTK windows
  • Proper scaling for large images (max 1200x900)
  • Clean white background with padding
  • Titled windows for each plot type

Implementation

New Components

ImageWindow Module (xdl-gui/src/image_window.rs)

  • Loads PNG images using FLTK’s PngImage
  • Auto-scales large images to fit screen
  • Centered display with padding
  • Close button handling
  • Event loop for window interaction

Callback System

  • GUI_IMAGE_CALLBACK - Global callback for image display
  • register_gui_image_callback() - Registration function
  • Called automatically after PNG generation
  • Works similar to existing 2D plot callback

Integration Points

  1. xdl-stdlib/src/graphics_procs.rs
    • Added GUI_IMAGE_CALLBACK static
    • Added register_gui_image_callback() function
    • Updated all 3D procedures to call callback after PNG save
  2. xdl-gui/src/gui.rs
    • Import ImageWindow module
    • Register callback in GUI initialization
    • Callback opens ImageWindow with path and title
  3. xdl-stdlib/src/lib.rs
    • Export register_gui_image_callback

Usage 

xdl-gui examples/plot3d_demo.xdl

Behavior:

  1. Script executes
  2. PNG file generated (e.g., xdl_surface.png)
  3. Image window opens automatically
  4. User views plot interactively
  5. Close window to continue to next plot

Without GUI (CLI) 

xdl examples/plot3d_demo.xdl

Behavior:

  1. Script executes
  2. PNG files generated
  3. No window display (files saved to disk)
  4. Can view manually: open xdl_surface.png

Example Code 

; Create a surface plot
z = [[1, 2, 3, 2, 1],
     [2, 4, 6, 4, 2],
     [3, 6, 9, 6, 3]]
SURFACE, z

; In GUI mode: Window automatically opens showing the surface
; In CLI mode: File saved as xdl_surface.png

Window Titles

Each plot type has a descriptive window title:

  • SURFACE → “XDL Surface Plot”
  • CONTOUR → “XDL Contour Plot”
  • SHADE_SURF → “XDL Shaded Surface”
  • PLOT3D → “XDL 3D Line Plot”

File Outputs

Procedure PNG Filename Window Title
SURFACE xdl_surface.png XDL Surface Plot
CONTOUR xdl_contour.png XDL Contour Plot
SHADE_SURF xdl_shade_surf.png XDL Shaded Surface
PLOT3D xdl_plot3d.png XDL 3D Line Plot

Technical Details

Image Loading

  • Uses FLTK’s PngImage::load()
  • Error handling for missing/corrupt files
  • Automatic format detection

Window Sizing

  • Base size: image dimensions + 40px padding
  • Maximum: 1200x900 (scaled proportionally)
  • Window title bar: +30px height
  • Always maintains aspect ratio

Event Handling

  • Close button properly handled
  • Event loop runs until window closed
  • Clean window disposal

Thread Safety

  • Callback uses Arc<dyn Fn> for thread safety
  • Mutex protection for global callback
  • Safe to call from any thread

Differences from 2D PLOT

Feature 2D PLOT 3D PLOTS
Data Source In-memory vectors PNG files
Rendering Direct with plotters in window Pre-rendered to PNG, then displayed
Interaction Real-time chart Static image
Performance Immediate Two-step (render + display)
Quality Screen resolution High resolution PNG

Benefits of Two-Step Approach

  1. File Persistence - Plots saved to disk automatically
  2. High Quality - PNG format preserves detail
  3. Flexibility - Works in both GUI and CLI modes
  4. Simple Integration - No complex 3D rendering in GUI
  5. Reliability - PNG is a standard, well-supported format

Testing

Test Script 

# Run the demo
xdl-gui examples/plot3d_demo.xdl

Expected Results

  • 5 image windows open in sequence
  • Each shows a different 3D visualization
  • Windows can be closed to proceed
  • All PNG files saved to current directory

Verification 

# Check generated files
ls -lh xdl_*.png

# View a specific plot
open xdl_surface.png  # macOS

Code Changes Summary

Files Modified: 4

  1. xdl-gui/src/image_window.rs (NEW)
    • Complete image window implementation
    • ~88 lines
  2. xdl-gui/src/main.rs
    • Added mod image_window;
  3. xdl-gui/src/gui.rs
    • Import ImageWindow
    • Import register_gui_image_callback
    • Register callback in initialization
  4. xdl-stdlib/src/graphics_procs.rs
    • Added GUI_IMAGE_CALLBACK static
    • Added register_gui_image_callback() function
    • Updated SURFACE to call callback
    • Updated CONTOUR to call callback
    • Updated SHADE_SURF to call callback
    • Updated PLOT3D to call callback
  5. xdl-stdlib/src/lib.rs
    • Export register_gui_image_callback

Future Enhancements

Potential Improvements

  1. Interactive 3D - Real 3D rendering with rotation
  2. Multiple Windows - Show all plots simultaneously
  3. Export Options - Save as PDF, SVG, etc.
  4. Zoom/Pan - Image manipulation in window
  5. Comparison View - Side-by-side plot comparison

Advanced Features

  1. Animation - Rotate 3D plots in window
  2. Real-time Updates - Live plot updates
  3. Custom Views - Change perspective angles
  4. Annotations - Add text/markers in GUI

Conclusion

3D plotting is now fully integrated with the GUI:

  • ✅ PNG generation works
  • ✅ GUI window display works
  • ✅ CLI fallback works
  • ✅ All 4 procedures supported
  • ✅ Clean, user-friendly interface

The system is production-ready for both GUI and CLI use!

Quick Reference

Run with GUI 

xdl-gui <script>.xdl
  • Plots open in windows automatically
  • Close windows to continue execution

Run without GUI 

xdl <script>.xdl
  • Plots saved as PNG files
  • No windows displayed

Test Demo 

xdl-gui examples/plot3d_demo.xdl
  • See all 3D plot types
  • Interactive window display
  • Professional visualization quality