fortplot_annotations Module

Text annotation system for fortplot (Issue #55)

Provides comprehensive text annotation functionality with support for: - Multiple coordinate systems (data, figure, axis) - Typography control (font size, alignment, rotation) - Background boxes and arrow annotations - Backend-independent rendering

Follows SOLID principles with clean separation of concerns


Uses


Variables

Type Visibility Attributes Name Initial
integer, public, parameter :: COORD_DATA = 1
integer, public, parameter :: COORD_FIGURE = 2
integer, public, parameter :: COORD_AXIS = 3

Interfaces

public interface transform_annotation_coordinates

  • private subroutine transform_annotation_coordinates_4arg(annotation, area_or_size, pixel_x, pixel_y)

    4-argument coordinate transformation (figure or axis coordinates)

    Arguments

    Type IntentOptional Attributes Name
    type(text_annotation_t), intent(in) :: annotation
    real(kind=wp), intent(in) :: area_or_size(:)
    real(kind=wp), intent(out) :: pixel_x
    real(kind=wp), intent(out) :: pixel_y

  • private subroutine transform_annotation_coordinates_5arg(annotation, plot_area, data_bounds, pixel_x, pixel_y)

    5-argument coordinate transformation (data coordinates)

    Arguments

    Type IntentOptional Attributes Name
    type(text_annotation_t), intent(in) :: annotation
    real(kind=wp), intent(in) :: plot_area(:)
    real(kind=wp), intent(in) :: data_bounds(:)
    real(kind=wp), intent(out) :: pixel_x
    real(kind=wp), intent(out) :: pixel_y

Derived Types

type, public ::  text_annotation_t

Components

Type Visibility Attributes Name Initial
character(len=256), public :: text = ""
real(kind=wp), public :: x = 0.0_wp
real(kind=wp), public :: y = 0.0_wp
integer, public :: coord_type = COORD_DATA
real(kind=wp), public :: font_size = 12.0_wp
real(kind=wp), public :: rotation = 0.0_wp
character(len=16), public :: alignment = 'left'
character(len=16), public :: ha = 'left'
character(len=16), public :: va = 'bottom'
character(len=64), public :: font_family = 'DejaVu Sans'
character(len=16), public :: weight = 'normal'
character(len=16), public :: style = 'normal'
real(kind=wp), public :: color(3) = [0.0_wp, 0.0_wp, 0.0_wp]
real(kind=wp), public :: alpha = 1.0_wp
logical, public :: has_bbox = .false.
logical, public :: bbox = .false.
type(annotation_color_t), public :: bbox_color = annotation_color_t(1.0_wp, 1.0_wp, 1.0_wp, 1.0_wp)
logical, public :: has_arrow = .false.
real(kind=wp), public :: arrow_x = 0.0_wp
real(kind=wp), public :: arrow_y = 0.0_wp
integer, public :: arrow_coord_type = COORD_DATA
real(kind=wp), public :: xytext_x = 0.0_wp
real(kind=wp), public :: xytext_y = 0.0_wp
integer, public :: xytext_coord_type = COORD_DATA
character(len=64), public :: arrowstyle = ''

Functions

public function create_text_annotation(text, x, y, coord_type) result(annotation)

Create a text annotation with specified properties

Arguments

Type IntentOptional Attributes Name
character(len=*), intent(in) :: text
real(kind=wp), intent(in) :: x
real(kind=wp), intent(in) :: y
integer, intent(in), optional :: coord_type

Return Value type(text_annotation_t)

public function is_annotation_visible(annotation, plot_area) result(visible)

Check if annotation is visible within plot area

Arguments

Type IntentOptional Attributes Name
type(text_annotation_t), intent(in) :: annotation
real(kind=wp), intent(in) :: plot_area(4)

Return Value logical


Subroutines

public subroutine destroy_text_annotation(annotation)

Clean up text annotation resources

Arguments

Type IntentOptional Attributes Name
type(text_annotation_t), intent(inout) :: annotation

public subroutine transform_annotation_coordinates_log(annotation, plot_area, data_bounds, log_scale_x, log_scale_y, pixel_x, pixel_y)

Transform annotation coordinates with logarithmic scaling support

Arguments

Type IntentOptional Attributes Name
type(text_annotation_t), intent(in) :: annotation
real(kind=wp), intent(in) :: plot_area(4)
real(kind=wp), intent(in) :: data_bounds(4)
logical, intent(in) :: log_scale_x
logical, intent(in) :: log_scale_y
real(kind=wp), intent(out) :: pixel_x
real(kind=wp), intent(out) :: pixel_y

public subroutine calculate_aligned_position(annotation, text_width, text_height, adjusted_x, adjusted_y)

Calculate aligned text position based on alignment settings

Arguments

Type IntentOptional Attributes Name
type(text_annotation_t), intent(in) :: annotation
real(kind=wp), intent(in) :: text_width
real(kind=wp), intent(in) :: text_height
real(kind=wp), intent(out) :: adjusted_x
real(kind=wp), intent(out) :: adjusted_y

public subroutine calculate_rotated_bounds(annotation, bounds)

Calculate bounding box for rotated text

Arguments

Type IntentOptional Attributes Name
type(text_annotation_t), intent(in) :: annotation
real(kind=wp), intent(out) :: bounds(4)

public subroutine validate_annotation_coordinates(annotation, valid, error_message)

Validate annotation coordinate values

Arguments

Type IntentOptional Attributes Name
type(text_annotation_t), intent(in) :: annotation
logical, intent(out) :: valid
character(len=256), intent(out) :: error_message

public subroutine validate_annotation_parameters(annotation, valid, error_message)

Validate annotation parameter values

Arguments

Type IntentOptional Attributes Name
type(text_annotation_t), intent(in) :: annotation
logical, intent(out) :: valid
character(len=256), intent(out) :: error_message

public subroutine validate_annotation(annotation, valid, error_message)

Comprehensive annotation validation combining coordinate and parameter checks

Arguments

Type IntentOptional Attributes Name
type(text_annotation_t), intent(in) :: annotation
logical, intent(out) :: valid
character(len=*), intent(out) :: error_message

public subroutine calculate_text_metrics_safe(annotation, width, height, valid, error_message)

Safe text metrics calculation with error handling

Arguments

Type IntentOptional Attributes Name
type(text_annotation_t), intent(in) :: annotation
real(kind=wp), intent(out) :: width
real(kind=wp), intent(out) :: height
logical, intent(out) :: valid
character(len=*), intent(out) :: error_message

public subroutine load_font_system(font_path, loaded, error_message)

Load font system from specified path

Arguments

Type IntentOptional Attributes Name
character(len=*), intent(in) :: font_path
logical, intent(out) :: loaded
character(len=*), intent(out) :: error_message

public subroutine validate_text_parameters(annotation, valid, error_message)

Alias for validate_annotation_parameters for API compatibility

Arguments

Type IntentOptional Attributes Name
type(text_annotation_t), intent(in) :: annotation
logical, intent(out) :: valid
character(len=*), intent(out) :: error_message

public subroutine calculate_text_metrics(annotation, width, height)

Calculate text dimensions for given annotation

Arguments

Type IntentOptional Attributes Name
type(text_annotation_t), intent(in) :: annotation
real(kind=wp), intent(out) :: width
real(kind=wp), intent(out) :: height

public subroutine calculate_text_anchor(annotation, text_width, text_height, anchor_x, anchor_y)

Calculate anchor position based on alignment settings

Arguments

Type IntentOptional Attributes Name
type(text_annotation_t), intent(in) :: annotation
real(kind=wp), intent(in) :: text_width
real(kind=wp), intent(in) :: text_height
real(kind=wp), intent(out) :: anchor_x
real(kind=wp), intent(out) :: anchor_y

public subroutine calculate_rotated_text_bounds(annotation, bounds)

Calculate bounding box for rotated text

Arguments

Type IntentOptional Attributes Name
type(text_annotation_t), intent(in) :: annotation
real(kind=wp), intent(out) :: bounds(4)

public subroutine select_font_family(annotation, selected_font, font_found)

Select font family with fallback mechanism

Arguments

Type IntentOptional Attributes Name
type(text_annotation_t), intent(in) :: annotation
character(len=*), intent(out) :: selected_font
logical, intent(out) :: font_found

public subroutine validate_typography_parameters(annotation, valid, error_message)

Validate typography-specific parameters with normalization support

Arguments

Type IntentOptional Attributes Name
type(text_annotation_t), intent(in) :: annotation
logical, intent(out) :: valid
character(len=*), intent(out) :: error_message