Skip to main content

Stock Chart (丝袜统计图)

GitHub: xie-huaaaan/stockchart

License: MPL 2.0 Assets: ARR

A creative plotting library that draws data as stockings pulled up over a pair of legs.

A grouped stockchart: two series over three months

stockchart is a playful alternative to the bar chart. Each value becomes the height of a stocking pulled up over a leg: a larger value means more stocking, and zero is a bare leg. It is made for infographics, slides, posters, and anywhere a chart should be memorable rather than conventional.

  • Values → stocking height. Grouped, paired, and positive/negative mirror charts are supported.
  • 19 built-in styles. Sheer, opaque tights, stripes, knit, fishnet, polka dots, hearts, lace trims, and more.
  • Data-science friendly. Lists, NumPy arrays, dictionaries, and pandas DataFrame/Series. pandas is optional and never imported by the library itself.
  • Native high-resolution output. Stocking textures and lighting are generated at the target pixel density, not upscaled from a bitmap.
  • Composable by design. Start with one-line bar(); drop down to pixel-level placement when you need a custom layout.
  • No matplotlib. Text and lines are rendered with Skia, including a per-character font fallback for Chinese, Japanese, and Korean.
A grouped chart comparing planned and actual weekend hours
Grouped chart — black_sheer (welt) and white_sheer (lace)
A single-series chart with negative values, all legs upright
Single series with negative values — every leg stays upright (heart_white)
Seven legs wearing seven different stocking styles
A sweep of presets — 5 fabric types, 4 top edges
A mirror chart with positive and negative values
Mirror chart — positive and negative values

Installation

pip install stockchart

or with uv:

uv add stockchart

Requires Python 3.12 or newer. Runtime dependencies are skia-python, numpy, and pillow.

Quick start

from stockchart import bar

bar(
    [[320, 210], [450, 280], [510, 190]],
    labels=["Jan", "Feb", "Mar"],
    series_labels=["This site", "Neighbor"],
    title="Monthly report",
    xlabel="Month",
    ylabel="Active users",
    style=["black_sheer", "white_sheer"],
    value_labels=True,
    seed=2,
).save("chart.png")

The result is the image at the top of this README. bar() maps the data, chooses leg assets, lays out groups, and draws the axes. It returns a BarPlot that can be saved directly or adjusted further.

A mirror chart for positive and negative values:

from stockchart import mirror_bar

mirror_bar(
    [4.2, -2.8, 6.1, -5.5, 3.4, -1.9],
    labels=["Mon", "Tue", "Wed", "Thu", "Fri", "Sat"],
    title="Daily change",
    style="gray_sheer",
    value_labels=True,
    seed=2,
).save("mirror.png")

Data input

Pass the data structure you already have:

Input How it is interpreted
1-D list / tuple / sequence One series
2-D sequence (groups, series) Grouped data
numpy.ndarray 1-D or 2-D arrays
dict of scalars Keys become x-axis labels, one series
dict of equal-length sequences Keys become series names and a legend is generated
pandas DataFrame Index → x labels, columns → series names
pandas Series Index → x labels, one series
PlotData Already-normalized data

For example, a DataFrame gets its labels and legend automatically:

import pandas as pd
from stockchart import bar

df = pd.DataFrame(
    {"This site": [320, 450, 510], "Neighbor": [210, 280, 190]},
    index=["Jan", "Feb", "Mar"],
)
bar(df, title="Monthly report", style=["black_sheer", "white_sheer"]).save("chart.png")

Explicit labels= and series_labels= override anything inferred from the data. Custom containers can be registered with register_data_type; see the data input reference.

Stocking styles

Pass a preset name, or a list of names to cycle through styles:

bar(
    [5, 6, 7, 8, 6, 9, 4],
    labels=["Sheer", "Lace", "Stripe", "Knit", "Fishnet", "Dots", "Tights"],
    title="One of each",
    style=[
        "nude_sheer",
        "white_sheer",
        "stripe_rainbow",
        "knit_cream",
        "fishnet_black",
        "polka_black",
        "black_pantyhose",
    ],
    value_labels=True,
    seed=3,
)

