fix: restore PDF axes visibility and prevent plot stretching/shifting #338 (#339)

Squash merge PDF axes rendering fix

Author: krystophny

BACKLOG.md

@@ -3,13 +3,25 @@
 ## CURRENT SPRINT (Critical PNG/PDF Rendering Issues)
 
 **🚨 CRITICAL: User-visible PNG/PDF rendering completely broken**
+- [x] #338: Fix - No axes visible and plots strangely stretched and shifted in PDF (moved to DOING)
+- [ ] #337: Fix - Title too far right in PNGs - check matplotlib placement
+- [ ] #335: Fix - Axes wrong and no labels visible on scale_examples.html
+- [ ] #334: Fix - No output visible on pcolormesh_demo.html
+- [ ] #333: Fix - Circles seem not centered with line plot in marker_demo.html
+- [ ] #332: Fix - Dashed and dash-dotted look funny on line_styles.html
+- [ ] #331: Fix - No legend visible in format_string_demo.html
+- [ ] #330: Fix - Old plot not cleared in second figure (figure() call) in contour_demo.html
+- [ ] #329: Fix - No output visible on colored_contours.html
+- [ ] #328: Fix - One legend entry too much in basic_plots.html second plot
+- [ ] #327: Fix - MP4 link not showing on animation.html
+- [ ] #336: Fix - Streamplot and stateful streamplot example redundant
 
 **Infrastructure & Documentation Issues (Lower Priority)**
 - [ ] #323: Test - add edge case tests for PDF heatmap color validation
 - [ ] #324: Refactor - define epsilon constant for numerical comparisons
 
 ## DOING (Current Work)
-- [x] #321: Refactor - apply consistent validation pattern to other PDF write functions (branch: refactor-consistent-validation-321)
+- [ ] #338: Fix - No axes visible and plots strangely stretched and shifted in PDF
 
 ## BLOCKED (Infrastructure Issues)
 
@@ -36,6 +48,7 @@
 - Performance impact validation
 
 ## DONE (Completed)
+- [x] #321: Refactor - apply consistent validation pattern to other PDF write functions - FIXED: Extended robust validation pattern to pdf_write_move, pdf_write_line, and pdf_write_line_width with comprehensive test coverage and zero performance impact (PR #326 merged)
 - [x] #320: Feature - add debug logging for invalid color value corrections - FIXED: Implemented debug logging for RGB color corrections in PDF output with zero performance impact and comprehensive test coverage (PR #325 merged)
 - [x] #319: Refactor - investigate source of invalid RGB values in contour color mapping - FIXED: Replaced direct color writing with validated pdf_write_color method, added proper edge case handling for division by zero scenarios (PR #322 merged)
 - [x] #317: Fix GitHub Pages deployment failure - colored_contours PDF runtime crash in pdf_write_color - FIXED: Added robust RGB validation to prevent PDF color crashes, restored visual showcase (PR #318 merged)

src/fortplot_ascii.f90

@@ -62,6 +62,7 @@ module fortplot_ascii
         procedure :: draw_axes_and_labels_backend => ascii_draw_axes_and_labels
         procedure :: save_coordinates => ascii_save_coordinates
         procedure :: set_coordinates => ascii_set_coordinates
+        procedure :: render_axes => ascii_render_axes
     end type ascii_context
 
     ! ASCII plotting constants
@@ -927,4 +928,13 @@ subroutine ascii_set_coordinates(this, x_min, x_max, y_min, y_max)
         this%y_max = y_max
     end subroutine ascii_set_coordinates
 
+    subroutine ascii_render_axes(this, title_text, xlabel_text, ylabel_text)
+        !! Render axes for ASCII context (stub implementation)
+        class(ascii_context), intent(inout) :: this
+        character(len=*), intent(in), optional :: title_text, xlabel_text, ylabel_text
+        
+        ! ASCII axes are rendered as part of draw_axes_and_labels_backend
+        ! This is a stub to satisfy the interface
+    end subroutine ascii_render_axes
+
 end module fortplot_ascii

