DOCSEARCHbyAlgolia
Submit Docs

ntcharts

repository·v2·Indexed 20 days ago

https://github.com/nimblemarkets/ntcharts

A Golang library for creating high-quality terminal-based charts, designed for the Bubble Tea framework. It supports a wide range of visualizations including time series line charts, OHLC candlestick charts, bar charts, heatmaps, and 2D grid plotting via a Canvas. The library features advanced terminal capabilities such as Kitty graphics for high-resolution imagery and smooth gradients, as well as half-block glyph fallbacks for broader terminal compatibility.

Tokens
10.1K
Snippets
32
Records
46
Agent score
73%

What's inside ntcharts

  1. Overview of ntcharts-lorem-picsum

    v2

    ntcharts-lorem-picsum

    ntcharts-lorem-picsum is a terminal-based browser for the Lorem Picsum image catalog. It allows users to sort and filter through images and view them using two different rendering modes side-by-side:

    1. Half-block glyphs: Rendered on the left side; compatible with any terminal.
    2. Full Kitty graphics: Rendered on the right side; requires a terminal with Kitty graphics support (e.g., Kitty, Ghostty, or WezTerm).

    The application demonstrates the capabilities of the pictureurl package, including asynchronous URL fetching, LRU image caching, error overlays, and the picture.Model Glyph/Kitty toggle.

  2. Overview of ntcharts terminal charting types

    v2

    ntcharts is a Golang library for creating terminal-based charts, primarily designed for the Bubble Tea framework and other TUIs. It provides a variety of chart types built upon a foundational Canvas (a 2D grid for plotting runes).

    Available chart types include:

    • Canvas: The 2D grid foundation for all charts.
    • Bar Chart: Horizontal rows or vertical columns.
    • Heat Map: (x,y) values on a color-mapped grid.
    • Line Chart: (X,Y) data points on a 2D grid.
    • OHLC/Candle Chart: Open, High, Low, Close values.
    • Picture: Displays images via local files or URLs.
    • Chart Picture: Renders go-analyze/charts images using Kitty graphics with glyph fallback.
    • Heat Picture: High-resolution continuous-field heatmap using Kitty graphics.
    • Scatter Chart: Arbitrary runes on (X,Y) coordinates.
    • Streamline Chart: Continuous line moving from right to left.
    • Time Series Chart: Lines with time on the X axis and values on the Y axis.
    • Waveline Chart: Line chart connecting points in a wave pattern.
    • Sparkline: Small, simple data visualizations.

  3. Integrate ntcharts with Bubble Tea

    v2

    To use ntcharts in a Bubble Tea application, follow this integration pattern:

    1. Model: Create a struct that holds the chart (tslc.Model) and the zone.Manager.
    2. Update: In the Update(msg tea.Msg) method, forward the incoming message to the chart using m.chart, _ = m.chart.Update(msg). If you want to use braille rendering for all data sets, call m.chart.DrawBrailleAll() after the update.
    3. View: Wrap the m.chart.View() output with m.zoneManager.Scan() to enable mouse interaction.
    type model struct {
    chart       tslc.Model
    zoneManager *zone.Manager
}

func (m model) Update(msg tea.Msg) (tea.Model, tea.Cmd) {
    // ... handle quit keys ...

    // forward Bubble Tea Msg to chart
    m.chart, _ = m.chart.Update(msg)
    m.chart.DrawBrailleAll()
    return m, nil
}

func (m model) View() string {
    return m.zoneManager.Scan(m.chart.View())
}

  4. Create coordinate-aligned graphics with picture.NewGridImage

    v2

    To render graphics where logical grid cells map exactly to fixed terminal-cell regions (useful for game boards or grids), use the picture.NewGridImage pattern.

    The Workflow:

    1. Initialize a grid using picture.NewGridImage.
    2. Draw content into specific cells using grid.CellRect(...) for coordinate-based drawing or grid.DrawCell(...) for cell-based drawing.
    3. Retrieve the dimensions using grid.TerminalSize().
    4. Convert the grid to a bitmap using grid.Image().
    5. Pass the resulting image to picture.Model.SetImage to render it.

    To ensure the grid fills the available space correctly, use picture.Config{Fit: picture.FitFill} when rendering through picture.Model.

    // Conceptual pattern extracted from example