The 19 presets cover sheer stockings, opaque tights, stripes, ribbed knit, fishnet, polka dots, hearts, lace trims, and more. For direct control, pass a StockingStyle built from Plain, Striped, Ribbed, Fishnet, or Dotted fabrics with a Bare, Welt, Lace, or Fade top edge. The full style table is in the rendering reference.

Titles, axis names, and options

bar(
    data,
    title="Monthly report",  # centered over the plot by default
    xlabel="Month",
    ylabel="Active users",
    title_align="left",  # restore a left-aligned title
    grid=True,
    axis_style="handdrawn",
    legend_loc="bottom",
)

Chart-level parameters stay in the signature; lower-level options such as grid, axis_style, legend_loc, legend_ncol, x_label_rotation, bar_gap, and group_gap are passed through a typed option bag. See the ChartOptions table.

API layers

The library is deliberately layered, so you can choose how much control you want:

Layer What it gives you Entry points
L0 assets Leg metadata and built-in artwork Leg, LegLibrary, load_leg
L1 primitives One stocking, text, hand-drawn lines render_stocking, StockingStyle, STYLES, draw_text, sketch_*
L2 free-form plot Canvas, baseline, arbitrary leg placement BarPlot, Scale, Canvas
L3 layout helpers Uniform spacing and automatic leg selection add_bars, add_grouped_bars, add_paired_bars
L4 one-liners Data normalization and fully automatic layout bar, mirror_bar

For a more hands-on layout:

from stockchart import BarPlot, Scale

plot = BarPlot(1200)
plot.add_bars([300, 500, 400], style="black_sheer")
plot.add_x_labels(["A", "B", "C"])
plot.add_y_axis(Scale((0, 500), (0, 760)))
plot.add_title("Free-form layout")
plot.save("chart.png")

Output

BarPlot renders to PNG and can also return a PIL image or a NumPy array:

plot.save("chart.png", scale=2)  # PNG at 2× pixel density
image = plot.to_pil()
array = plot.to_numpy()

scale controls output pixel density; stocking textures and lighting are regenerated at that density. SVG and PDF output are intentionally not supported.

Documentation

Development

git clone https://github.com/xie-huaaaan/stockchart.git
cd stockchart
uv sync
uv run python -m pytest
uv run ruff check . && uv run ruff format .
uv run python -m pyright

Issues and pull requests are welcome.

Status

0.1.x is an early public release. The rendering pipeline is stable, but the public API may still change in minor releases.

License

The source code is released under the Mozilla Public License 2.0 (MPL-2.0). You can use stockchart in closed-source projects; if you modify MPL-covered source files, those files must remain available under MPL-2.0.

The built-in leg artwork (src/stockchart/assets/leg_*.svg and legs.json) is All Rights Reserved and is not covered by MPL-2.0; see the asset license. The artwork may be used to render charts with stockchart, and charts you generate are your own work. The artwork itself may not be extracted or redistributed except as part of an unmodified stockchart package.


简体中文

用丝袜被拉起的高度表示数据的创意绘图库。

分组丝袜图:三个月、两个系列

stockchart 是柱状图的一种有趣替代:每个数值对应一条腿上丝袜被拉起的高度, 数值越大丝袜越高,0 则是一条裸腿。它适合信息图、幻灯片、海报,以及任何希望 图表更有个性、而不只是“标准”的场合。

  • 数值 → 丝袜高度:支持分组、成对,以及正负值上下镜像。
  • 19 种内置样式:透肉丝袜、厚袜、条纹、针织、网袜、波点、爱心、蕾丝边等。
  • 支持常见数据类型:列表、NumPy 数组、字典、pandas DataFrame / Series。 pandas 是可选依赖,库本身不会 import 它。
  • 原生高分辨率输出:丝袜纹理与光影按目标像素密度重新生成,不是把小图放大。
  • 分层可组合:一行 bar() 即可出图;需要自由排版时可下沉到逐像素放置。
  • 不依赖 matplotlib:文字与线条由 Skia 渲染,逐字符字体回退,中文可正常显示。