src/fortplot_context.f90

@@ -44,6 +44,7 @@ module fortplot_context
         procedure(draw_axes_and_labels_interface), deferred :: draw_axes_and_labels_backend
         procedure(save_coordinates_interface), deferred :: save_coordinates
         procedure(set_coordinates_interface), deferred :: set_coordinates
+        procedure(render_axes_interface), deferred :: render_axes
     end type plot_context
 
     abstract interface
@@ -190,6 +191,12 @@ subroutine set_coordinates_interface(this, x_min, x_max, y_min, y_max)
             class(plot_context), intent(inout) :: this
             real(wp), intent(in) :: x_min, x_max, y_min, y_max
         end subroutine set_coordinates_interface
+
+        subroutine render_axes_interface(this, title_text, xlabel_text, ylabel_text)
+            import :: plot_context
+            class(plot_context), intent(inout) :: this
+            character(len=*), intent(in), optional :: title_text, xlabel_text, ylabel_text
+        end subroutine render_axes_interface
     end interface
 
 contains

src/fortplot_pdf.f90

@@ -33,6 +33,7 @@ module fortplot_pdf
         type(pdf_context_handle), private :: coord_ctx
         integer :: x_tick_count = 0
         integer :: y_tick_count = 0
+        logical, private :: axes_rendered = .false.
     contains
         procedure :: line => draw_pdf_line
         procedure :: color => set_pdf_color
@@ -62,6 +63,7 @@ module fortplot_pdf
         procedure :: draw_axes_and_labels_backend => draw_axes_and_labels_backend_wrapper
         procedure :: save_coordinates => pdf_save_coordinates
         procedure :: set_coordinates => pdf_set_coordinates
+        procedure :: render_axes => render_pdf_axes_wrapper
 
         procedure, private :: update_coord_context
         procedure, private :: make_coord_context
@@ -133,6 +135,10 @@ subroutine write_pdf_file_facade(this, filename)
         class(pdf_context), intent(inout) :: this
         character(len=*), intent(in) :: filename
 
+        ! Automatically render axes if they haven't been rendered yet
+        ! This provides better UX for low-level PDF API users
+        call this%render_axes()
+        
         this%core_ctx%stream_data = this%stream_writer%content_stream
         call write_pdf_file(this%core_ctx, filename)
     end subroutine write_pdf_file_facade
@@ -413,6 +419,56 @@ subroutine pdf_set_coordinates(this, x_min, x_max, y_min, y_max)
         this%x_max = x_max
         this%y_min = y_min
         this%y_max = y_max
+        
+        ! Reset axes flag when coordinates change
+        this%axes_rendered = .false.
     end subroutine pdf_set_coordinates
 
+    subroutine render_pdf_axes_wrapper(this, title_text, xlabel_text, ylabel_text)
+        !! Explicitly render axes with optional labels
+        !! This allows low-level PDF users to add proper axes to their plots
+        class(pdf_context), intent(inout) :: this
+        character(len=*), intent(in), optional :: title_text, xlabel_text, ylabel_text
+        
+        character(len=256) :: title_str, xlabel_str, ylabel_str
+        
+        ! Only render axes once unless coordinates change
+        if (this%axes_rendered) return
+        
+        ! Ensure coordinate system is set
+        if (this%x_min == this%x_max .or. this%y_min == this%y_max) then
+            ! No valid coordinate system - skip axes
+            return
+        end if
+        
+        ! Set default empty strings for labels
+        title_str = ""
+        xlabel_str = ""  
+        ylabel_str = ""
+        
+        ! Use provided labels if present
+        if (present(title_text)) title_str = title_text
+        if (present(xlabel_text)) xlabel_str = xlabel_text
+        if (present(ylabel_text)) ylabel_str = ylabel_text
+        
+        ! Clear any previous axes data in core context
+        this%core_ctx%stream_data = ""
+        
+        ! Draw axes and labels with current coordinate system
+        call draw_pdf_axes_and_labels(this%core_ctx, "linear", "linear", 1.0_wp, &
+                                     this%x_min, this%x_max, this%y_min, this%y_max, &
+                                     title_str, xlabel_str, ylabel_str, &
+                                     real(this%plot_area%left, wp), &
+                                     real(this%plot_area%bottom, wp), &
+                                     real(this%plot_area%width, wp), &
+                                     real(this%plot_area%height, wp), &
+                                     real(this%height, wp))
+        
+        ! Add axes content to the stream
+        call this%stream_writer%add_to_stream(this%core_ctx%stream_data)
+        
+        ! Mark axes as rendered
+        this%axes_rendered = .true.
+    end subroutine render_pdf_axes_wrapper
+    
 end module fortplot_pdf

