CrImage::Draw

Draws an arc (portion of a circle).

Parameters:

• img : The image to draw on
• center : Center point of the arc
• radius : Radius in pixels
• start_angle : Starting angle in radians (0 = right, PI/2 = down)
• end_angle : Ending angle in radians
• style : Arc appearance settings

Draws a line with arrow heads.

Example:

# Simple arrow
style = CrImage::Draw::ArrowStyle.single(CrImage::Color::BLACK)
CrImage::Draw.arrow(img, CrImage.point(50, 100), CrImage.point(200, 100), style)

# Double-headed arrow
style = CrImage::Draw::ArrowStyle.double(CrImage::Color::RED, thickness: 3)
CrImage::Draw.arrow(img, CrImage.point(50, 150), CrImage.point(200, 150), style)

Blends two colors using the specified blend mode.

Draws a bracket annotation (curly brace style).

Example:

style = CrImage::Draw::BracketStyle.new(color: CrImage::Color::BLACK)
CrImage::Draw.bracket(img, p1, p2, style, side: :right)

Draws a callout box with a leader line pointing to a target.

Example:

style = CrImage::Draw::CalloutStyle.new(
  background: CrImage::Color::WHITE,
  border: CrImage::Color::BLACK
)
CrImage::Draw.callout(img, "Note: Important!", box_pos, target_pos, style)

Draws a circle using the midpoint circle algorithm.

Supports both outlined and filled circles with optional anti-aliasing. The algorithm is efficient and produces symmetric circles.

Parameters:

• img : The image to draw on
• center : Center point of the circle
• radius : Circle radius in pixels (must be non-negative)
• style : Circle appearance settings (color, fill, anti-aliasing)

Raises: ArgumentError if radius is negative

Example:

img = CrImage.rgba(400, 300)
style = CrImage::Draw::CircleStyle.new(CrImage::Color.rgb(0, 255, 0), filled: true)
CrImage::Draw.circle(img, CrImage.point(200, 150), 50, style)

Draws a color scale bar (gradient legend) for heatmaps.

Parameters:

• img : The image to draw on
• position : Top-left corner of the scale
• min_value : Minimum value label
• max_value : Maximum value label
• gradient : Gradient to display
• style : Scale appearance settings
• font : Font for labels (optional)

Example:

gradient = CrImage::Draw::LinearGradient.new(...)
style = CrImage::Draw::ColorScaleStyle.new(width: 150, height: 15)
CrImage::Draw.color_scale(img, CrImage.point(10, 10), 0.0, 100.0, gradient, style, font)

Draws a cubic bezier curve (two control points).

Parameters:

• img : The image to draw on
• p0 : Start point
• p1 : First control point
• p2 : Second control point
• p3 : End point
• style : Bezier curve appearance settings

Draws a dashed or dotted line.

Parameters:

• img : The image to draw on
• p1 : Starting point
• p2 : Ending point
• style : Dashed line appearance settings

Draws a data label with optional background box.

Useful for labeling data points on charts.

Parameters:

• img : The image to draw on
• text_str : Label text
• position : Position for the label
• font : Font for the label
• font_size : Font size (for calculating box size)
• text_color : Text color
• background : Optional background color
• padding : Padding around text (if background)

Draws a dimension line with measurements.

Example:

style = CrImage::Draw::DimensionStyle.new(color: CrImage::Color::BLACK)
CrImage::Draw.dimension_line(img, p1, p2, "100 px", style, face, offset: 30)

Draws a source image onto a destination image using Porter-Duff composition.

This is a convenience method that calls draw_mask with no mask. The rectangle r in the destination is filled with pixels from the source starting at point sp, using the specified composition operator.

Parameters:

• dst : Destination image to draw onto
• r : Rectangle in destination to fill
• src : Source image to draw from
• sp : Starting point in source image
• op : Porter-Duff composition operator (e.g., OVER, SRC)

Example:

background = CrImage.rgba(400, 300, CrImage::Color.rgb(255, 255, 255))
logo = CrImage::PNG.read("logo.png")
CrImage::Draw.draw(background, logo.bounds, logo, CrImage.point(0, 0), CrImage::Draw::Op::OVER)

