🧶 BCC Yarn Viewer 🧶

An interactive Polyscope viewer for .bcc yarn-level cloth models. The .bcc (Binary Curve Collection) format comes from Cem Yuksel's yarn-level cloth work.

Contents — Features · Sample models · Install · Usage · Project layout · .bcc format · Acknowledgements

---

Features

Feature		Description
Tube rendering		Each strand drawn as a tube, auto-sized from the yarn gauge
Free-orbit camera		True trackball navigation with optional auto-rotate
Color modes		Solid, per-curve id, curvature, and baked ambient occlusion
Materials & color		Live color picker and 8 matcap materials
Curve isolation		Scrub a slider to isolate and inspect one yarn
Cutaway		Slice-plane clip at any orientation — axis presets, azimuth/elevation, and position
Drag & drop		Drop a .bcc onto the window to load it

Note

Cutaway clips the yarn with a scene slice plane to look inside a dense knit. Orient it at any angle (axis presets or azimuth/elevation sliders), slide the cut position, drag it in the scene, or hide the plane while keeping the clip. It also trims render overdraw on the clipped side.

Color modes

Mode		Shows
none		Solid yarn color
curve id		Each strand a distinct color
curvature		Discrete Menger curvature per point
ambient occlusion		Baked directional AO proxy

Views

The yarns structure — curvature, per-strand ID, & normals can also be visualized:

Sample models

Note

No .bcc models are bundled with this repo - Sample Yarn-level models can be found at: Cem Yuksel's Yarn-level Cloth Models and should be placed into Assets/BCC/

Install

pip install -r requirements.txt

Requires Python ≥ 3.10. Dependencies: numpy, scipy, polyscope.

Important

Ambient occlusion and automatic tube sizing use SciPy's KD-tree. Without SciPy the viewer still runs — it just falls back to flat shading and a heuristic radius

Usage

python3 Src/main.py path/to/model.bcc      # open a file
python3 Src/main.py                        # no arg → native file picker

Flag		Effect
path		.bcc file to open; omit to get a file picker
--radius R		Tube radius in world units (default: auto from yarn gauge)
--no-up		Ignore the file's up-axis (upDimension) field
--summary-only		Print stats and exit, without opening a window

Controls

Input	Action	Input	Action
	Toggle auto-rotate		Show all curves
	Reset camera view		Open a file
	Orbit		Zoom

Project layout

📂 Project structure — click to collapse

BCC Yarn Viewer/
├── README.md
├── requirements.txt
├── .gitignore
├── LICENSE
├── Docs/
│   ├── rotate.gif            # rotating hero animation
│   ├── shading.gif           # solid + ambient occlusion
│   ├── views.gif             # curvature / curve id / normal
│   └── samples.gif           # sample-model gallery
├── Assets/
│   └── BCC/                  # put downloaded .bcc models here (not bundled)
└── Src/
    ├── main.py               # CLI entry point
    └── bccviewer/
        ├── __init__.py       # package API
        ├── bcc.py            # .bcc binary format + data model      (numpy)
        ├── geometry.py       # edges, curvature, strand gap, AO     (numpy / scipy)
        ├── dialogs.py        # native file-open dialogs             (stdlib)
        └── viewer.py         # Polyscope window + Viewer GUI        (polyscope)

The bcc, geometry, and dialogs modules are pure — they import and run without a display or GPU, so the parser and analysis can be exercised headlessly. Only viewer pulls in Polyscope:

graph TD
    A["main.py<br/>CLI entry point"]:::entry --> V["viewer.py<br/>Polyscope window + GUI"]:::gpu
    V --> G["geometry.py<br/>edges · curvature · AO"]:::pure
    V --> B["bcc.py<br/>.bcc format + data model"]:::pure
    V --> D["dialogs.py<br/>file dialogs"]:::pure
    G --> B
    A -.-> B
    A -.-> D
    classDef entry fill:#1c4e80,stroke:#4c9aff,color:#fff;
    classDef gpu   fill:#8b3a1a,stroke:#F26430,color:#fff;
    classDef pure  fill:#1f6f3f,stroke:#2ecc71,color:#fff;
    linkStyle 5,6 stroke:#667,stroke-width:1px,stroke-dasharray:4;

Loading

Note

main (blue) is the CLI; viewer (orange) is the only module that drives Polyscope; the pure core (green) — bcc, geometry, dialogs — has no display or GPU dependency and can be imported and tested headlessly. Solid arrows are the primary dependency path; the dashed arrows are main's direct helper calls into the core.

The .bcc format

Binary Curve Collection is a deliberately minimal, little-endian (x86) format: a fixed 64-byte header followed by a data block of per-curve records.

graph TD
    BCC[".bcc file"]:::file
    BCC --> H["Header<br/>64 bytes"]:::hdr
    BCC --> D["Data block<br/>variable length"]:::data

    H --> H1["0–2 · signature 'BCC'"]:::hdr
    H --> H2["3–7 · precision, curve type,<br/>dimensions, up-axis"]:::hdr
    H --> H3["8–23 · curve &amp; point counts<br/>(uint64 each)"]:::hdr
    H --> H4["24–63 · file info<br/>(40-byte ASCII)"]:::hdr

    D --> C1["curve record"]:::data
    D --> C2["curve record …"]:::data
    C1 --> P["int32 point count<br/>negative = closed loop"]:::data
    C1 --> XYZ["control points<br/>x, y, z (float32)"]:::data

    classDef file fill:#1c4e80,stroke:#4c9aff,color:#fff;
    classDef hdr  fill:#8b3a1a,stroke:#F26430,color:#fff;
    classDef data fill:#1f6f3f,stroke:#2ecc71,color:#fff;

Loading

Header (64 bytes)

Bytes	Field	Type	Value in these files
	Signature		BCC (ASCII 42 43 43)
	Precision		0x44 — 4-byte ints & floats
	Curve type		C0 — Catmull-Rom, uniform
	Dimensions		3
	Up axis		1 or 2 (y or z direction)
	Curve count		total number of curves
	Control-point count		total across all curves
	File info		free-form ASCII string

Important

The models are C0 Catmull-Rom curves, but this viewer draws the raw control points as a polyline (straight segments between them) — a fast, close approximation of the smooth spline, not the exact curve. Any non-C0 curve type still loads, but is shown as a raw polyline with a warning.

Acknowledgements

• .bcc format & sample models — Cem Yuksel, from Yarn-level Cloth Models / Stitch Meshes
• Format spec & loader — Using Binary Curve Collection files (cyCodeBase)
• Rendering — Polyscope
• License — MIT (viewer source only; sample models retain Cem Yuksel's terms)