# Drawing

Learn how to draw shapes, lines, curves, and text on images in BoxLang.

## Table of Contents

* [Setup & Configuration](#setup--configuration)
* [Drawing Shapes](#drawing-shapes)
* [Drawing Lines](#drawing-lines)
* [Drawing Curves](#drawing-curves)
* [Drawing Text](#drawing-text)
* [Advanced Drawing](#advanced-drawing)
* [Drawing Axis Transformations](#drawing-axis-transformations)

## Setup & Configuration

Before drawing, configure colors, strokes, and rendering options:

### Set Drawing Color

```js
// Named color
img = ImageNew(400, 300, "rgb", "white");
img.setDrawingColor("red");

// Hex color
img.setDrawingColor("#FF0000");
```

**Supported Colors:** `black`, `blue`, `cyan`, `darkgray`, `gray`, `green`, `lightgray`, `magenta`, `orange`, `pink`, `red`, `white`, `yellow`

### Set Background Color

```js
img.setBackgroundColor("white");
img.setBackgroundColor("#F0F0F0");
```

### Configure Stroke (Line Style)

```js
// Configure stroke properties
img.setDrawingStroke({
    width: 3,
    endCaps: "round",        // "butt", "round", "square"
    lineJoins: "round",      // "miter", "round", "bevel"
    miterLimit: 10,
    dashArray: [10, 5],      // Dash pattern
    dashPhase: 0
});
```

**Stroke Properties:**

* **width** - Line thickness in pixels
* **endCaps** - How line ends are drawn
* **lineJoins** - How line corners are drawn
* **miterLimit** - Miter join limit
* **dashArray** - Dash pattern (on, off, on, off...)
* **dashPhase** - Offset for dash pattern

### Set Transparency

```js
// 50% transparency (0-100)
img.setDrawingTransparency(50);

// Fully opaque
img.setDrawingTransparency(100);
```

### Enable Anti-Aliasing

```js
// Smooth edges
img.setAntiAliasing("on");

// Fast rendering (jagged edges)
img.setAntiAliasing("off");
```

## Drawing Shapes

### Draw Rectangle

```js
img = ImageNew(400, 300, "rgb", "white");
img.setDrawingColor("blue");

// Outline rectangle: x, y, width, height, filled
img.drawRect(50, 50, 200, 100, false);

// Filled rectangle
img.drawRect(50, 170, 200, 100, true);

img.write("rectangles.jpg");
```

**BIF Syntax:**

```js
ImageDrawRect(img, x=50, y=50, width=200, height=100, filled=false);
```

### Draw Rounded Rectangle

```js
// Rounded corners: x, y, width, height, arcWidth, arcHeight, filled
img.drawRoundRect(50, 50, 200, 100, 30, 30, false);
```

### Draw Beveled Rectangle (3D Effect)

```js
// 3D beveled rectangle: x, y, width, height, raised, filled
img.drawBeveledRect(50, 50, 200, 100, true, true);

// Lowered bevel
img.drawBeveledRect(50, 170, 200, 100, false, true);
```

### Draw Oval/Circle

```js
// Oval: x, y, width, height, filled
img.drawOval(50, 50, 200, 150, false);

// Circle (width = height)
img.drawOval(100, 100, 100, 100, true);
```

### Clear Rectangle

```js
// Clear region to transparent: x, y, width, height
img.clearRect(50, 50, 100, 100);
```

## Drawing Lines

### Draw Single Line

```js
img.setDrawingColor("black");
img.setDrawingStroke({width: 2});

// Draw line: x1, y1, x2, y2
img.drawLine(50, 50, 350, 250);
```

### Draw Multiple Lines (Polyline)

```js
// Array of x and y coordinates
xCoords = [50, 150, 250, 350];
yCoords = [50, 150, 50, 150];

// Draw polyline: xCoords, yCoords, isPolygon, filled
img.drawLines(xCoords, yCoords, false, false);
```

### Draw Polygon

```js
xCoords = [100, 200, 250, 200, 100, 50];
yCoords = [50, 50, 150, 250, 250, 150];

// Closed polygon outline
img.drawLines(xCoords, yCoords, true, false);

// Filled polygon
img.drawLines(xCoords, yCoords, true, true);
```

### Draw Single Point

```js
// Draw point: x, y
img.drawPoint(200, 150);
```

### Draw Arc

```js
// Arc: x, y, width, height, startAngle, arcAngle, filled
img.drawArc(50, 50, 200, 150, 0, 90, false);

// Pie slice (filled arc)
img.drawArc(50, 50, 200, 150, 0, 90, true);
```

**Angles:**

* 0° = 3 o'clock position
* 90° = 12 o'clock position
* Positive angles go counter-clockwise

## Drawing Curves

### Quadratic Bézier Curve

```js
// Quadratic curve: ctrlX, ctrlY, startX, startY, endX, endY
img.drawQuadraticCurve(200, 50, 50, 150, 350, 150);
```

### Cubic Bézier Curve

```js
// Cubic curve: startX, startY, ctrl1X, ctrl1Y, ctrl2X, ctrl2Y, endX, endY
img.drawCubicCurve(50, 150, 100, 50, 300, 250, 350, 150);
```

## Drawing Text

### Simple Text

```js
img.setDrawingColor("black");

// Draw text: text, x, y
img.drawText("Hello World", 50, 100);
```

### Styled Text

```js
// Draw text with font configuration
img.drawText("Styled Text", 50, 150, {
    font: "Arial",
    size: 24,
    style: "bold",
    underline: false,
    strikeThrough: false
});
```

**Font Configuration:**

* **font** - Font family name (e.g., "Arial", "Times New Roman")
* **size** - Font size in points
* **style** - "plain", "bold", "italic", "bolditalic"
* **underline** - true/false
* **strikeThrough** - true/false

### Text Examples

```js
// Title text
img.setDrawingColor("black");
img.drawText("My Photo Album", 100, 50, {
    font: "Arial",
    size: 36,
    style: "bold"
});

// Subtitle
img.setDrawingColor("gray");
img.drawText("Summer 2025", 100, 90, {
    font: "Arial",
    size: 18,
    style: "italic"
});

// Watermark with transparency
img.setDrawingColor("white");
img.setDrawingTransparency(30);
img.drawText("© 2025 My Company", 20, 280, {
    font: "Arial",
    size: 12
});
```

## Advanced Drawing

### Complex Shape Example

```js
img = ImageNew(500, 400, "rgb", "white");
img.setAntiAliasing("on");

// Draw robot face
img.setDrawingColor("lightgray");
img.drawRoundRect(150, 100, 200, 250, 30, 30, true);

// Eyes
img.setDrawingColor("black");
img.drawOval(180, 150, 50, 50, true);
img.drawOval(270, 150, 50, 50, true);

// Pupils
img.setDrawingColor("blue");
img.drawOval(195, 165, 20, 20, true);
img.drawOval(285, 165, 20, 20, true);

// Mouth
img.setDrawingStroke({width: 3});
img.drawArc(200, 220, 100, 80, 180, 180, false);

img.write("robot.jpg");
```

### Chart/Graph Drawing

```js
img = ImageNew(600, 400, "rgb", "white");
img.setAntiAliasing("on");

// Draw axes
img.setDrawingColor("black");
img.setDrawingStroke({width: 2});
img.drawLine(50, 350, 550, 350);  // X-axis
img.drawLine(50, 50, 50, 350);    // Y-axis

// Draw bars
colors = ["red", "blue", "green", "orange"];
values = [200, 150, 300, 180];

for (i = 1; i <= arrayLen(values); i++) {
    img.setDrawingColor(colors[i]);
    x = 50 + (i * 100);
    height = values[i];
    img.drawRect(x, 350 - height, 80, height, true);
}

img.write("chart.jpg");
```

## Drawing Axis Transformations

These transformations affect the coordinate system for drawing, not the image itself.

### Translate Origin

```js
// Move origin to center of image
img = ImageNew(400, 300, "rgb", "white");
img.translateDrawingAxis(200, 150);

// Now (0,0) is at center
img.setDrawingColor("red");
img.drawRect(-50, -50, 100, 100, true);

img.write("centered.jpg");
```

### Rotate Coordinate System

```js
img = ImageNew(400, 300, "rgb", "white");
img.translateDrawingAxis(200, 150);

// Rotate 45 degrees
img.rotateDrawingAxis(45);

// Rectangle will be rotated
img.setDrawingColor("blue");
img.drawRect(-50, -50, 100, 100, false);

img.write("rotated-drawing.jpg");
```

### Shear Coordinate System

```js
img = ImageNew(400, 300, "rgb", "white");

// Shear axis
img.shearDrawingAxis(0.3, 0.1);

// Rectangle will be sheared
img.setDrawingColor("green");
img.drawRect(50, 50, 100, 100, false);

img.write("sheared-drawing.jpg");
```

## Complete Drawing Examples

### Create Badge

```js
// Create circular badge
img = ImageNew(200, 200, "argb", "transparent");
img.setAntiAliasing("on");

// Outer circle (border)
img.setDrawingColor("gold");
img.setDrawingStroke({width: 5});
img.drawOval(10, 10, 180, 180, false);

// Inner circle
img.setDrawingColor("yellow");
img.drawOval(20, 20, 160, 160, true);

// Star or text
img.setDrawingColor("red");
img.drawText("★", 75, 130, {
    font: "Arial",
    size: 72,
    style: "bold"
});

img.write("badge.png");
```

### Create Button

```js
// Create web button
img = ImageNew(200, 60, "rgb", "white");
img.setAntiAliasing("on");

// Gradient effect (simplified)
img.setDrawingColor("#4CAF50");
img.drawRoundRect(0, 0, 200, 60, 10, 10, true);

// Highlight
img.setDrawingColor("white");
img.setDrawingTransparency(30);
img.drawRoundRect(5, 5, 190, 25, 8, 8, true);

// Text
img.setDrawingColor("white");
img.setDrawingTransparency(100);
img.drawText("Click Me", 60, 40, {
    font: "Arial",
    size: 20,
    style: "bold"
});

img.write("button.png");
```

### Watermark with Text

```js
// Add watermark to photo
img = ImageNew("photo.jpg");
width = img.getWidth();
height = img.getHeight();

// Semi-transparent white text
img.setDrawingColor("white");
img.setDrawingTransparency(40);
img.drawText("© 2025 My Company",
    width - 250,
    height - 30,
    {
        font: "Arial",
        size: 16,
        style: "bold"
    }
);

img.write("watermarked.jpg");
```

## Drawing Tips

1. **Enable anti-aliasing** for smooth curves and text
2. **Set stroke before drawing** for consistent line widths
3. **Use transparency** for subtle effects like watermarks
4. **Translate axis to center** for symmetrical drawing
5. **Rotate axis** for angled text without rotating the image

## Next Steps

* [**Advanced Examples**](/boxlang-framework/modularity/image-manipulation/advanced-examples.md) - Complex drawing projects
* [**Filters & Effects**](/boxlang-framework/modularity/image-manipulation/filters-effects.md) - Apply visual effects
* [**Transformations**](/boxlang-framework/modularity/image-manipulation/transformations.md) - Resize and rotate images


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://boxlang.ortusbooks.com/boxlang-framework/modularity/image-manipulation/drawing.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.