0
# Branca
1

2
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.
3

4
## Package Information
5

6
- **Package Name**: branca
7
- **Language**: Python
8
- **Installation**: `pip install branca`
9
- **Dependencies**: jinja2>=3
10

11
## Core Imports
12

13
```python
14
import branca
15
```
16

17
Import specific modules:
18

19
```python
20
import branca.colormap as cm
21
import branca.element as element
22
from branca.utilities import color_brewer, legend_scaler
23
```
24

25
Or import specific classes and functions:
26

27
```python
28
from branca.colormap import ColorMap, LinearColormap, StepColormap, linear, step
29
from branca.element import Element, Figure, Html, Div, MacroElement, Link, JavascriptLink, CssLink, IFrame
30
from branca.utilities import image_to_url, write_png, color_brewer, legend_scaler, linear_gradient
31
```
32

33
## Basic Usage
34

35
```python
36
import branca.colormap as cm
37
from branca.element import Figure, Html
38

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

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

48
# Create HTML div with custom styling
49
div_content = Html(
50
    '<p>This is custom HTML content</p>',
51
    script=True,
52
    width='500px',
53
    height='300px'
54
)
55
```
56

57
## Architecture
58

59
Branca is organized into three main modules that work together:
60

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

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

67
## Capabilities
68

69
### Colormap Creation
70

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

73
```python { .api }
74
class LinearColormap:
75
    def __init__(self, colors, index=None, vmin=0.0, vmax=1.0, caption="", text_color="black", max_labels=10, tick_labels=None): ...
76
    def __call__(self, x: float) -> str: ...
77
    def scale(self, vmin: float = 0.0, vmax: float = 1.0, max_labels: int = 10): ...
78
    def to_step(self, n=None, index=None, data=None, method="linear", quantiles=None, round_method=None, max_labels=10): ...
79

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

87
[Colormap Creation](./colormap.md)
88

89
### HTML Element Generation
90

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

93
```python { .api }
94
class Figure:
95
    def __init__(self, width="100%", height=None, ratio="60%", title=None, figsize=None): ...
96
    def add_child(self, child, name=None, index=None): ...
97
    def save(self, outfile, close_file=True, **kwargs): ...
98
    def render(self, **kwargs) -> str: ...
99

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

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

109
[HTML Element Generation](./element.md)
110

111
### Utility Functions
112

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

115
```python { .api }
116
def color_brewer(color_code: str, n: int = 6) -> list: ...
117
def legend_scaler(legend_values, max_labels: int = 10) -> list: ...
118
def image_to_url(image, colormap=None, origin="upper") -> str: ...
119
def write_png(data, origin="upper", colormap=None) -> bytes: ...
120
def linear_gradient(hexList: list, nColors: int) -> list: ...
121
```
122

123
[Utility Functions](./utilities.md)
124

125
## Built-in Color Schemes
126

127
Pre-defined colormap collections with ColorBrewer schemes:
128

129
```python { .api }
130
# Linear colormap collection
131
linear: _LinearColormaps
132

133
# Step colormap collection  
134
step: _StepColormaps
135
```
136

137
Access built-in schemes:
138

139
```python
140
import branca.colormap as cm
141

142
# Use built-in linear colormaps
143
viridis_linear = cm.linear.viridis
144
plasma_linear = cm.linear.plasma
145

146
# Use built-in step colormaps
147
viridis_step = cm.step.viridis
148
plasma_step = cm.step.plasma
149
```