Easel - GitLite

KO | EN

gitlite — search

#javascript #python #hacktoberfest #react #llm #golang #docker #macos #java #windows #awesome-list #ios #mcp #openai

Easel

(★ 62)

Canvas 2D API for Elixir — draw to Phoenix LiveView, native wx windows, or custom backends

파일 탐색기

최종 버전 다운로드 (.zip)

- config.exs
- - .formatter.exs
  - .gitignore
  - AGENTS.md
  - mix.exs
  - mix.lock
  - README.md
- - audio_test.exs
  - boids.exs
  - braille_bloom.exs
  - chart.exs
  - clock.exs
  - example_opts.exs
  - final_card.exs
  - mandelbrot.exs
  - mondrian.exs
  - neon_bands.exs
  - showreel.exs
  - sierpinski.exs
  - smiley.exs
  - spiral.exs
  - starfield.exs
  - terminal_wave.exs
  - tree.exs
- - boids.exs
  - chart.exs
  - clock.exs
  - mandelbrot.exs
  - mondrian.exs
  - sierpinski.exs
  - smiley.exs
  - spiral.exs
  - starfield.exs
  - tree.exs
- README.md
- - live_view.ex
  - terminal.ex
  - wx.ex
- easel.ex
- web_idl.ex.exs
- - easel.js
- compat.json
- easel.webidl
- regenerate_canvas_api.exs
- - live_view_test.exs
  - wx_test.exs
- easel_api_test.exs
- easel_terminal_test.exs
- easel_test.exs
- test_helper.exs
.dockerignore
.formatter.exs
.gitignore
AGENTS.md
Dockerfile
fly.toml
LICENSE
mix.exs
mix.lock
README.md
TERMINAL_RENDERER_PLAN.md

# 설치 가이드

1. 코드 내려받기

git clone https://github.com/jeregrine/Easel

깃허브에서 프로젝트 코드 전체를 내 컴퓨터로 내려받습니다.

cd Easel

방금 내려받은 프로젝트 폴더 안으로 이동합니다.

2. 공식 설치 스크립트

쉬움 추천

사전 준비물

APT (Debian/Ubuntu 계열) Debian/Ubuntu 계열 리눅스에 기본 내장된 패키지 매니저입니다.

sudo apt install libwxgtk3.2-dev

APT 패키지 저장소에서 바로 설치합니다 (Debian/Ubuntu 계열).

✅ 설치 후 새 터미널을 열고, 프로그램의 버전 확인 명령(예: --version)으로 정상 설치됐는지 확인하세요.

이 레포의 README에 적힌 실제 명령어를 그대로 가져왔습니다.

3. Docker

쉬움

사전 준비물

Git GitHub에서 프로젝트 코드를 내려받으려면 필요합니다.
Docker Desktop 컨테이너를 빌드하고 실행하려면 필요합니다. 설치 후 실행해서 백그라운드에 켜두세요.

docker build -t easel .

Dockerfile을 기반으로 실행 가능한 이미지를 빌드합니다.

docker run -p 8080:80 easel

빌드된 이미지를 실제 컨테이너로 실행합니다.

✅ 터미널에 docker compose ps 를 입력해 컨테이너들이 Up 상태인지 확인하세요. README에 포트 번호가 적혀있다면 브라우저에서 http://localhost:포트번호 로 접속해보세요.

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# Easel

