Graphics and Images

class Image(Flowable):
    """
    Block-level image element with comprehensive formatting options.
    
    Parameters:
    - filename_or_file: str or file-like, path to image file or open file
    - scale: float or Scale, scaling factor or scaling mode
    - width: Dimension, explicit width (overrides scale)
    - height: Dimension, explicit height (overrides scale)
    - dpi: float, resolution for pixel-based images
    - rotate: float, rotation angle in degrees
    - limit_width: Dimension, maximum width constraint
    - alt: str, alternative text for accessibility
    - id: str, unique identifier
    - style: Style, styling for the image
    - parent: parent element
    - source: source location information
    """
    def __init__(self, filename_or_file, scale=1.0, width=None, height=None, 
                 dpi=None, rotate=0, limit_width=None, alt=None, 
                 id=None, style=None, parent=None, source=None): ...
    
    @property
    def filename(self): ...  # Image file path
    @property
    def image_size(self): ...  # Original image dimensions
    @property
    def scaled_size(self): ...  # Final scaled dimensions
    
    def get_intrinsic_size(self): ...  # Get natural image size

class InlineImage(InlineFlowable):
    """
    Inline image that flows with text content.
    
    Similar to Image but designed for embedding within paragraphs
    and other text-based content.
    
    Parameters:
    - filename_or_file: str or file-like, image source
    - scale: float or Scale, scaling options
    - width: Dimension, explicit width
    - height: Dimension, explicit height
    - baseline: Dimension, baseline alignment offset
    - alt: str, alternative text
    - style: InlineStyle, styling for inline context
    - parent: parent element
    """
    def __init__(self, filename_or_file, scale=1.0, width=None, height=None,
                 baseline=None, alt=None, style=None, parent=None): ...

class BackgroundImage(Image):
    """
    Background image for pages or containers.
    
    Provides background imagery with positioning, scaling, and
    repeat options for page backgrounds and decorative elements.
    
    Parameters:
    - filename_or_file: str or file-like, background image source
    - position: str, positioning ('center', 'top-left', etc.)
    - repeat: str, repeat mode ('no-repeat', 'repeat', 'repeat-x', 'repeat-y')
    - opacity: float, background opacity (0.0 to 1.0)
    - **kwargs: additional Image parameters
    """
    def __init__(self, filename_or_file, position='center', repeat='no-repeat', 
                 opacity=1.0, **kwargs): ...

class ImageArgs:
    """
    Container for image arguments and configuration.
    
    Encapsulates image parameters for consistent handling across
    different image types and processing contexts.
    
    Parameters:
    - scale: float or Scale, scaling configuration
    - width: Dimension, target width
    - height: Dimension, target height
    - dpi: float, resolution setting
    - rotate: float, rotation angle
    """
    def __init__(self, scale=1.0, width=None, height=None, dpi=None, rotate=0): ...

class Scale:
    """
    Image scaling modes and options.
    
    Provides different strategies for sizing images within layout
    constraints while maintaining aspect ratios and quality.
    """
    
    # Scaling constants
    FIT = 'fit'      # Scale to fit within bounds, preserve aspect ratio
    FILL = 'fill'    # Scale to fill bounds, may crop, preserve aspect ratio
    STRETCH = 'stretch'  # Scale to exact bounds, ignore aspect ratio
    
    def __init__(self, mode, factor=1.0):
        """
        Create scaling configuration.
        
        Parameters:
        - mode: str, scaling mode ('fit', 'fill', 'stretch', or numeric)
        - factor: float, additional scaling factor
        """
        ...

class Figure(Float):
    """
    Image or content with caption as a floating figure.
    
    Provides numbered figures with captions that can float to
    appropriate positions and integrate with lists of figures.
    
    Parameters:
    - image_or_flowable: Image or other Flowable for figure content
    - caption: Caption or str, figure caption
    - id: str, unique identifier for cross-referencing
    - style: FigureStyle, styling for the figure
    - parent: parent element
    - source: source location information
    """
    def __init__(self, image_or_flowable, caption=None, id=None, 
                 style=None, parent=None, source=None): ...
    
    @property
    def number(self): ...  # Figure number
    @property
    def formatted_number(self): ...  # Formatted figure number