分组图:周末计划与实际的小时数对比
分组图 —— black_sheer(松紧袜口)与 white_sheer(蕾丝边)
含负值的单系列图,全部朝上的腿
单系列含负值 —— 依旧全是朝上的腿(heart_white)
七条腿穿着七种不同的丝袜样式
样式巡礼 —— 5 种袜身、4 种上沿
正负值镜像图
镜像图 —— 正负值上下分布

安装

pip install stockchart

或使用 uv:

uv add stockchart

需要 Python 3.12 或更高版本。运行时依赖只有 skia-python、numpy、pillow。

快速开始

from stockchart import bar

bar(
    [[320, 210], [450, 280], [510, 190]],
    labels=["一月", "二月", "三月"],
    series_labels=["本站", "隔壁站"],
    title="每月活跃用户",
    xlabel="月份",
    ylabel="人数",
    style=["black_sheer", "white_sheer"],
    value_labels=True,
    seed=2,
).save("chart.png")

输出就是本文顶部那张图。bar() 会自动完成数值映射、选腿、分组布局与坐标轴绘制, 返回一个可以直接 .save()、也可以继续微调的 BarPlot。

正负值镜像图:

from stockchart import mirror_bar

mirror_bar(
    [4.2, -2.8, 6.1, -5.5, 3.4, -1.9],
    labels=["周一", "周二", "周三", "周四", "周五", "周六"],
    title="每日变化",
    style="gray_sheer",
    value_labels=True,
    seed=2,
).save("mirror.png")

数据输入

直接传入手头的数据结构即可:

输入 解释
一维列表 / 元组 / 序列 单系列
二维序列 (组数, 系列数) 分组数据
numpy.ndarray 一维或二维数组
标量值字典 键作 x 轴标签,单系列
等长序列字典 键作系列名,并自动生成图例
pandas DataFrame index → x 标签,columns → 系列名
pandas Series index → x 标签,单系列
PlotData 已归一化的数据

例如 DataFrame 会自动带上标签和图例:

import pandas as pd
from stockchart import bar

df = pd.DataFrame(
    {"本站": [320, 450, 510], "隔壁站": [210, 280, 190]},
    index=["一月", "二月", "三月"],
)
bar(df, title="每月活跃用户", style=["black_sheer", "white_sheer"]).save("chart.png")

显式传入的 labels= / series_labels= 会覆盖从数据推断出的值。自定义容器可以用 register_data_type 注册,详见 数据输入参考。

丝袜样式

传一个预设名,或用列表让样式循环:

bar(
    [5, 6, 7, 8, 6, 9, 4],
    labels=["肉丝", "白丝", "彩条", "针织", "网袜", "波点", "厚袜"],
    title="每种来一条",
    style=[
        "nude_sheer",
        "white_sheer",
        "stripe_rainbow",
        "knit_cream",
        "fishnet_black",
        "polka_black",
        "black_pantyhose",
    ],
    value_labels=True,
    seed=3,
)

19 个预设覆盖透肉丝袜、厚袜、条纹、针织、网袜、波点、爱心、蕾丝边等。需要更细的 控制时,可以直接构造 StockingStyle:袜身用 Plain / Striped / Ribbed / Fishnet / Dotted,上沿用 Bare / Welt / Lace / Fade。完整样式表见 渲染原语参考。

标题、轴名与选项

bar(
    [[320, 210], [450, 280], [510, 190]],
    labels=["一月", "二月", "三月"],
    series_labels=["本站", "隔壁站"],
    title="每月活跃用户",  # 默认在绘图区上方居中
    xlabel="月份",
    ylabel="人数",
    title_align="left",  # 需要时改回左对齐
    grid=True,
    axis_style="handdrawn",
    legend_loc="bottom",
)

图表语义参数留在函数签名里;grid、axis_style、legend_loc、legend_ncol、 x_label_rotation、bar_gap、group_gap 等下层选项通过类型化的选项包透传。 完整列表见 ChartOptions 表。