[![Hex.pm](https://img.shields.io/hexpm/v/easel.svg)](https://hex.pm/packages/easel)
[![Docs](https://img.shields.io/badge/hex-docs-blue.svg)](https://hexdocs.pm/easel)

Easel allows you to interact and draw on a canvas. The API is a `snake_cased` version of the [CanvasRenderingContext2D](https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D) with the addition of `set` and `call` if you need to set a property or call a function not yet supported.

The idea is you create a canvas, apply the draw operations to it then send it off to the Browser, Wx, or terminal backend to render. This allows us to use Elixir to draw basically anything, further it comes with the following features:

- Optional Phoenix LiveView components and hooks are available.
  - With support for layers.
  - Animations and Event handling
  - And templating and instancing of drawing, so you don't have to send all the draw commands on every frame, just the values that have changed.
- Optional Wx Rendering for local art and speed using the same Canvas API!.
- Experimental terminal rendering (`Easel.Terminal`) using wx off-screen rasterization + ASCII conversion.

## Example

Build a set of draw operations:

```elixir
canvas =
  Easel.new(300, 300)
  |> Easel.set_fill_style("blue")
  |> Easel.fill_rect(0, 0, 100, 100)
  |> Easel.set_line_width(10)
  |> Easel.stroke_rect(100, 100, 100, 100)
```

And render it

```elixir
Easel.render(canvas)
```

This reverses the ops list and marks it as rendered. To actually display it, send
it to a backend such as LiveView, wx, or `Easel.Terminal`.

## Phoenix LiveView

Easel includes an optional Phoenix LiveView component with a colocated runtime hook. No JavaScript build step is required.

### Template

```heex
<Easel.LiveView.canvas id="my-canvas" width={300} height={300} />
```

### Drawing from a LiveView

```elixir
def handle_event("draw", _, socket) do
  canvas =
    Easel.new(300, 300)
    |> Easel.set_fill_style("blue")
    |> Easel.fill_rect(0, 0, 100, 100)
    |> Easel.render()

{:noreply, Easel.LiveView.draw(socket, "my-canvas", canvas)}
end
```

You can clear before drawing:

```elixir
Easel.LiveView.draw(socket, "my-canvas", canvas, clear: true)
```

Or clear independently:

```elixir
Easel.LiveView.clear(socket, "my-canvas")
```

### Initial ops

Pass ops directly to render on mount:

```heex
<Easel.LiveView.canvas id="my-canvas" width={300} height={300} ops={@canvas.ops} />
```

### Events

Enable mouse and keyboard events with boolean attributes:

```heex
<Easel.LiveView.canvas
  id="my-canvas"
  width={300}
  height={300}
  on_click
  on_mouse_move
  on_key_down
/>
```

Events are pushed to your LiveView as `"<id>:<event>"`:

```elixir
def handle_event("my-canvas:click", %{"x" => x, "y" => y}, socket) do
  IO.puts("Clicked at #{x}, #{y}")
  {:noreply, socket}
end

def handle_event("my-canvas:keydown", %{"key" => key}, socket) do
  IO.puts("Key pressed: #{key}")
  {:noreply, socket}
end
```

Available: `on_click`, `on_mouse_down`, `on_mouse_up`, `on_mouse_move`, `on_key_down`.

Key events include `key`, `code`, `ctrl`, `shift`, `alt`, and `meta` fields.

### Layers

Use `canvas_stack/1` to layer multiple canvases. Each layer is an independent
`<canvas>` element stacked via CSS. Only layers whose assigns change get
re-patched by LiveView — static layers like backgrounds are sent once:

```heex
<Easel.LiveView.canvas_stack id="game" width={800} height={600}>
  <:layer id="background" ops={@background.ops} />
  <:layer id="sprites" ops={@sprites.ops} templates={@sprites.templates} />
  <:layer id="ui" ops={@ui.ops} />
</Easel.LiveView.canvas_stack>
```

Event flags go on the layer that should receive them (typically the topmost):

```heex
<:layer id="sprites" ops={@sprites.ops} on_click />
```

### Templates and Instances

For scenes with many similar shapes (particles, sprites, entities), define a
**template** once and stamp out **instances** with per-instance transforms.
Only the instance data is sent each frame while template ops are cached
client-side.

`Easel.instances/4` supports float quantization to reduce websocket payloads,
and you can set defaults once on `Easel.template/4`:

```elixir
canvas =
  Easel.new(800, 600)
  |> Easel.template(:boid, fn c ->
    c
    |> Easel.begin_path()
    |> Easel.move_to(12, 0)
    |> Easel.line_to(-4, -5)
    |> Easel.line_to(-4, 5)
    |> Easel.close_path()
    |> Easel.fill()
  end, x: 1, y: 1, rotate: 3)
```

Per-call overrides still work:

```elixir
Easel.instances(canvas, :boid, instances, rotate: 2)
```

Internally, instance rows are sent in a compact columnar format (`rows + cols`)
so unused fields are omitted instead of sending repeated `null`s.

```elixir
canvas =
  Easel.new(800, 600)
  |> Easel.template(:boid, fn c ->
    c
    |> Easel.begin_path()
    |> Easel.move_to(12, 0)
    |> Easel.line_to(-4, -5)
    |> Easel.line_to(-4, 5)
    |> Easel.close_path()
    |> Easel.fill()
  end)
  |> Easel.instances(:boid, Enum.map(boids, fn b ->
    angle = :math.atan2(b.vy, b.vx)
    hue = round(angle / :math.pi() * 180 + 180)
    %{x: b.x, y: b.y, rotate: angle, fill: "hsl(#{hue}, 70%, 60%)"}
  end))
  |> Easel.render()
```

Pass templates to the canvas component alongside ops:

```heex
<Easel.LiveView.canvas
  id="sprites"
  width={800}
  height={600}
  ops={@canvas.ops}
  templates={@canvas.templates}
/>
```

If templates are cached in one canvas and instances are emitted from another,
carry template instance defaults over with `Easel.with_template_opts/2`:

```elixir
frame_canvas
|> Easel.with_template_opts(template_canvas.template_opts)
|> Easel.instances(:boid, instances)
```

Each instance map may contain:

| Key                    | Description           | Default |
| ---------------------- | --------------------- | ------- |
| `:x`, `:y`             | Translation           | `0`     |
| `:rotate`              | Rotation in radians   | `0`     |
| `:scale_x`, `:scale_y` | Scale factors         | `1`     |
| `:fill`                | Fill style override   | —       |
| `:stroke`              | Stroke style override | —       |
| `:alpha`               | Global alpha override | —       |

For non-JS backends (wx, custom renderers), call `Easel.expand/1` to flatten
instances into plain Canvas 2D ops (save/translate/rotate/fill/restore):

```elixir
canvas |> Easel.expand()  # __instances → plain ops
```

**Payload comparison (100 boids):**

| Approach                  | Ops/frame | Bytes/frame |
| ------------------------- | --------- | ----------- |
| Inline ops (no templates) | ~504      | ~19 KB      |
| Templates + instances     | 1         | ~7.8 KB     |

### Animation

Run a server-side animation loop. Use `:canvas_assign` so the template
re-renders with new ops each frame:

```elixir
def mount(_params, _session, socket) do
  socket =
    socket
    |> assign(:balls, initial_balls())
    |> assign(:canvas, Easel.new(600, 400) |> Easel.render())
    |> Easel.LiveView.animate("my-canvas", :balls, fn balls ->
      new_balls = tick(balls)
      canvas = render_balls(new_balls)
      {canvas, new_balls}
    end, interval: 16, canvas_assign: :canvas)

{:ok, socket}
end

def handle_info({:easel_tick, id}, socket) do
  {:noreply, Easel.LiveView.tick(socket, id)}
end
```

The template binds ops to the canvas assign:

```heex
<Easel.LiveView.canvas id="my-canvas" width={600} height={400} ops={@canvas.ops} />
```

The hook uses `requestAnimationFrame` to sync drawing with the browser's
refresh rate. If multiple server updates arrive between frames, only the
latest is drawn — no wasted renders.

To stop the animation:

```elixir
Easel.LiveView.stop_animation(socket, "my-canvas")
```

## Examples

This repo has two main example styles:

- **Phoenix/LiveView examples** in `examples/phx_demo`
  - Includes static and animated browser demos
  - Static examples: Smiley, Chart, Starfield, Spiral, Fractal Tree, Mondrian, Sierpinski, Mandelbrot
  - Animated examples: Clock, Boids, Matrix, Game of Life, Lissajous, Flow Field, Wave Grid, Pathfinding (BFS/DFS/A*/Greedy)
  - Demo app entry: `examples/phx_demo/lib/phx_demo_web/live/demo_live.ex`
  - Drawing logic modules: `examples/phx_demo/lib/phx_demo/examples/*.ex`
  - Static per-example pages: `/examples/:id`

- **wx/native examples** using `Easel.WX`
  - Use the same Easel Canvas API, but render to a native wx window instead of the browser
  - Includes both static renders and animated examples
  - Standalone scripts live under `examples/wx/*.exs` (for example boids)

- **terminal examples** using `Easel.Terminal`
  - Experimental terminal rendering and animation scripts
  - Standalone scripts live under `examples/term/*.exs`

Run the Phoenix demo locally:

```bash
cd examples/phx_demo
mix phx.server
```

## wx Backend

Easel includes an optional native rendering backend using Erlang's `:wx` (wxWidgets).
This opens a native desktop window and draws your canvas operations without a browser.

```elixir
Easel.new(400, 300)
|> Easel.set_fill_style("blue")
|> Easel.fill_rect(50, 50, 100, 100)
|> Easel.set_stroke_style("red")
|> Easel.set_line_width(3)
|> Easel.stroke_rect(50, 50, 100, 100)
|> Easel.render()
|> Easel.WX.render(title: "My Drawing")
```

Canvases with templates/instances are automatically expanded via `Easel.expand/1`
before rendering in wx.

### Event handling

Both `render/2` and `animate/5` accept optional event handler callbacks:

```elixir
# Static render — handlers receive (x, y) or (key_event)
Easel.WX.render(canvas,
  on_click: fn x, y -> IO.puts("Clicked at #{x}, #{y}") end,
  on_mouse_move: fn x, y -> IO.puts("Mouse at #{x}, #{y}") end,
  on_key_down: fn %{key: key} -> IO.puts("Key: #{key}") end
)

# Animation — handlers receive args + state, return new state
Easel.WX.animate(600, 400, initial_state, tick_fn,
  on_click: fn x, y, state -> %{state | target: {x, y}} end,
  on_key_down: fn %{key: ?r}, state -> reset(state) end
)
```

Available events: `:on_click`, `:on_mouse_down`, `:on_mouse_up`, `:on_mouse_move`, `:on_key_down`

Not all Canvas 2D operations are supported in wx. Unsupported ops (shadows, filters,
gradients, image data, etc.) will raise `Easel.WX.UnsupportedOpError`. See the
`Easel.WX` module docs for the full list of supported operations.

### wx Prerequisites

Erlang must be compiled with wxWidgets support. If you use [mise](https://mise.jdx.dev)
(or asdf), you'll need to ensure wxWidgets is installed and Erlang is built against it.

1. Install wxWidgets (with compat-3.0 support, required by Erlang's wx):

```bash
   # macOS — edit the formula to add --enable-compat30
   brew edit wxwidgets
   # Add "--enable-compat30" to the args list in the formula, then:
   brew reinstall wxwidgets --build-from-source

# Ubuntu/Debian
   sudo apt install libwxgtk3.2-dev
   ```

2. Configure mise to build Erlang with wx support. In your `.mise.toml`:

```toml
   [tools]
   erlang = "latest"
   elixir = "latest"

[env]
   KERL_CONFIGURE_OPTIONS = "--with-wx"
   ```

3. Force rebuild Erlang (this takes a few minutes):

```bash
   mise install erlang@latest --force
   ```

4. Verify wx works:

```bash
   erl -noshell -eval 'wx:new(), io:format("wx works!~n"), halt().'
   ```

> **Note:** If you update wxWidgets (e.g. via `brew upgrade`), you'll need to
> rebuild Erlang with `mise install erlang --force` so it links against the new version.

## Terminal Backend (Experimental)

`Easel.Terminal` renders Easel canvases in a terminal by:

1. Rasterizing off-screen with `Easel.WX.rasterize/2`
2. Extracting color silhouettes and fitting printable ASCII glyph masks per cell
3. Writing frames through `termite`

Because it currently relies on wx for rasterization, it has the same wx runtime
requirement as `Easel.WX`.

It also requires an interactive TTY (run from a real terminal session).

```elixir
canvas =
  Easel.new(120, 80)
  |> Easel.set_fill_style("black")
  |> Easel.fill_rect(0, 0, 120, 80)
  |> Easel.set_fill_style("white")
  |> Easel.set_font("bold 24px monospace")
  |> Easel.fill_text("Easel", 20, 45)

Easel.Terminal.render(canvas, color: :ansi256, dpr: 2.0, samples: 3)
# press q to quit
```

Animation API mirrors `Easel.WX.animate/5`:

```elixir
Easel.Terminal.animate(120, 80, state, fn state ->
  {canvas, next_state} = tick(state)
  {canvas, next_state}
end, fps: 30, color: :ansi256)
```

Press `q` (or Ctrl+C) to stop.

Tip: `dpr` and `samples` help a lot with text/edge quality.

By default, `Easel.Terminal` auto-selects characters using silhouette fitting,
caches mask→glyph matches during a render/animation run (`char_cache: true`),
and can adapt color luma to terminal theme (`theme: :auto`, `auto_contrast: true`) when needed.
You can tune cache size with `char_cache_size:`.

For faster animation, reduce silhouette cell resolution with `glyph_width:` /
`glyph_height:`.

If you want the old density-ramp mode, pass a manual `charset:` string.

## Installation

Add `easel` to your list of dependencies in `mix.exs`:

```elixir
def deps do
  [
    {:easel, "~> 0.3.3"},
    # optional, for LiveView support
    {:phoenix_live_view, "~> 1.0"},
    # optional, for Easel.Terminal
    {:termite, "~> 0.4.0"}
  ]
end
```

Then fetch your dependencies:

```bash
mix deps.get
```

Documentation is available on [HexDocs](https://hexdocs.pm/easel).

## Regenerating Canvas API wrappers (for contributors)

`Easel` ships with generated Canvas2D wrapper functions directly in `lib/easel.ex`.

If `priv/easel.webidl` or `priv/compat.json` changes, regenerate wrappers with:

```bash
mix easel.regen_canvas_api
```

This uses a script-local NimbleParsec parser template (`lib/web_idl.ex.exs`) and does
not require NimbleParsec as a runtime dependency of the library.