Draws a source image onto a destination with an optional mask using Porter-Duff composition.

Aligns r.min in dst with sp in src and mp in mask, then replaces the rectangle r in dst with the result of a Porter-Duff composition. A nil mask is treated as fully opaque. The mask's alpha channel controls the opacity of the source pixels.

Parameters:

• dst : Destination image to draw onto
• r : Rectangle in destination to fill
• src : Source image to draw from
• sp : Starting point in source image
• mask : Optional mask image (nil for no mask)
• mp : Starting point in mask image
• op : Porter-Duff composition operator

Example:

background = CrImage.rgba(400, 300)
sprite = CrImage::PNG.read("sprite.png")
mask = CrImage::PNG.read("mask.png")
CrImage::Draw.draw_mask(background, sprite.bounds, sprite, CrImage.point(0, 0),
  mask, CrImage.point(0, 0), CrImage::Draw::Op::OVER)

Draws an ellipse using the midpoint ellipse algorithm.

Supports both outlined and filled ellipses with optional anti-aliasing. The algorithm efficiently handles ellipses of any aspect ratio.

Parameters:

• img : The image to draw on
• center : Center point of the ellipse
• rx : Horizontal radius in pixels (must be non-negative)
• ry : Vertical radius in pixels (must be non-negative)
• style : Ellipse appearance settings (color, fill, anti-aliasing)

Raises: ArgumentError if either radius is negative

Example:

img = CrImage.rgba(400, 300)
style = CrImage::Draw::CircleStyle.new(CrImage::Color.rgb(0, 0, 255), filled: false)
CrImage::Draw.ellipse(img, CrImage.point(200, 150), 80, 50, style)

Fills the area between two bezier curves (for Sankey diagrams).

Creates a filled band shape bounded by two cubic bezier curves. The top curve goes from left to right, bottom curve goes from right to left to form a closed shape.

Parameters:

• img : The image to draw on
• top_curve : Top edge bezier (p0, ctrl1, ctrl2, p1)
• bottom_curve : Bottom edge bezier (p0, ctrl1, ctrl2, p1)
• color : Fill color
• segments : Curve resolution (default: 32)
• anti_alias : Enable anti-aliased edges (default: false)

Example:

# Sankey flow band
top = {
  CrImage.point(100, 100), # start
  CrImage.point(200, 100), # ctrl1
  CrImage.point(300, 150), # ctrl2
  CrImage.point(400, 150), # end
}
bottom = {
  CrImage.point(100, 130), # start
  CrImage.point(200, 130), # ctrl1
  CrImage.point(300, 180), # ctrl2
  CrImage.point(400, 180), # end
}
CrImage::Draw.fill_bezier_band(img, top, bottom, CrImage::Color::BLUE)

Fills the area between two bezier curves (tuple version).

Fills a rectangle with a conic/angular gradient.

Creates a color transition that sweeps around a center point based on angle. Useful for gauge charts, color wheels, and progress indicators.

Parameters:

• img : The image to draw on
• rect : Rectangle area to fill with gradient
• gradient : Conic gradient definition with center, color stops, and start angle

Example:

# Gauge-style gradient (green to yellow to red)
img = CrImage.rgba(400, 400)
gradient = CrImage::Draw::ConicGradient.new(
  CrImage.point(200, 200),
  [
    CrImage::Draw::ColorStop.new(0.0, CrImage::Color.rgb(0, 255, 0)),   # Green
    CrImage::Draw::ColorStop.new(0.5, CrImage::Color.rgb(255, 255, 0)), # Yellow
    CrImage::Draw::ColorStop.new(1.0, CrImage::Color.rgb(255, 0, 0)),   # Red
  ],
  start_angle: -Math::PI # Start from left
)
CrImage::Draw.fill_conic_gradient(img, img.bounds, gradient)

Fills a ring (donut shape) with a conic gradient.

Combines angular gradient with ring shape - perfect for gauge charts. Only fills pixels between inner_radius and outer_radius.

Parameters:

• img : The image to draw on
• center : Center point of the ring
• inner_radius : Inner radius (hole size)
• outer_radius : Outer radius
• gradient : Conic gradient for coloring
• start_angle : Starting angle in radians (default: 0)
• end_angle : Ending angle in radians (default: 2π for full circle)

Example:

# Gauge chart with gradient fill
gradient = CrImage::Draw::ConicGradient.new(
  CrImage.point(200, 200),
  [
    CrImage::Draw::ColorStop.new(0.0, CrImage::Color.rgb(0, 255, 0)),
    CrImage::Draw::ColorStop.new(1.0, CrImage::Color.rgb(255, 0, 0)),
  ],
  start_angle: -Math::PI * 0.75
)
CrImage::Draw.fill_conic_ring(img, CrImage.point(200, 200), 60, 100, gradient,
  start_angle: -Math::PI * 0.75, end_angle: Math::PI * 0.75)

Fills a rectangle with a linear gradient.

Creates a smooth color transition between gradient stops along a line from the start point to the end point. Colors are interpolated in RGB space.

Parameters:

• img : The image to draw on
• rect : Rectangle area to fill with gradient
• gradient : Linear gradient definition with start/end points and color stops

Example:

img = CrImage.rgba(400, 300)
gradient = CrImage::Draw::LinearGradient.new(
  CrImage.point(0, 0),
  CrImage.point(400, 0),
  [
    {0.0, CrImage::Color.rgb(255, 0, 0)},
    {1.0, CrImage::Color.rgb(0, 0, 255)},
  ]
)
CrImage::Draw.fill_linear_gradient(img, img.bounds, gradient)

Fills a path with a solid color.

Uses scanline fill algorithm on the flattened path. For anti-aliased fills, use fill_path_aa.

Parameters:

• img : The image to draw on
• path : The path to fill
• color : Fill color

Example:

path = CrImage::Draw::Path.new
  .move_to(100, 50)
  .bezier_to(150, 50, 200, 100, 200, 150)
  .line_to(100, 150)
  .close
CrImage::Draw.fill_path(img, path, CrImage::Color::BLUE)

Fills a path with anti-aliased edges.

Uses signed area coverage for smooth edges.

Parameters:

• img : The image to draw on
• path : The path to fill
• color : Fill color

Fills a path with a color using the specified blend mode.

Fills a path with a gradient.

Fills a path with a pattern.

Fills a pie slice (filled arc) with a pattern.

Useful for accessible pie charts where color alone shouldn't distinguish slices.

Parameters:

• img : The image to draw on
• center : Center point of the pie
• radius : Radius in pixels
• start_angle : Starting angle in radians (0 = right, PI/2 = down)
• end_angle : Ending angle in radians
• pattern : Fill pattern

Example:

pattern = CrImage::Draw::Pattern.diagonal(CrImage::Color::BLUE, spacing: 6)
CrImage::Draw.fill_pie_pattern(img, center, 100, 0.0, Math::PI/2, pattern)

Fills a polygon with anti-aliased edges.

Parameters:

• img : The image to draw on
• points : Array of polygon vertices
• color : Fill color

Example:

points = [
  CrImage.point(100, 50),
  CrImage.point(200, 150),
  CrImage.point(50, 150),
]
CrImage::Draw.fill_polygon_aa(img, points, CrImage::Color::RED)

Fills a polygon with a color using the specified blend mode.

Example:

# Overlapping semi-transparent shapes with multiply blend
CrImage::Draw.fill_polygon_blended(img, points, color, CrImage::Draw::BlendMode::Multiply)

Fills a polygon with a linear gradient.

Parameters:

• img : The image to draw on
• points : Array of polygon vertices
• gradient : Linear gradient definition

Example:

points = [CrImage.point(100, 50), CrImage.point(200, 150), CrImage.point(50, 150)]
gradient = CrImage::Draw::LinearGradient.new(
  CrImage.point(50, 50), CrImage.point(200, 150),
  [CrImage::Draw::ColorStop.new(0.0, CrImage::Color::RED),
   CrImage::Draw::ColorStop.new(1.0, CrImage::Color::BLUE)]
)
CrImage::Draw.fill_polygon_gradient(img, points, gradient)