// 1. Create the grid
grid := picture.NewGridImage()

// 2. Draw into cells
grid.DrawCell(x, y, sprite)
// OR
rect := grid.CellRect(x, y)
drawSomething(rect)

// 3. Get size and image
size := grid.TerminalSize()
img := grid.Image()

// 4. Render via picture.Model
model.SetImage(img)

  5. Best Practice: Compose, Then Render

    v2

    To avoid fragile cursor-position overlays or 'holes' in the image caused by mixing Kitty graphics with standard terminal text, follow the Compose, Then Render pattern:

    1. Build a single bitmap containing the background and all sprites/overlays.
    2. Feed that single image to picture.Model using pic.SetImage().
    3. Let picture.Model manage the Kitty placeholder grid.

    Example Pattern:

    grid := picture.NewGridImage(cfg)
grid.DrawOverlay(gridLines)
grid.DrawCell(x, y, sprite)
pic.SetImage(grid.Image())
    grid := picture.NewGridImage(cfg)
grid.DrawOverlay(gridLines)
grid.DrawCell(x, y, sprite)
pic.SetImage(grid.Image())

  6. Use HeatPicture for continuous-field heatmaps

    v2

    heatpicture is designed for function-driven sources where every pixel can be sampled cheaply. Unlike the standard heatmap (which uses sparse data points), heatpicture uses a Sampler func(x, y float64) float64.

    Key Features:

    • Kitty Mode: Renders at full terminal-pixel resolution for smooth gradients.
    • Glyph Mode: Renders at half-block resolution as a fast fallback.
    • Sampling Control: You can cycle the sampling factor (e.g., 1.0 → 0.5 → 0.25) to trade rendering quality for animation smoothness on large terminals.

    Example: ntcharts-heatpicture-perlin (animates a 2D Perlin-noise field).

  8. Quickstart: Create a Time Series Chart

    v2

    The ntcharts-quickstart example demonstrates how to create a simple Time Series Chart with two data sets. This implementation utilizes:

    • Bubble Tea: For the TUI framework.
    • Lip Gloss: For styling.
    • BubbleZone: For mouse support.

    Refer to the quickstart tutorial for the full implementation details.

    // Source for quickstart is located at examples/quickstart/main.go

  9. Run ntcharts examples locally

    v2

    To run the provided examples, first build the project using the task command. This will compile all examples into the bin directory of the ntcharts repository. You can then execute any example directly from that directory.

    Example command:

    ./bin/ntcharts-quickstart

  10. Use ntcharts-ohlc to display OHLC data

    v2

    ntcharts-ohlc is a CLI tool that visualizes Open, High, Low, Close (OHLC) data from a CSV file as terminal charts. It supports line charts (using either braille patterns or continuous lines) and candlestick charts.

    Input CSV Requirements

    The input CSV file must include the following column headers:

    • Date (Format: YYYY-MM-DD, must be in chronological order)
    • Open
    • High
    • Low
    • Close
    • Adj Close
    • Volume
    ./bin/ntcharts-ohlc -filepath cmd/ntcharts-ohlc/example.csv -high -low -vol -braille

  11. Configure Tmux for Kitty Graphics Passthrough

    v2

    When running inside tmux, raw Kitty graphics escape sequences are often blocked. To enable them, you must configure tmux to allow DCS passthrough.

    Add this line to your ~/.tmux.conf (requires tmux 3.3+):

    set -g allow-passthrough on

    After adding this, reload your tmux configuration or restart your session.

    set -g allow-passthrough on

  12. Import ntcharts based on Bubble Tea version

    v2

    ntcharts supports two versions depending on your project's Bubble Tea dependency:

    1. Bubble Tea v2 (Primary): Use the v2 branch. Import using the /v2 suffix.
    2. Bubble Tea v1: Use the main branch. Import without the suffix.

    Note: The v2 designation refers to Bubble Tea API compatibility; the ntcharts API itself may still change.

    // For Bubble Tea v2
import "github.com/NimbleMarkets/ntcharts/v2"

// For Bubble Tea v1
import "github.com/NimbleMarkets/ntcharts"