0
# Graphics and Images
1
2
Comprehensive graphics system providing image handling, drawing primitives, shapes, colors, and graphical elements for rich document content. The graphics engine supports various image formats, vector drawing, and advanced visual elements with precise positioning and styling.
3
4
## Capabilities
5
6
### Image Handling
7
8
Core image functionality supporting various formats, scaling, positioning, and integration with document layout.
9
10
```python { .api }
11
class Image(Flowable):
12
"""
13
Block-level image element with comprehensive formatting options.
14
15
Parameters:
16
- filename_or_file: str or file-like, path to image file or open file
17
- scale: float or Scale, scaling factor or scaling mode
18
- width: Dimension, explicit width (overrides scale)
19
- height: Dimension, explicit height (overrides scale)
20
- dpi: float, resolution for pixel-based images
21
- rotate: float, rotation angle in degrees
22
- limit_width: Dimension, maximum width constraint
23
- alt: str, alternative text for accessibility
24
- id: str, unique identifier
25
- style: Style, styling for the image
26
- parent: parent element
27
- source: source location information
28
"""
29
def __init__(self, filename_or_file, scale=1.0, width=None, height=None,
30
dpi=None, rotate=0, limit_width=None, alt=None,
31
id=None, style=None, parent=None, source=None): ...
32
33
@property
34
def filename(self): ... # Image file path
35
@property
36
def image_size(self): ... # Original image dimensions
37
@property
38
def scaled_size(self): ... # Final scaled dimensions
39
40
def get_intrinsic_size(self): ... # Get natural image size
41
42
class InlineImage(InlineFlowable):
43
"""
44
Inline image that flows with text content.
45
46
Similar to Image but designed for embedding within paragraphs
47
and other text-based content.
48
49
Parameters:
50
- filename_or_file: str or file-like, image source
51
- scale: float or Scale, scaling options
52
- width: Dimension, explicit width
53
- height: Dimension, explicit height
54
- baseline: Dimension, baseline alignment offset
55
- alt: str, alternative text
56
- style: InlineStyle, styling for inline context
57
- parent: parent element
58
"""
59
def __init__(self, filename_or_file, scale=1.0, width=None, height=None,
60
baseline=None, alt=None, style=None, parent=None): ...
61
62
class BackgroundImage(Image):
63
"""
64
Background image for pages or containers.
65
66
Provides background imagery with positioning, scaling, and
67
repeat options for page backgrounds and decorative elements.
68
69
Parameters:
70
- filename_or_file: str or file-like, background image source
71
- position: str, positioning ('center', 'top-left', etc.)
72
- repeat: str, repeat mode ('no-repeat', 'repeat', 'repeat-x', 'repeat-y')
73
- opacity: float, background opacity (0.0 to 1.0)
74
- **kwargs: additional Image parameters
75
"""
76
def __init__(self, filename_or_file, position='center', repeat='no-repeat',
77
opacity=1.0, **kwargs): ...
78
```
79
80
### Image Configuration
81
82
Image-related configuration classes and scaling options for flexible image handling.
83
84
```python { .api }
85
class ImageArgs:
86
"""
87
Container for image arguments and configuration.
88
89
Encapsulates image parameters for consistent handling across
90
different image types and processing contexts.
91
92
Parameters:
93
- scale: float or Scale, scaling configuration
94
- width: Dimension, target width
95
- height: Dimension, target height
96
- dpi: float, resolution setting
97
- rotate: float, rotation angle
98
"""
99
def __init__(self, scale=1.0, width=None, height=None, dpi=None, rotate=0): ...
100
101
class Scale:
102
"""
103
Image scaling modes and options.
104
105
Provides different strategies for sizing images within layout
106
constraints while maintaining aspect ratios and quality.
107
"""
108
109
# Scaling constants
110
FIT = 'fit' # Scale to fit within bounds, preserve aspect ratio
111
FILL = 'fill' # Scale to fill bounds, may crop, preserve aspect ratio
112
STRETCH = 'stretch' # Scale to exact bounds, ignore aspect ratio
113
114
def __init__(self, mode, factor=1.0):
115
"""
116
Create scaling configuration.
117
118
Parameters:
119
- mode: str, scaling mode ('fit', 'fill', 'stretch', or numeric)
120
- factor: float, additional scaling factor
121
"""
122
...
123
```
124
125
### Figures and Captions
126
127
Figure system for images with captions, numbering, and list-of-figures integration.
128
129
```python { .api }
130
class Figure(Float):
131
"""
132
Image or content with caption as a floating figure.
133
134
Provides numbered figures with captions that can float to
135
appropriate positions and integrate with lists of figures.
136
137
Parameters:
138
- image_or_flowable: Image or other Flowable for figure content
139
- caption: Caption or str, figure caption
140
- id: str, unique identifier for cross-referencing
141
- style: FigureStyle, styling for the figure
142
- parent: parent element
143
- source: source location information
144
"""
145
def __init__(self, image_or_flowable, caption=None, id=None,
146
style=None, parent=None, source=None): ...
147
148
@property
149
def number(self): ... # Figure number
150
@property
151
def formatted_number(self): ... # Formatted figure number
152
153
class Caption(Paragraph):
154
"""
155
Caption for figures, tables, and other captioned content.
156
157
Specialized paragraph for captions with automatic numbering,
158
special formatting, and integration with lists of figures/tables.
159
160
Parameters:
161
- content: str or list, caption text content
162
- category: str, caption category ('figure', 'table', etc.)
163
- id: str, unique identifier
164
- style: CaptionStyle, caption-specific styling
165
- parent: parent element
166
- source: source location information
167
"""
168
def __init__(self, content, category='figure', id=None,
169
style=None, parent=None, source=None): ...
170
171
class CaptionStyle(Style):
172
"""Style configuration for captions including numbering and formatting."""
173
174
number_format = Attribute(NumberFormat) # Number formatting
175
number_separator = Attribute(str) # Separator between number and text
176
177
class FigureStyle(Style):
178
"""Style configuration for figures including positioning and spacing."""
179
```
180
181
### Lists of Figures
182
183
System for generating lists of figures and managing figure references.
184
185
```python { .api }
186
class ListOfFigures(Section):
187
"""
188
Automatically generated list of all figures in document.
189
190
Creates a section containing links to all figures with their
191
captions and page numbers.
192
193
Parameters:
194
- id: str, unique identifier
195
- style: Style, styling for the list section
196
- parent: parent element
197
- source: source location information
198
"""
199
def __init__(self, id=None, style=None, parent=None, source=None): ...
200
201
class ListOfFiguresSection(Section):
202
"""Section wrapper for list of figures with proper formatting."""
203
```
204
205
### Drawing Primitives
206
207
Vector drawing system for creating shapes, lines, and geometric elements within documents.
208
209
```python { .api }
210
class Shape(Flowable):
211
"""
212
Base class for vector shapes and drawing primitives.
213
214
Provides foundation for all drawn geometric elements with
215
styling, positioning, and rendering capabilities.
216
217
Parameters:
218
- style: ShapeStyle, styling for the shape
219
- parent: parent element
220
- source: source location information
221
"""
222
def __init__(self, style=None, parent=None, source=None): ...
223
224
class Rectangle(Shape):
225
"""
226
Rectangular shape with customizable dimensions and styling.
227
228
Parameters:
229
- bottom_left: (Dimension, Dimension), bottom-left corner position
230
- width: Dimension, rectangle width
231
- height: Dimension, rectangle height
232
- style: ShapeStyle, styling including fill and stroke
233
- parent: parent element
234
- source: source location information
235
"""
236
def __init__(self, bottom_left, width, height, style=None, parent=None, source=None): ...
237
238
@property
239
def top_right(self): ... # Top-right corner position
240
@property
241
def center(self): ... # Center point
242
243
class Polygon(Shape):
244
"""
245
Multi-point polygon shape.
246
247
Creates closed shape from sequence of points with customizable
248
styling for both fill and stroke properties.
249
250
Parameters:
251
- points: list of (Dimension, Dimension), polygon vertices
252
- style: ShapeStyle, styling for fill and stroke
253
- parent: parent element
254
- source: source location information
255
"""
256
def __init__(self, points, style=None, parent=None, source=None): ...
257
258
@property
259
def points(self): ... # Polygon vertices
260
@property
261
def bounds(self): ... # Bounding rectangle
262
263
class Line(Shape):
264
"""
265
Straight line between two points.
266
267
Parameters:
268
- start: (Dimension, Dimension), line start point
269
- end: (Dimension, Dimension), line end point
270
- style: LineStyle, styling for line appearance
271
- parent: parent element
272
- source: source location information
273
"""
274
def __init__(self, start, end, style=None, parent=None, source=None): ...
275
276
@property
277
def length(self): ... # Line length
278
@property
279
def angle(self): ... # Line angle in degrees
280
```
281
282
### Drawing Styles
283
284
Style classes for controlling the appearance of drawn shapes and lines.
285
286
```python { .api }
287
class ShapeStyle(Style):
288
"""
289
Style configuration for filled shapes.
290
291
Controls both fill and stroke properties for shapes like
292
rectangles, polygons, and other closed figures.
293
"""
294
295
fill_color = Attribute(Color) # Fill color
296
fill_opacity = Attribute(float) # Fill transparency (0.0-1.0)
297
stroke_color = Attribute(Color) # Stroke/border color
298
stroke_width = Attribute(Dimension) # Stroke thickness
299
stroke_opacity = Attribute(float) # Stroke transparency
300
301
class LineStyle(Style):
302
"""
303
Style configuration for lines and strokes.
304
305
Controls appearance of linear elements including thickness,
306
color, dash patterns, and end cap styles.
307
"""
308
309
stroke_color = Attribute(Color) # Line color
310
stroke_width = Attribute(Dimension) # Line thickness
311
stroke_opacity = Attribute(float) # Line transparency
312
line_cap = Attribute(str) # End cap style ('butt', 'round', 'square')
313
line_join = Attribute(str) # Join style ('miter', 'round', 'bevel')
314
dash_pattern = Attribute(list) # Dash pattern [dash_length, gap_length, ...]
315
316
class Stroke:
317
"""
318
Stroke definition for line drawing properties.
319
320
Encapsulates line drawing properties for consistent application
321
across different drawing contexts.
322
323
Parameters:
324
- width: Dimension, stroke thickness
325
- color: Color, stroke color
326
- opacity: float, stroke transparency
327
- dash_pattern: list, dash pattern specification
328
"""
329
def __init__(self, width, color, opacity=1.0, dash_pattern=None): ...
330
```
331
332
### Color System
333
334
Comprehensive color system supporting various color models, transparency, and predefined colors.
335
336
```python { .api }
337
class Color:
338
"""
339
RGBA color with red, green, blue, and alpha components.
340
341
Parameters:
342
- red: float, red component (0.0-1.0)
343
- green: float, green component (0.0-1.0)
344
- blue: float, blue component (0.0-1.0)
345
- alpha: float, alpha/transparency component (0.0-1.0)
346
"""
347
def __init__(self, red, green, blue, alpha=1.0): ...
348
349
@property
350
def rgba(self): ... # (r, g, b, a) tuple
351
@property
352
def r(self): ... # Red component
353
@property
354
def g(self): ... # Green component
355
@property
356
def b(self): ... # Blue component
357
@property
358
def a(self): ... # Alpha component
359
360
def __add__(self, other): ... # Color blending
361
def with_alpha(self, alpha): ... # Create copy with new alpha
362
363
class HexColor(Color):
364
"""
365
Color created from hexadecimal string representation.
366
367
Supports various hex formats including #RGB, #RRGGBB, #RRGGBBAA.
368
369
Parameters:
370
- hex_string: str, hexadecimal color string
371
"""
372
def __init__(self, hex_string): ...
373
374
class Gray(Color):
375
"""
376
Grayscale color with luminance value.
377
378
Convenience class for creating grayscale colors from single
379
luminance value instead of separate RGB components.
380
381
Parameters:
382
- luminance: float, grayscale value (0.0=black, 1.0=white)
383
- alpha: float, transparency (0.0-1.0)
384
"""
385
def __init__(self, luminance, alpha=1.0): ...
386
387
# Predefined colors
388
BLACK = Color(0, 0, 0) # Pure black
389
WHITE = Color(1, 1, 1) # Pure white
390
RED = Color(1, 0, 0) # Pure red
391
GREEN = Color(0, 1, 0) # Pure green
392
BLUE = Color(0, 0, 1) # Pure blue
393
394
# Predefined grays
395
GRAY10 = Gray(0.1) # 10% gray
396
GRAY25 = Gray(0.25) # 25% gray
397
GRAY50 = Gray(0.5) # 50% gray
398
GRAY75 = Gray(0.75) # 75% gray
399
GRAY90 = Gray(0.9) # 90% gray
400
```
401
402
## Usage Examples
403
404
### Basic Image Usage
405
406
```python
407
from rinohtype.image import Image, Figure, Caption
408
from rinohtype.dimension import MM, PT
409
410
# Simple image
411
photo = Image('photo.jpg', scale=0.8, alt="Company photo")
412
413
# Image with explicit dimensions
414
logo = Image('logo.png', width=50*MM, height=20*MM, alt="Company logo")
415
416
# Figure with caption
417
chart_image = Image('sales_chart.png', width=120*MM)
418
chart_caption = Caption("Monthly sales figures for 2024")
419
chart_figure = Figure(chart_image, caption=chart_caption, id='sales-chart')
420
```
421
422
### Advanced Image Scaling
423
424
```python
425
from rinohtype.image import Image, Scale
426
427
# Fit image within bounds while preserving aspect ratio
428
fitted_image = Image('large_image.jpg', scale=Scale.FIT,
429
width=100*MM, height=80*MM)
430
431
# Fill bounds, may crop image
432
filled_image = Image('background.jpg', scale=Scale.FILL,
433
width=200*MM, height=150*MM)
434
435
# Custom scaling with rotation
436
rotated_image = Image('diagram.png', scale=1.2, rotate=45,
437
limit_width=150*MM)
438
```
439
440
### Inline Images
441
442
```python
443
from rinohtype.image import InlineImage
444
from rinohtype.text import MixedStyledText, SingleStyledText
445
from rinohtype.dimension import PT
446
447
# Inline image within text
448
icon = InlineImage('icon.png', height=12*PT, baseline=2*PT)
449
450
text_with_icon = MixedStyledText([
451
SingleStyledText("Click the "),
452
icon,
453
SingleStyledText(" icon to continue.")
454
])
455
```
456
457
### Drawing Shapes
458
459
```python
460
from rinohtype.draw import Rectangle, Polygon, Line, ShapeStyle, Stroke
461
from rinohtype.color import Color, BLUE, RED
462
from rinohtype.dimension import PT, MM
463
464
# Rectangle with styling
465
rect_style = ShapeStyle(
466
fill_color=Color(0.8, 0.8, 1.0), # Light blue fill
467
stroke_color=BLUE, # Blue border
468
stroke_width=2*PT # 2pt border width
469
)
470
471
rectangle = Rectangle((10*MM, 10*MM), 50*MM, 30*MM, style=rect_style)
472
473
# Polygon (triangle)
474
triangle_points = [
475
(0*MM, 0*MM),
476
(20*MM, 0*MM),
477
(10*MM, 20*MM)
478
]
479
480
triangle_style = ShapeStyle(
481
fill_color=RED,
482
stroke_color=Color(0.5, 0, 0),
483
stroke_width=1*PT
484
)
485
486
triangle = Polygon(triangle_points, style=triangle_style)
487
488
# Line with custom stroke
489
line_stroke = Stroke(3*PT, Color(0, 0.5, 0), dash_pattern=[5*PT, 2*PT])
490
line = Line((0*MM, 0*MM), (50*MM, 25*MM), style=line_stroke)
491
```
492
493
### Background Images
494
495
```python
496
from rinohtype.image import BackgroundImage
497
498
# Page background
499
page_bg = BackgroundImage('watermark.png',
500
position='center',
501
repeat='no-repeat',
502
opacity=0.1)
503
504
# Repeating pattern background
505
pattern_bg = BackgroundImage('pattern.png',
506
position='top-left',
507
repeat='repeat',
508
opacity=0.3)
509
```
510
511
### Color Management
512
513
```python
514
from rinohtype.color import Color, HexColor, Gray
515
516
# RGB colors
517
red = Color(1.0, 0.0, 0.0)
518
green = Color(0.0, 1.0, 0.0)
519
blue = Color(0.0, 0.0, 1.0)
520
521
# Hex colors
522
brand_color = HexColor('#FF6B35')
523
accent_color = HexColor('#1A1A1A')
524
525
# Grayscale
526
light_gray = Gray(0.8)
527
dark_gray = Gray(0.2)
528
529
# Colors with transparency
530
semi_transparent = Color(1.0, 0.0, 0.0, alpha=0.5) # 50% transparent red
531
translucent_gray = Gray(0.5, alpha=0.3) # 30% transparent gray
532
533
# Color operations
534
darker_red = red.with_alpha(0.7) # Same color, different transparency
535
```
536
537
### Custom Shape Drawing
538
539
```python
540
from rinohtype.draw import Shape, ShapeStyle
541
542
class CustomShape(Shape):
543
"""Custom shape implementation."""
544
545
def __init__(self, parameters, **kwargs):
546
super().__init__(**kwargs)
547
self.parameters = parameters
548
549
def render(self, container, descender, state=None, first_line_only=False):
550
# Custom rendering logic
551
# Use container's graphics context to draw custom shape
552
pass
553
554
# Use custom shape
555
custom_style = ShapeStyle(
556
fill_color=Color(0.2, 0.8, 0.4),
557
stroke_width=1*PT
558
)
559
560
custom_shape = CustomShape({'size': 20*MM}, style=custom_style)
561
```
562
563
### List of Figures
564
565
```python
566
from rinohtype.image import ListOfFigures, ListOfFiguresSection
567
568
# Create figures throughout document
569
figure1 = Figure(Image('chart1.png'), Caption("Sales Data"), id='fig-sales')
570
figure2 = Figure(Image('chart2.png'), Caption("Revenue Trends"), id='fig-revenue')
571
572
# Generate list of figures
573
lof_section = ListOfFiguresSection([
574
Heading("List of Figures"),
575
ListOfFigures()
576
])
577
```
578
579
### Complex Graphics Layout
580
581
```python
582
from rinohtype.flowable import GroupedFlowables
583
584
# Combine multiple graphic elements
585
graphics_group = GroupedFlowables([
586
Rectangle((0*MM, 0*MM), 100*MM, 5*MM,
587
style=ShapeStyle(fill_color=BLUE)),
588
589
Image('logo.png', width=30*MM, height=20*MM),
590
591
Rectangle((70*MM, 0*MM), 30*MM, 20*MM,
592
style=ShapeStyle(fill_color=Gray(0.9),
593
stroke_color=BLACK,
594
stroke_width=1*PT))
595
])
596
```