module Celestine::Docs::A_GETTING_STARTED::OVERVIEW

Overview

Getting Started & System Overview

Celestine is a fast, pure-Crystal library for programmatic SVG generation. It provides both a fluent builder DSL and a strongly-typed object model for creating, transforming, styling, and animating SVG graphics.

Executive Summary & Key Topics

Topic	Method / Anchor	Description
Introduction & Architecture	`.topic_01_introduction`	Core concepts and structural layout of Celestine.

Related Guides & Source References

src/celestine.cr
src/drawables/
src/effects/

Defined in:

docs/a_getting_started/overview.cr

Class Method Summary

.topic_01_introduction : Nil
Introduction & Architecture: Core concepts and structural layout of Celestine.

Class Method Detail

def self.topic_01_introduction : Nil #

Introduction & Architecture: Core concepts and structural layout of Celestine.

Celestine organizes SVG generation around three pillars:

Drawables: Core SVG elements such as <svg>, <rect>, <circle>, <ellipse>, <line>, <polygon>, <polyline>, <path>, <text>, <image>, and <use>.
Containers & Definitions: <g>, <a>, <defs>, <mask>, <marker>, <pattern>, <linearGradient>, and <radialGradient>.
Effects & Animations: Declarative SVG filters (<filter>, <feGaussianBlur>, etc.) and SMIL animations (<animate>, <animateMotion>, <animateTransform>).

Component	Module / Directory	Role
Root DSL	`Celestine.draw`	Builder entrypoint yielding `Celestine::Svg`
Drawables	`src/drawables/`	Concrete SVG tag implementations inheriting `Celestine::Drawable`
Effects	`src/effects/`	Gradients, filters, masks, markers, patterns, animations
Math	`src/math/`	`Point`, `FPoint`, and coordinate manipulation

Working Examples

require "celestine"

svg = Celestine.draw do |ctx|
  ctx.view_box = {x: 0, y: 0, w: 200, h: 200}
  ctx.rectangle do |r|
    r.x = 10
    r.y = 10
    r.width = 180
    r.height = 180
    r.fill = "blue"
    r.radius_x = 8
    r.radius_y = 8
  end
end

puts svg

Common Pitfalls & Safety Caveats

Warning: Never forget to set view_box or width/height on the root SVG for proper scaling.
Warning: Remember that units default to pixels if none are specified.

Frequently Asked Questions (FAQ)

Q: How do I stream SVG directly to an IO instead of allocating a String? A: Call Celestine.draw(io) { |ctx| ... } to render directly to any IO object.
Q: Can I use Celestine without the DSL block syntax? A: Yes! Every drawable and effect is a standard Crystal class (e.g. Celestine::Rectangle.new) that can be instantiated and appended to any container.

[View source]