API 分层

库里刻意分成五层,按需要的控制力选择即可:

层 提供什么 入口
L0 素材 腿素材的元数据与内置图形 Leg、LegLibrary、load_leg
L1 渲染原语 单条丝袜、文字、手绘线条 render_stocking、StockingStyle、STYLES、draw_text、sketch_*
L2 自由柱状图 画布、基线、任意位置贴腿 BarPlot、Scale、Canvas
L3 布局封装 统一间距、自动选腿 add_bars、add_grouped_bars、add_paired_bars
L4 一行出图 数据归一 + 全自动布局 bar、mirror_bar

例如 L2/L3 可以自己摆放每一条腿:

from stockchart import BarPlot, Scale

plot = BarPlot(1200)
plot.add_bars([300, 500, 400], style="black_sheer")
plot.add_x_labels(["A", "B", "C"])
plot.add_y_axis(Scale((0, 500), (0, 760)))
plot.add_title("自由排版")
plot.save("chart.png")

输出

BarPlot 输出 PNG,也可以直接拿 PIL Image 或 NumPy 数组:

plot.save("chart.png", scale=2)  # 2 倍像素密度的 PNG
image = plot.to_pil()
array = plot.to_numpy()

scale 控制输出像素密度;丝袜纹理与光影会按该密度重新生成。库不提供 SVG / PDF 输出:袜身是逐像素算法,转矢量需要另写渲染器,输出只有 PNG。

文档

开发

git clone https://github.com/xie-huaaaan/stockchart.git
cd stockchart
uv sync
uv run python -m pytest
uv run ruff check . && uv run ruff format .
uv run python -m pyright

欢迎提 issue 或 PR。

状态

0.1.x 是早期公开版本。渲染管线已经稳定,但公开 API 仍可能在小版本中调整。

许可证

Copyright © 2026 xie-huaaaan。

源代码以 Mozilla Public License 2.0(MPL-2.0)发布。你可以在闭源项目中 使用 stockchart;如果修改了受 MPL 覆盖的源文件,这些文件需要继续以 MPL-2.0 提供。

内置腿部素材(src/stockchart/assets/leg_*.svg 与 legs.json)为 All Rights Reserved(保留所有权利),不在 MPL-2.0 覆盖范围内,详见 素材许可。素材可用于通过 stockchart 渲染图表, 你生成的图表归你所有;素材本身除作为未修改的完整软件包的一部分外,不得单独提取或再分发。

Metadata

Release files for stockchart 0.1.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for stockchart 0.1.1
File Size Uploaded Provenance Actions
stockchart-0.1.1.tar.gz 6.1 MB With provenance Details for stockchart-0.1.1.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for stockchart 0.1.1
File Interpreter ABI Platform Actions
stockchart-0.1.1-py3-none-any.whl Python 3 none any Details for stockchart-0.1.1-py3-none-any.whl

Total release size: 12.2 MB

Release files / stockchart-0.1.1.tar.gz

Download URL stockchart-0.1.1.tar.gz
Size 6.1 MB
Tags Source
SHA-256 checksum
How to use checksums
13611406ab99636a909094d8efb9c8268b8d76d2dff7247f0e2b2eabd0ee45fb
BLAKE2b-256 checksum
How to use checksums
7a1763f9bd268420f8fe28002e8dfbdcfad0a3bd610e5780361d9785877caf2a
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 1, 2026.

Transparency log

Release files / stockchart-0.1.1-py3-none-any.whl

Download URL stockchart-0.1.1-py3-none-any.whl
Size 6.1 MB
Tags Python 3
SHA-256 checksum
How to use checksums
22e94595016c9976ffefca6f75d123d7a6853f2405480ddfa662bcf170a685a9
BLAKE2b-256 checksum
How to use checksums
594d987b4ab46b7aa20957deffd068ef77ecbaf0fd4a2cc36d1d2e746907371a
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 1, 2026.

Transparency log

Security for stockchart 0.1.1

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for stockchart-0.1.1.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 1, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.1.1 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page