or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

colormap.mdelement.mdindex.mdutilities.md
tile.json

tessl/pypi-branca

A library to generate HTML + JS pages, spun off from folium and based on Jinja2

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
pypipkg:pypi/branca@0.8.x

To install, run

npx @tessl/cli install tessl/pypi-branca@0.8.0

index.mddocs/

Branca

A lightweight Python library for generating HTML + JS pages, spun off from folium and based on Jinja2 templating. Branca provides powerful colormap creation, flexible HTML element generation, and utility functions for web visualization, serving as the foundation for interactive data visualization projects.

Package Information

  • Package Name: branca
  • Language: Python
  • Installation: pip install branca
  • Dependencies: jinja2>=3

Core Imports

import branca

Import specific modules:

import branca.colormap as cm
import branca.element as element
from branca.utilities import color_brewer, legend_scaler

Or import specific classes and functions:

from branca.colormap import ColorMap, LinearColormap, StepColormap, linear, step
from branca.element import Element, Figure, Html, Div, MacroElement, Link, JavascriptLink, CssLink, IFrame
from branca.utilities import image_to_url, write_png, color_brewer, legend_scaler, linear_gradient

Basic Usage

import branca.colormap as cm
from branca.element import Figure, Html

# Create a colormap for data visualization
colormap = cm.LinearColormap(['green', 'yellow', 'red'], vmin=0, vmax=100)
print(colormap(50))  # Get color for value 50

# Create HTML content with Figure
fig = Figure(width='800px', height='600px', title='My Visualization')
fig.html.add_child(Html('<h1>Hello World</h1>'))
fig.save('output.html')

# Create HTML div with custom styling
div_content = Html(
    '<p>This is custom HTML content</p>',
    script=True,
    width='500px',
    height='300px'
)

Architecture

Branca is organized into three main modules that work together:

  • colormap: Provides LinearColormap and StepColormap classes for creating color scales, with built-in ColorBrewer schemes and custom color interpolation
  • element: Contains HTML generation classes including Figure (complete HTML documents), Html/Div (content containers), and MacroElement (template-based components)
  • utilities: Offers helper functions for color processing, image conversion, and data manipulation

This modular design enables flexible web content generation, from simple HTML pages to complex interactive visualizations with custom color schemes.

Capabilities

Colormap Creation

Create linear and step-based colormaps for data visualization, with support for custom colors, ColorBrewer schemes, and automatic scaling.

class LinearColormap:
    def __init__(self, colors, index=None, vmin=0.0, vmax=1.0, caption="", text_color="black", max_labels=10, tick_labels=None): ...
    def __call__(self, x: float) -> str: ...
    def scale(self, vmin: float = 0.0, vmax: float = 1.0, max_labels: int = 10): ...
    def to_step(self, n=None, index=None, data=None, method="linear", quantiles=None, round_method=None, max_labels=10): ...

class StepColormap:
    def __init__(self, colors, index=None, vmin=0.0, vmax=1.0, caption="", text_color="black", max_labels=10, tick_labels=None): ...
    def __call__(self, x: float) -> str: ...
    def scale(self, vmin: float = 0.0, vmax: float = 1.0, max_labels: int = 10): ...
    def to_linear(self, index=None, max_labels=10): ...

Colormap Creation

HTML Element Generation

Create structured HTML documents with Figure, Html, Div, and other element classes for building web pages and interactive content.

class Figure:
    def __init__(self, width="100%", height=None, ratio="60%", title=None, figsize=None): ...
    def add_child(self, child, name=None, index=None): ...
    def save(self, outfile, close_file=True, **kwargs): ...
    def render(self, **kwargs) -> str: ...

class Html:
    def __init__(self, data: str, script=False, width="100%", height="100%"): ...
    def render(self, **kwargs) -> str: ...

class Div:
    def __init__(self, width="100%", height="100%", left="0%", top="0%", position="relative"): ...
    def add_child(self, child, name=None, index=None): ...

HTML Element Generation

Utility Functions

Helper functions for color processing, image conversion, legend scaling, and data manipulation to support visualization workflows.

def color_brewer(color_code: str, n: int = 6) -> list: ...
def legend_scaler(legend_values, max_labels: int = 10) -> list: ...
def image_to_url(image, colormap=None, origin="upper") -> str: ...
def write_png(data, origin="upper", colormap=None) -> bytes: ...
def linear_gradient(hexList: list, nColors: int) -> list: ...

Utility Functions

Built-in Color Schemes

Pre-defined colormap collections with ColorBrewer schemes:

# Linear colormap collection
linear: _LinearColormaps

# Step colormap collection  
step: _StepColormaps

Access built-in schemes:

import branca.colormap as cm

# Use built-in linear colormaps
viridis_linear = cm.linear.viridis
plasma_linear = cm.linear.plasma

# Use built-in step colormaps
viridis_step = cm.step.viridis
plasma_step = cm.step.plasma