Skip to main content

VStitcher-CLI live examples

Updated this week

Example 1: Find colors used in the current colorway

What this does
Retrieves all colors that are actively used in the currently selected colorway.

Why it’s useful

  • Understand which colors are driving the look

  • Prepare logic for color-based material or render decisions

import BwApi

gid = BwApi.GarmentId()
colorway_id = BwApi.ColorwayCurrentGet(gid)

colors = BwApi.ColorwayColorsInUseGet(gid, colorway_id)

print("Colors used in current colorway:")
for c in colors:
  print(c)

Example 2: Find materials that use a specific color

What this does
Finds materials that are associated with a selected color in the current colorway.

Why it’s useful

  • Update materials programmatically

  • Identify which materials will be affected by a color change

import BwApi
gid = BwApi.GarmentId()
cw  = BwApi.ColorwayCurrentGet(gid)

# pick one color from the colorway 
target_color = BwApi.ColorwayColorsInUseGet(gid, cw)[0]

materials = BwApi.MaterialIds(gid)
matching_materials = []

for mid in materials:   
  mat = BwApi.MaterialGet(gid, mid)   
  if hasattr(mat, "color") and mat.color == target_color:
matching_materials.append(mid)

print("Materials using selected color:", matching_materials)

⚠️ Note
Some builds resolve color → material through containers or overrides.
If this returns no results, inspect MaterialGet() output using Python Playground.

Example 3: Load a color palette and search for a color

What this does
Loads a color library (palette) and finds a color by name.

Why it’s useful

  • Automate color assignments

  • Validate palette contents before applying colors

import BwApi

gid = BwApi.GarmentId() 

libraries = BwApi.ColorLibraryIds(gid) 

for lib_id in libraries:   
  name = BwApi.ColorLibraryNameGet(gid, lib_id)  
  print("Library:", name) 

# choose a library by name
library_name = "My Color Library"
lib_id = next(
     l for l in libraries
     if BwApi.ColorLibraryNameGet(gid, l) == library_name
) 

BwApi.ColorLibraryCurrentSet(gid, lib_id) 

colors = BwApi.ColorLibraryGetColors(gid, lib_id) 

for c in colors:   
  if "red" in str(c).lower():     
    print("Found color:", c)

Example 4: Render garment using a preset

What this does
Runs a headless render/export using a JSON preset via RenderExportByPreset.

Why it’s useful

  • Automated image exports in pipelines

  • Reproducible renders using saved preset JSON

Common pitfall (and how to avoid it)
If you see an error like:

plugin init failed for C:\Users\...\export_using_preset.py

One common cause is attempting to render before the garment/avatar is prepared and dressed.
Per the RenderExportByPreset documentation, you should run these steps before rendering:

  • GarmentPrepare

  • GarmentDress

  • SnapshotLoad

Also:

  • Test render in VStitcher UI first

  • Export a working preset from the UI and reuse it in your script

  • Ensure render mode is Normal render (RenderExportByPreset does not work with Ray Trace)

Slim, recommended code flow

import BwApi
gid = BwApi.GarmentId()
out = r"C:\CLI-TEST\output" 

# Required preparation before RenderExportByPreset BwApi.GarmentPrepare(gid) 
BwApi.GarmentDress(gid) 

# If you rely on a saved visual state (colorway/avatar), load snapshot 
# (pick the snapshot you want) 
snap = BwApi.GarmentSnapshotIdsEx(gid)[0] 
BwApi.SnapshotLoadEx(gid, '{"load_snapshot_option":"saved_colorway_and_avatar","sync_snapshot":true}', snap) 

# Render/export by preset (Normal render only, not Ray Trace) 
preset = r''' 
{
   "exportType": "image",
   "fileFormat": "png",
   "background": ["transparent"],
   "width": 2000,
   "height": 2000,
   "useDpiRes": false 
} 
''' 

BwApi.RenderExportByPreset(gid, preset, out) 
print("Render started. Output:", out)

Tip for troubleshooting

  • If it still fails, first render the same garment in VStitcher UI successfully, then export the preset from UI and compare it to your JSON (this is the quickest way to validate the preset structure and settings).

Example 5: Create a Bezier edge from points

Where: create_edge_from_points(garment_id, shape_id, edge_points)

What it shows

  • How to build geometry from scratch by creating a Bezier edge

  • How to define:

    • main vertex (BwApi.Point)

    • two handles (BwApi.CoordinatesXY)

    • bezier point (BwApi.BezierPoint)

  • How to commit the edge to a shape using BwApi.EdgeCreateAsBezier

Core idea (simplified)

tmp_point   = BwApi.Point(x, y, pointType, gradeId) 
tmp_handle1 = BwApi.CoordinatesXY(h1x, h1y) 
tmp_handle2 = BwApi.CoordinatesXY(h2x, h2y) 

bz = BwApi.BezierPoint(tmp_point, tmp_handle1, tmp_handle2) BwApi.EdgeCreateAsBezier(garment_id, shape_id, [bz, ...])

Example 6: Export GLB without white / missing colors

Issue
GLB export appears white when:

  • Snapshot is not loaded before export

  • alpha_mode is set to "BLEND"

Fix

  1. Load snapshot

  2. Set colorway after snapshot load

  3. Use alpha_mode = "OPAQUE" or "MASK"

Minimal working example

import BwApi

BwApi.GarmentOpen(r"C:\CLI-TEST\WelcometoBW_Outfit.bw") 
gid = BwApi.GarmentId() 

# Load snapshot 
snap = BwApi.GarmentSnapshotIdsEx(gid)[0] 
BwApi.SnapshotLoadEx(   
  gid,     '{"load_snapshot_option":"saved_colorway_and_avatar","sync_snapshot":true}',   
  snap 
) 