class Caption(Paragraph):
    """
    Caption for figures, tables, and other captioned content.
    
    Specialized paragraph for captions with automatic numbering,
    special formatting, and integration with lists of figures/tables.
    
    Parameters:
    - content: str or list, caption text content
    - category: str, caption category ('figure', 'table', etc.)
    - id: str, unique identifier
    - style: CaptionStyle, caption-specific styling
    - parent: parent element
    - source: source location information
    """
    def __init__(self, content, category='figure', id=None, 
                 style=None, parent=None, source=None): ...

class CaptionStyle(Style):
    """Style configuration for captions including numbering and formatting."""
    
    number_format = Attribute(NumberFormat)  # Number formatting
    number_separator = Attribute(str)        # Separator between number and text

class FigureStyle(Style):
    """Style configuration for figures including positioning and spacing."""

class ListOfFigures(Section):
    """
    Automatically generated list of all figures in document.
    
    Creates a section containing links to all figures with their
    captions and page numbers.
    
    Parameters:
    - id: str, unique identifier
    - style: Style, styling for the list section
    - parent: parent element
    - source: source location information
    """
    def __init__(self, id=None, style=None, parent=None, source=None): ...

class ListOfFiguresSection(Section):
    """Section wrapper for list of figures with proper formatting."""

class Shape(Flowable):
    """
    Base class for vector shapes and drawing primitives.
    
    Provides foundation for all drawn geometric elements with
    styling, positioning, and rendering capabilities.
    
    Parameters:
    - style: ShapeStyle, styling for the shape
    - parent: parent element
    - source: source location information
    """
    def __init__(self, style=None, parent=None, source=None): ...

class Rectangle(Shape):
    """
    Rectangular shape with customizable dimensions and styling.
    
    Parameters:
    - bottom_left: (Dimension, Dimension), bottom-left corner position
    - width: Dimension, rectangle width
    - height: Dimension, rectangle height
    - style: ShapeStyle, styling including fill and stroke
    - parent: parent element
    - source: source location information
    """
    def __init__(self, bottom_left, width, height, style=None, parent=None, source=None): ...
    
    @property
    def top_right(self): ...  # Top-right corner position
    @property
    def center(self): ...     # Center point

class Polygon(Shape):
    """
    Multi-point polygon shape.
    
    Creates closed shape from sequence of points with customizable
    styling for both fill and stroke properties.
    
    Parameters:
    - points: list of (Dimension, Dimension), polygon vertices
    - style: ShapeStyle, styling for fill and stroke
    - parent: parent element
    - source: source location information
    """
    def __init__(self, points, style=None, parent=None, source=None): ...
    
    @property
    def points(self): ...  # Polygon vertices
    @property
    def bounds(self): ...  # Bounding rectangle

class Line(Shape):
    """
    Straight line between two points.
    
    Parameters:
    - start: (Dimension, Dimension), line start point
    - end: (Dimension, Dimension), line end point
    - style: LineStyle, styling for line appearance
    - parent: parent element
    - source: source location information
    """
    def __init__(self, start, end, style=None, parent=None, source=None): ...
    
    @property
    def length(self): ...  # Line length
    @property
    def angle(self): ...   # Line angle in degrees

class ShapeStyle(Style):
    """
    Style configuration for filled shapes.
    
    Controls both fill and stroke properties for shapes like
    rectangles, polygons, and other closed figures.
    """
    
    fill_color = Attribute(Color)      # Fill color
    fill_opacity = Attribute(float)    # Fill transparency (0.0-1.0)
    stroke_color = Attribute(Color)    # Stroke/border color
    stroke_width = Attribute(Dimension) # Stroke thickness
    stroke_opacity = Attribute(float)   # Stroke transparency