Fills a polygon with a radial gradient.

Fills a polygon with a pattern.

Example:

pattern = CrImage::Draw::Pattern.diagonal(CrImage::Color::BLUE, spacing: 6)
CrImage::Draw.fill_polygon_pattern(img, points, pattern)

Fills a rectangle with a radial gradient.

Creates a circular color transition radiating from a center point. Colors are interpolated in RGB space based on distance from center.

Parameters:

• img : The image to draw on
• rect : Rectangle area to fill with gradient
• gradient : Radial gradient definition with center, radius, and color stops

Example:

img = CrImage.rgba(400, 300)
gradient = CrImage::Draw::RadialGradient.new(
  CrImage.point(200, 150),
  150,
  [
    {0.0, CrImage::Color.rgb(255, 255, 0)},
    {1.0, CrImage::Color.rgb(255, 0, 0)},
  ]
)
CrImage::Draw.fill_radial_gradient(img, img.bounds, gradient)

Fills a rectangle with a pattern.

Fills a ring slice (donut segment) with a pattern.

Useful for accessible donut charts where color alone shouldn't distinguish slices.

Parameters:

• img : The image to draw on
• center : Center point of the ring
• inner_radius : Inner radius in pixels (hole size)
• outer_radius : Outer radius in pixels
• start_angle : Starting angle in radians
• end_angle : Ending angle in radians
• pattern : Fill pattern

Example:

pattern = CrImage::Draw::Pattern.crosshatch(CrImage::Color::RED, spacing: 8)
CrImage::Draw.fill_ring_pattern(img, center, 50, 100, 0.0, Math::PI/2, pattern)

Draws a hexagon (flat-top by default)

Draws a chart legend box with color swatches and labels.

Parameters:

• img : The image to draw on
• position : Top-left corner of the legend
• items : Array of legend items (label + color/pattern)
• style : Legend appearance settings
• font : Font face for labels (optional)

Returns: Rectangle bounds of the drawn legend

Example:

items = [
  CrImage::Draw::LegendItem.new("Sales", CrImage::Color::BLUE),
  CrImage::Draw::LegendItem.new("Costs", CrImage::Color::RED),
]
style = CrImage::Draw::LegendStyle.new(background: CrImage::Color::WHITE)
CrImage::Draw.legend_box(img, CrImage.point(10, 10), items, style, font)

Draws a line from one point to another.

Supports multiple rendering modes based on style settings:

• Thin lines (thickness=1, no anti-aliasing): Uses fast Bresenham algorithm
• Thick lines: Draws parallel lines with perpendicular offset
• Anti-aliased lines: Uses Wu's algorithm for smooth edges
• Thick anti-aliased lines: Uses polygon-based stroke with AA edges

Parameters:

• img : The image to draw on
• p1 : Starting point
• p2 : Ending point
• style : Line appearance settings (color, thickness, anti-aliasing)

Example:

img = CrImage.rgba(400, 300)
style = CrImage::Draw::LineStyle.new(CrImage::Color.rgb(255, 0, 0), thickness: 2)
CrImage::Draw.line(img, CrImage.point(10, 10), CrImage.point(100, 100), style)

Draws a marker at the specified position.

Example:

# Scatter plot markers
style = CrImage::Draw::MarkerStyle.filled(CrImage::Draw::MarkerType::Circle, CrImage::Color::RED)
data_points.each do |point|
  CrImage::Draw.marker(img, point, style)
end

Draw multiple markers at once (for scatter plots)

Draws a pentagon

Draws a pie slice (filled arc with lines to center).

Parameters:

• img : The image to draw on
• center : Center point of the pie
• radius : Radius in pixels
• start_angle : Starting angle in radians
• end_angle : Ending angle in radians
• style : Pie appearance settings

Draws a polygon from an array of points.

Supports both outlined and filled polygons. Filled polygons use scanline filling for efficiency. Requires at least 3 points to form a valid polygon.

Parameters:

• img : The image to draw on
• points : Array of points defining the polygon vertices
• style : Polygon appearance settings (color, fill, outline)