# Force recoloring 
BwApi.ColorwayCurrentSet(gid, BwApi.ColorwayCurrentGet(gid)) 

# Export GLB (DO NOT use BLEND) 
preset = r''' 
{
   "exportType": "gltf",
   "gltfType": "glb",
   "alpha_mode": "OPAQUE" 
} 
''' 

BwApi.RenderExportByPreset(gid, preset, r"C:\CLI-TEST\output")

Key notes

  • Always load snapshot before exporting

  • Always set colorway after snapshot load

  • Use OPAQUE or MASK for GLB exports

Example 7: RenderExport3DObject – single UV layout for all pieces

Goal
Export one combined UV layout for all pattern pieces using RenderExport3DObject.

Correct layout configuration

To generate a single UV layout (not per piece), use:

"layout": {
   "layout_type": "layout_uv",
   "piece": "all_pieces_bounding_box",
   "dpi": 300,
   "file_format": "png" 
}

You must provide either dpi or pixels for this layout mode.

Minimal usage (Python)

import BwApi 

gid = BwApi.GarmentId() 

BwApi.RenderExport3DObject(  
   gid,  
   three_d_object_json,  
   {
         "layout_type": "layout_uv",
         "piece": "all_pieces_bounding_box",
         "dpi": 300,
         "file_format": "png"  
   },
   r"C:\output" 
)

What to keep in mind

  • per_piece → one UV layout per pattern piece

  • all_pieces_bounding_box → one combined UV layout

  • Some layout modes require extra fields (dpi or pixels)

  • If you see “invalid parameter”, check the layout attribute combination

Example 8: Create a shape from edge definitions

Where: create_shape_from_points(garment_id, shape_points)

What it shows

  • How to create a shape/panel on a garment

  • How to validate success using:

    • BwApi.GetLastError()

    • BwApi.BW_API_ERROR_SUCCESS

  • How to build a shape by repeatedly calling your edge-builder (create_edge_from_points)

Core idea (simplified)

shape_id = BwApi.ShapeCreate(garment_id) 
err = BwApi.GetLastError() 
if err != BwApi.BW_API_ERROR_SUCCESS:  
   return err, -1 

# then add edges using create_edge_from_points(...) 
return BwApi.BW_API_ERROR_SUCCESS, shape_id

Example 9: Create a graded rectangle (sizes + grade rules)

Where: create_graded_rectangle()

What it shows

  • How to create a new garment using BwApi.GarmentCreate()

  • How to create / configure sizes:

    • BwApi.SizeBaseGet()

    • BwApi.SizeNameSet()

    • BwApi.SizeAdd()

  • How to make a shape and apply grading rules:

    • BwApi.ShapeCreate()

    • BwApi.GradeRuleAdd()

    • BwApi.GradeRuleSet()

Why this is useful
This is a great “starter” example for automation where you need consistent parametric construction and grading.

Core idea (simplified)

garment_id = BwApi.GarmentCreate() 
base = BwApi.SizeBaseGet(garment_id) 

BwApi.SizeNameSet(garment_id, base, "M") 
BwApi.SizeAdd(garment_id, "L") 
BwApi.SizeAdd(garment_id, "XL") 

shape_id = BwApi.ShapeCreate(garment_id) 

rule_id = BwApi.GradeRuleAdd(garment_id, shape_id)
BwApi.GradeRuleSet(garment_id, rule_id, BwApi.CoordinatesXY(dx, dy))

Example 10: Build a simple “shirt” (front/back/sleeves) + symmetry + stitching + clusters

Where: create_shirt()

What it shows
This is the most “end-to-end” example in the file. It demonstrates:

Geometry construction

  • Create multiple shapes from point sets:

    • front panel

    • back panel

    • sleeves

Symmetry to complete a panel

  • Fetch edges of a shape: BwApi.ShapeEdgeIds()

  • Apply inner symmetry: BwApi.ShapeSymmetryCreate(..., INNER, last_edge)

Transformations

  • Read/write panel transform:

    • BwApi.ShapeTransformationGet()

    • BwApi.ShapeTransformationSet()

Stitching panels together

  • Stitch operations:

    • BwApi.StitchSide(...)

    • BwApi.StitchCreate(...)

Organizing shapes into clusters (front/back/arms)

  • Create clusters: BwApi.ClusterCreate()

  • Assign shapes: BwApi.ClusterShapeAdd()

  • Offset shapes inside cluster:

    • BwApi.ClusterShapeOffsetGet()

    • BwApi.ClusterShapeOffsetSet()

Why this is useful
This is basically a “mini garment generator” example that covers most of what people want to automate:

  • generate panels

  • connect panels

  • position panels

  • organize garment structure

Example 11: Error handling pattern using BwAPI status codes

Where: used inside create_shape_from_points() and create_shirt()

What it shows
A consistent pattern you can reuse everywhere:

  • Call a BwAPI function

  • Immediately check:

    • BwApi.GetLastError()

    • compare to BwApi.BW_API_ERROR_SUCCESS

  • Print an actionable message (and stop/return)

Core idea (copy/paste template)

result = BwApi.SomeOperation(...) 
err = BwApi.GetLastError() 

if err != BwApi.BW_API_ERROR_SUCCESS:  
   print(f"SomeOperation failed. err={err}")  
   return err
Related Articles
Create a Tech Pack
Bill of Material
VStitcher-CLI — Local Installation & Usage Guide
How to Start Working With VStitcher Engine (VS-CLI)
Debugging VStitcher-CLI Scripts with Python Playground
Did this answer your question?