class LineStyle(Style):
    """
    Style configuration for lines and strokes.
    
    Controls appearance of linear elements including thickness,
    color, dash patterns, and end cap styles.
    """
    
    stroke_color = Attribute(Color)     # Line color
    stroke_width = Attribute(Dimension) # Line thickness
    stroke_opacity = Attribute(float)   # Line transparency
    line_cap = Attribute(str)          # End cap style ('butt', 'round', 'square')
    line_join = Attribute(str)         # Join style ('miter', 'round', 'bevel')
    dash_pattern = Attribute(list)     # Dash pattern [dash_length, gap_length, ...]

class Stroke:
    """
    Stroke definition for line drawing properties.
    
    Encapsulates line drawing properties for consistent application
    across different drawing contexts.
    
    Parameters:
    - width: Dimension, stroke thickness
    - color: Color, stroke color
    - opacity: float, stroke transparency
    - dash_pattern: list, dash pattern specification
    """
    def __init__(self, width, color, opacity=1.0, dash_pattern=None): ...

class Color:
    """
    RGBA color with red, green, blue, and alpha components.
    
    Parameters:
    - red: float, red component (0.0-1.0)
    - green: float, green component (0.0-1.0)
    - blue: float, blue component (0.0-1.0)
    - alpha: float, alpha/transparency component (0.0-1.0)
    """
    def __init__(self, red, green, blue, alpha=1.0): ...
    
    @property
    def rgba(self): ...  # (r, g, b, a) tuple
    @property
    def r(self): ...     # Red component
    @property
    def g(self): ...     # Green component  
    @property
    def b(self): ...     # Blue component
    @property
    def a(self): ...     # Alpha component
    
    def __add__(self, other): ...  # Color blending
    def with_alpha(self, alpha): ...  # Create copy with new alpha

class HexColor(Color):
    """
    Color created from hexadecimal string representation.
    
    Supports various hex formats including #RGB, #RRGGBB, #RRGGBBAA.
    
    Parameters:
    - hex_string: str, hexadecimal color string
    """
    def __init__(self, hex_string): ...

class Gray(Color):
    """
    Grayscale color with luminance value.
    
    Convenience class for creating grayscale colors from single
    luminance value instead of separate RGB components.
    
    Parameters:
    - luminance: float, grayscale value (0.0=black, 1.0=white)
    - alpha: float, transparency (0.0-1.0)
    """
    def __init__(self, luminance, alpha=1.0): ...

# Predefined colors
BLACK = Color(0, 0, 0)        # Pure black
WHITE = Color(1, 1, 1)        # Pure white  
RED = Color(1, 0, 0)          # Pure red
GREEN = Color(0, 1, 0)        # Pure green
BLUE = Color(0, 0, 1)         # Pure blue

# Predefined grays
GRAY10 = Gray(0.1)   # 10% gray
GRAY25 = Gray(0.25)  # 25% gray
GRAY50 = Gray(0.5)   # 50% gray
GRAY75 = Gray(0.75)  # 75% gray
GRAY90 = Gray(0.9)   # 90% gray

from rinohtype.image import Image, Figure, Caption
from rinohtype.dimension import MM, PT

# Simple image
photo = Image('photo.jpg', scale=0.8, alt="Company photo")

# Image with explicit dimensions
logo = Image('logo.png', width=50*MM, height=20*MM, alt="Company logo")

# Figure with caption
chart_image = Image('sales_chart.png', width=120*MM)
chart_caption = Caption("Monthly sales figures for 2024")
chart_figure = Figure(chart_image, caption=chart_caption, id='sales-chart')

from rinohtype.image import Image, Scale

# Fit image within bounds while preserving aspect ratio
fitted_image = Image('large_image.jpg', scale=Scale.FIT, 
                    width=100*MM, height=80*MM)

# Fill bounds, may crop image
filled_image = Image('background.jpg', scale=Scale.FILL,
                    width=200*MM, height=150*MM)

# Custom scaling with rotation
rotated_image = Image('diagram.png', scale=1.2, rotate=45, 
                     limit_width=150*MM)

from rinohtype.image import InlineImage
from rinohtype.text import MixedStyledText, SingleStyledText
from rinohtype.dimension import PT