src/fortplot_raster.f90

@@ -87,6 +87,7 @@ module fortplot_raster
         procedure :: draw_axes_and_labels_backend => raster_draw_axes_and_labels
         procedure :: save_coordinates => raster_save_coordinates
         procedure :: set_coordinates => raster_set_coordinates
+        procedure :: render_axes => raster_render_axes
     end type raster_context
 
 contains
@@ -1014,5 +1015,13 @@ subroutine raster_set_coordinates(this, x_min, x_max, y_min, y_max)
         this%y_max = y_max
     end subroutine raster_set_coordinates
 
+    subroutine raster_render_axes(this, title_text, xlabel_text, ylabel_text)
+        !! Render axes for raster context (stub implementation)
+        class(raster_context), intent(inout) :: this
+        character(len=*), intent(in), optional :: title_text, xlabel_text, ylabel_text
+        
+        ! Raster axes are rendered as part of draw_axes_and_labels_backend
+        ! This is a stub to satisfy the interface
+    end subroutine raster_render_axes
 
 end module fortplot_raster

test/test_axes_edge_cases_338.f90

@@ -0,0 +1,55 @@
+program test_axes_edge_cases_338
+    !! Test edge cases for PDF axes rendering fix (Issue #338)
+    use iso_fortran_env, only: wp => real64
+    use fortplot_pdf, only: pdf_context, create_pdf_canvas
+    implicit none
+
+    type(pdf_context) :: ctx
+
+    write(*, '(A)') "Testing PDF axes edge cases for Issue #338"
+
+    ! Test 1: Multiple coordinate changes
+    ctx = create_pdf_canvas(600, 400)
+    ctx%x_min = 0.0_wp
+    ctx%x_max = 1.0_wp
+    ctx%y_min = 0.0_wp
+    ctx%y_max = 1.0_wp
+    
+    call ctx%render_axes("Test 1", "X1", "Y1")
+    
+    ! Change coordinates - should reset axes_rendered
+    ctx%x_min = -1.0_wp
+    ctx%x_max = 2.0_wp
+    ctx%y_min = -2.0_wp
+    ctx%y_max = 3.0_wp
+    
+    call ctx%render_axes("Test 1b", "X2", "Y2")
+    call ctx%save("test_edge_case_1.pdf")
+
+    ! Test 2: Degenerate coordinate system
+    ctx = create_pdf_canvas(600, 400)
+    ctx%x_min = 1.0_wp
+    ctx%x_max = 1.0_wp  ! Same values - degenerate
+    ctx%y_min = -1.0_wp
+    ctx%y_max = 2.0_wp
+    
+    call ctx%render_axes("Degenerate X", "X", "Y")
+    call ctx%save("test_edge_case_2.pdf")
+
+    ! Test 3: Multiple explicit axes calls
+    ctx = create_pdf_canvas(600, 400)
+    ctx%x_min = 0.0_wp
+    ctx%x_max = 10.0_wp
+    ctx%y_min = -5.0_wp
+    ctx%y_max = 5.0_wp
+    
+    call ctx%render_axes("First", "X1", "Y1")
+    call ctx%render_axes("Second", "X2", "Y2")  ! Should be ignored
+    call ctx%save("test_edge_case_3.pdf")
+
+    write(*, '(A)') "Edge case tests completed:"
+    write(*, '(A)') "- test_edge_case_1.pdf: Multiple coordinate changes"
+    write(*, '(A)') "- test_edge_case_2.pdf: Degenerate coordinates (should have no axes)"
+    write(*, '(A)') "- test_edge_case_3.pdf: Multiple axes calls (should use first)"
+
+end program test_axes_edge_cases_338

test/test_axes_order_338.f90

@@ -0,0 +1,49 @@
+program test_axes_order_338
+    use iso_fortran_env, only: wp => real64
+    use fortplot_pdf, only: pdf_context, create_pdf_canvas
+    implicit none
+
+    type(pdf_context) :: ctx
+    integer :: i
+    real(wp) :: x, y, prev_x, prev_y
+
+    write(*, '(A)') "Testing axes/content order in PDF"
+
+    ctx = create_pdf_canvas(600, 400)
+    ctx%x_min = 0.0_wp
+    ctx%x_max = 10.0_wp
+    ctx%y_min = -2.0_wp
+    ctx%y_max = 2.0_wp
+
+    ! Draw content BEFORE explicit axes call
+    call ctx%color(0.0_wp, 0.0_wp, 1.0_wp)
+    do i = 1, 50
+        x = real(i-1, wp) * 10.0_wp / 49.0_wp
+        y = sin(x)
+        if (i > 1) then
+            call ctx%line(prev_x, prev_y, x, y)
+        end if
+        prev_x = x
+        prev_y = y
+    end do
+
+    ! Explicitly render axes
+    call ctx%render_axes("Test Plot", "X Axis", "Y Axis")
+
+    ! Draw MORE content AFTER axes call
+    call ctx%color(1.0_wp, 0.0_wp, 0.0_wp)
+    do i = 1, 50
+        x = real(i-1, wp) * 10.0_wp / 49.0_wp
+        y = cos(x)
+        if (i > 1) then
+            call ctx%line(prev_x, prev_y, x, y)
+        end if
+        prev_x = x
+        prev_y = y
+    end do
+
+    call ctx%save("test_axes_order.pdf")
+    write(*, '(A)') "Generated test_axes_order.pdf"
+    write(*, '(A)') "Check: Should see both blue sine and red cosine curves with axes"
+
+end program test_axes_order_338

test/test_pdf_axes_simple_338.f90

@@ -0,0 +1,36 @@
+program test_pdf_axes_simple_338
+    use iso_fortran_env, only: wp => real64
+    use fortplot_pdf, only: pdf_context, create_pdf_canvas
+    implicit none
+
+    type(pdf_context) :: ctx
+    integer :: i
+    real(wp) :: x, y, prev_x, prev_y
+
+    write(*, '(A)') "Testing PDF axes fix for Issue #338"
+
+    ctx = create_pdf_canvas(600, 400)
+    ctx%x_min = 0.0_wp
+    ctx%x_max = 10.0_wp
+    ctx%y_min = -2.0_wp
+    ctx%y_max = 2.0_wp
+
+    ! Draw a sine wave
+    call ctx%color(0.0_wp, 0.0_wp, 1.0_wp)
+    do i = 1, 100
+        x = real(i-1, wp) * 10.0_wp / 99.0_wp
+        y = sin(x)
+        
+        if (i > 1) then
+            call ctx%line(prev_x, prev_y, x, y)
+        end if
+        prev_x = x
+        prev_y = y
+    end do
+
+    call ctx%save("test_axes_simple_338.pdf")
+    write(*, '(A)') "Generated: test_axes_simple_338.pdf"
+    write(*, '(A)') "Expected: PDF with visible axes, tick marks, and labels"
+    write(*, '(A)') "If axes are visible, Issue #338 is fixed!"
+
+end program test_pdf_axes_simple_338