Raises: ArgumentError if fewer than 3 points are provided

Example:

img = CrImage.rgba(400, 300)
triangle = [
  CrImage.point(200, 50),
  CrImage.point(100, 200),
  CrImage.point(300, 200),
]
style = CrImage::Draw::PolygonStyle.new(CrImage::Color.rgb(255, 255, 0), filled: true)
CrImage::Draw.polygon(img, triangle, style)

Draws connected line segments through an array of points.

Parameters:

• img : The image to draw on
• points : Array of points to connect
• style : Line appearance settings

Example:

points = [CrImage.point(10, 10), CrImage.point(50, 30), CrImage.point(90, 20)]
style = CrImage::Draw::LineStyle.new(CrImage::Color::BLUE, thickness: 2)
CrImage::Draw.polyline(img, points, style)

Draws a quadratic bezier curve (one control point).

Parameters:

• img : The image to draw on
• p0 : Start point
• p1 : Control point
• p2 : End point
• style : Bezier curve appearance settings

Draws a rectangle with optional rounded corners.

Parameters:

• img : The image to draw on
• rect : Rectangle bounds
• style : Rectangle appearance settings

Draws a regular polygon (equilateral triangle, square, pentagon, hexagon, etc.)

Parameters:

• img : The image to draw on
• center : Center point of the polygon
• radius : Distance from center to vertices
• sides : Number of sides (3 = triangle, 4 = square, 5 = pentagon, etc.)
• style : Polygon appearance settings
• rotation : Rotation angle in radians (default 0, pointing right)

Raises: ArgumentError if sides < 3 or radius < 0

Draws a ring slice (donut segment) between two radii.

This is useful for donut charts where you need a hollow center. The slice is drawn between inner_radius and outer_radius within the specified angle range.

Parameters:

• img : The image to draw on
• center : Center point of the ring
• inner_radius : Inner radius in pixels (hole size)
• outer_radius : Outer radius in pixels
• start_angle : Starting angle in radians (0 = right, PI/2 = down)
• end_angle : Ending angle in radians
• style : Ring appearance settings

Example:

# Draw a donut chart segment
style = CrImage::Draw::RingStyle.new(CrImage::Color::RED, fill: true)
CrImage::Draw.ring_slice(img, center, 50, 100, 0.0, Math::PI/2, style)

Draws a rounded rectangle with per-corner radius control.

Example:

# Bar chart with rounded top only
CrImage::Draw.rounded_rect(img, rect,
  CrImage::Draw::CornerRadii.top(10),
  fill: CrImage::Color::BLUE)

# Custom per-corner radii
CrImage::Draw.rounded_rect(img, rect,
  CrImage::Draw::CornerRadii.new(top_left: 20, top_right: 5, bottom_right: 20, bottom_left: 5),
  fill: CrImage::Color::RED, stroke: CrImage::Color::BLACK)

Draws a bezier spline through multiple points using Catmull-Rom interpolation.

Parameters:

• img : The image to draw on
• points : Array of points to pass through
• style : Bezier curve appearance settings
• tension : Curve tension (0.0 = sharp corners, 1.0 = smooth)

Flattens a Catmull-Rom spline to an array of points.

Useful for fills, clipping paths, hit testing, or any operation that needs the interpolated points without drawing.

Parameters:

• points : Control points the spline passes through
• tension : Curve tension (0.0 = sharp corners, 1.0 = smooth)
• segments_per_span : Number of line segments per curve span (default: 16)

Returns: Array of interpolated points along the spline

Example:

control_points = [CrImage.point(10, 50), CrImage.point(50, 20), CrImage.point(90, 60)]
curve_points = CrImage::Draw.spline_flatten(control_points, tension: 0.5)
# Use curve_points for fills, hit testing, etc.

Draws a square (rotated 45° by default to have flat top)

Draws a simple brace/bracket (square style).

Strokes an arc with gradient color.

Example:

# Progress arc (green to red)
stops = [
  CrImage::Draw::ColorStop.new(0.0, CrImage::Color::GREEN),
  CrImage::Draw::ColorStop.new(1.0, CrImage::Color::RED),
]
CrImage::Draw.stroke_arc_gradient(img, center, radius, 0.0, Math::PI, stops, thickness: 5)

Strokes a bezier curve with gradient color.

Strokes a line with gradient color.

Strokes a path outline.

Parameters:

• img : The image to draw on
• path : The path to stroke
• style : Stroke appearance settings

Strokes a path with a gradient color.

The gradient is applied along the path length, useful for:

• Progress indicators
• Line charts showing value intensity
• Decorative effects

Example:

path = CrImage::Draw::Path.new
  .move_to(50, 100)
  .bezier_to(150, 50, 250, 150, 350, 100)

stops = [
  CrImage::Draw::ColorStop.new(0.0, CrImage::Color::GREEN),
  CrImage::Draw::ColorStop.new(0.5, CrImage::Color::YELLOW),
  CrImage::Draw::ColorStop.new(1.0, CrImage::Color::RED),
]

CrImage::Draw.stroke_path_gradient(img, path, stops, thickness: 3)

Strokes a ring/donut arc with gradient (for gauge charts).

Draws text on an image at the specified position.

This is a convenience method that creates a Font::Drawer internally.

Parameters:

• img : The image to draw on
• text : The text string to draw
• position : Position for the text baseline
• face : Font face to use
• size : Font size (used to scale if face was created at different size)
• color : Text color

Example:

font = FreeType::TrueType.load("font.ttf")
face = FreeType::TrueType.new_face(font, 24.0)
CrImage::Draw.text(img, "Hello!", CrImage.point(10, 50), face, CrImage::Color::BLACK)

Draws text along a circular arc.

Parameters:

• img : Image to draw on
• text : Text to render
• center : Center of the arc
• radius : Radius of the arc (text baseline position)
• start_angle : Starting angle in radians
• end_angle : Ending angle in radians
• face : Font face
• color : Text color
• align : Text alignment on arc (:start, :center, :end)
• text_offset : Radial offset from arc (negative = toward center, positive = away)

Draws text along a curved path (bezier curve or arc).

Each character is positioned and rotated to follow the curve tangent. Useful for circular labels around pie/donut charts, curved axis labels.

Parameters:

• img : Image to draw on
• text : Text to render
• curve : Cubic bezier curve to follow
• face : Font face
• color : Text color
• offset : Starting position along curve (0.0 = auto-center)
• text_offset : Perpendicular offset from curve (negative = above, positive = below)

Example:

# Text along a bezier curve, positioned above the line
curve = CrImage::Draw::CubicBezier.new(
  {50.0, 200.0}, {150.0, 50.0}, {250.0, 50.0}, {350.0, 200.0}
)
CrImage::Draw.text_on_curve(img, "Hello Curved World!", curve, face, color, text_offset: -20)

Draws a thick anti-aliased curve through multiple points.

This is optimized for thick curves (like KDE lines in histograms) and produces smooth results without gaps or artifacts.

Parameters:

• img : The image to draw on
• points : Array of points the curve passes through
• color : Curve color
• thickness : Line thickness in pixels
• tension : Curve tension (0.0 = sharp corners, 1.0 = smooth)

Example:

points = [CrImage.point(10, 50), CrImage.point(50, 20), CrImage.point(90, 60)]
CrImage::Draw.thick_curve(img, points, CrImage::Color::BLUE, 4)

Draws an equilateral triangle

Draws an X axis with ticks and optional labels.

Parameters:

• img : The image to draw on
• start_point : Left end of the axis
• end_point : Right end of the axis
• min_value : Minimum axis value
• max_value : Maximum axis value
• style : Axis appearance settings
• font : Font for labels (optional)
• chart_height : Height of chart area for grid lines (optional)

Draws a Y axis with ticks and optional labels.

Parameters:

• img : The image to draw on
• start_point : Bottom end of the axis
• end_point : Top end of the axis
• min_value : Minimum axis value
• max_value : Maximum axis value
• style : Axis appearance settings
• font : Font for labels (optional)
• chart_width : Width of chart area for grid lines (optional)