# Inline image within text
icon = InlineImage('icon.png', height=12*PT, baseline=2*PT)

text_with_icon = MixedStyledText([
    SingleStyledText("Click the "),
    icon,
    SingleStyledText(" icon to continue.")
])

from rinohtype.draw import Rectangle, Polygon, Line, ShapeStyle, Stroke
from rinohtype.color import Color, BLUE, RED
from rinohtype.dimension import PT, MM

# Rectangle with styling
rect_style = ShapeStyle(
    fill_color=Color(0.8, 0.8, 1.0),  # Light blue fill
    stroke_color=BLUE,                 # Blue border
    stroke_width=2*PT                  # 2pt border width
)

rectangle = Rectangle((10*MM, 10*MM), 50*MM, 30*MM, style=rect_style)

# Polygon (triangle)
triangle_points = [
    (0*MM, 0*MM),
    (20*MM, 0*MM), 
    (10*MM, 20*MM)
]

triangle_style = ShapeStyle(
    fill_color=RED,
    stroke_color=Color(0.5, 0, 0),
    stroke_width=1*PT
)

triangle = Polygon(triangle_points, style=triangle_style)

# Line with custom stroke
line_stroke = Stroke(3*PT, Color(0, 0.5, 0), dash_pattern=[5*PT, 2*PT])
line = Line((0*MM, 0*MM), (50*MM, 25*MM), style=line_stroke)

from rinohtype.image import BackgroundImage

# Page background
page_bg = BackgroundImage('watermark.png', 
                         position='center',
                         repeat='no-repeat',
                         opacity=0.1)

# Repeating pattern background
pattern_bg = BackgroundImage('pattern.png',
                           position='top-left',
                           repeat='repeat',
                           opacity=0.3)

from rinohtype.color import Color, HexColor, Gray

# RGB colors
red = Color(1.0, 0.0, 0.0)
green = Color(0.0, 1.0, 0.0) 
blue = Color(0.0, 0.0, 1.0)

# Hex colors
brand_color = HexColor('#FF6B35')
accent_color = HexColor('#1A1A1A')

# Grayscale
light_gray = Gray(0.8)
dark_gray = Gray(0.2)

# Colors with transparency
semi_transparent = Color(1.0, 0.0, 0.0, alpha=0.5)  # 50% transparent red
translucent_gray = Gray(0.5, alpha=0.3)              # 30% transparent gray

# Color operations
darker_red = red.with_alpha(0.7)  # Same color, different transparency

from rinohtype.draw import Shape, ShapeStyle

class CustomShape(Shape):
    """Custom shape implementation."""
    
    def __init__(self, parameters, **kwargs):
        super().__init__(**kwargs)
        self.parameters = parameters
    
    def render(self, container, descender, state=None, first_line_only=False):
        # Custom rendering logic
        # Use container's graphics context to draw custom shape
        pass

# Use custom shape
custom_style = ShapeStyle(
    fill_color=Color(0.2, 0.8, 0.4),
    stroke_width=1*PT
)

custom_shape = CustomShape({'size': 20*MM}, style=custom_style)

from rinohtype.image import ListOfFigures, ListOfFiguresSection

# Create figures throughout document
figure1 = Figure(Image('chart1.png'), Caption("Sales Data"), id='fig-sales')
figure2 = Figure(Image('chart2.png'), Caption("Revenue Trends"), id='fig-revenue')

# Generate list of figures
lof_section = ListOfFiguresSection([
    Heading("List of Figures"),
    ListOfFigures()
])

from rinohtype.flowable import GroupedFlowables

# Combine multiple graphic elements
graphics_group = GroupedFlowables([
    Rectangle((0*MM, 0*MM), 100*MM, 5*MM, 
             style=ShapeStyle(fill_color=BLUE)),
    
    Image('logo.png', width=30*MM, height=20*MM),
    
    Rectangle((70*MM, 0*MM), 30*MM, 20*MM,
             style=ShapeStyle(fill_color=Gray(0.9), 
                            stroke_color=BLACK, 
                            stroke_width=1*PT))
])