Immutable. This exact content is served forever at /api/v1/blob/bf68ac91983a4b1b.
---
name: render
description: Render a PartCAD object or a CAD file to a 2D image - PNG, JPEG, SVG or DXF - from one or many viewing angles (front, back, left, right, top, bottom, iso, or an arbitrary direction), with `pc render` for an object a package declares or `pc adhoc render` for a file that belongs to no package. Use for /pc:render or when the user asks to render, draw, screenshot, preview, or produce an image or projection of a part, sketch, assembly or CAD file, or to see it from a particular view, or to draw an object's ports and interfaces on it (--with-ports / --with-interfaces / --with-all). For geometry another CAD tool can open use /pc:export or /pc:convert.
---
# pc:render
Produce a picture of a shape: a 2D projection, in `png`, `jpeg`, `svg` or `dxf`.
`$ARGUMENTS` says what to render and, often, from where.
A render is not a conversion. It writes something to look at, not geometry
another CAD tool can go on working with — that is `/pc:export` (or `/pc:convert`
when the object should *become* the new format). The viewing angle only means
anything here.
Two commands do it:
- **`pc render`** — an object a package declares. Reads the package's `render:`
configuration, so the object is drawn the way the package publishes it.
- **`pc adhoc render`** — a file that belongs to no package. PartCAD wraps it in
a throwaway package, writes the picture, and deletes the package again.
## 1. Work out which case you are in
Do this before running anything. It is the same first step in `/pc:convert` and
`/pc:export`.
1. **Is there a package?** PartCAD searches upward for `partcad.yaml`, so look in
the current directory and above. `pc --no-ansi list` lists what the package
holds; if there is no package it says so.
2. **Does the reference name an object?** Check it against
`pc --no-ansi list parts` / `list sketches` / `list assemblies`.
`pc --no-ansi info <name>` succeeds only for an object that resolves.
3. **Does a file the user named belong to an object?** Someone who says "render
`bracket.step`" inside a package usually means the part built from it. Read
`partcad.yaml` and look for an object whose `path:` is that file — and note
that a file-backed object *without* a `path:` is `<name>` plus the type's
extension, so a part `bracket` of type `step` is `bracket.step` whether or not
the path is written down.
**If 2 or 3 matched, it is an object: use `pc render` (§3).** That way the
package's own `render:` options apply — its pixel size, its prefix, the viewport
it publishes the object with — and the picture matches every other picture of
that package.
**If there is no package, or the file is not one an object is built from, it is
ad-hoc: use `pc adhoc render` (§4).**
## 2. Make sure PartCAD is available
Resolve a command as `/pc:init` does (`pc`, then `partcad`, then
`python -m partcad_cli.click.command`). If none is found, stop and run
`/pc:install executable` first.
Pass `--no-ansi` on every run so the output is plain text. It is a global flag
and goes before the subcommand, and it routes the logs to **stderr** — so
capture both streams when reading them: `pc --no-ansi render ... 2>&1`.
## 3. An object in a package — `pc render`
```sh
mkdir -p ./out # -O expects the directory to exist
pc --no-ansi render -t png -O ./out bracket # a part
pc --no-ansi render -t png -O ./out -a gearbox # an assembly (-a)
pc --no-ansi render -t svg -O ./out -s outline # a sketch (-s; SVG suits one better than PNG)
pc --no-ansi render -t png -O ./out -P //pub/std bolt # an object in another package
```
Formats: `png`, `jpeg`, `svg`, `dxf`, plus any a package implements itself.
`-t readme`, `-t pdf` and `-t html` are documents rather than projections (a
package README, or an assembly's bill of materials and instruction book) — they
take no viewing angle.
The file is written into `-O` and named after the object. Nothing about the
package changes.
## 4. A file with no package — `pc adhoc render`
```sh
pc --no-ansi adhoc render part bracket.step bracket.png
pc --no-ansi adhoc render part --output svg bracket.step # names the output after the input
pc --no-ansi adhoc render part --input step bracket.dat out.png
pc --no-ansi adhoc render sketch outline.svg outline.png
```
Both types are inferred from the file names; `--input` and `--output` say them
outright. The input may be any type PartCAD reads — including the scripted ones
it cannot write back out (`sdf`, `scad`, `chili3d`), since reading is all a
picture needs. The output is one of the four projections.
`urdf` and `assy` are refused here: both only mean anything inside a package. Put
the file in one (`pc import assembly`) and render it with `pc render`.
## 5. Choosing the angle
Both commands take the same three options.
`--view` names a direction — `front`, `back`, `left`, `right`, `top`, `bottom`,
`iso`. `--viewport-origin X,Y,Z` says where to look from and `--viewport-up
X,Y,Z` which way is up in the picture; each replaces the vector `--view`
resolved to, so a named view can be tilted by giving one of them alone:
```sh
pc --no-ansi render -t png --view front -O ./out bracket
pc --no-ansi render -t png --view top --viewport-up 0,1,0.5 -O ./out bracket
pc --no-ansi adhoc render part --viewport-origin 120,-40,60 bracket.step bracket.png
```
PartCAD is Z-up, with `+Y` pointing away from the front view — so `+X` is to the
right of it and `+Z` is up. Left unset, a part is drawn from the front-right-top
corner (`iso`), which is what makes it read as 3D, and a sketch head-on.
These are the same `viewport_origin` and `viewport_up` a `render:` file type is
configured with in `partcad.yaml`, passed for one command instead of written
down. If the user wants an object drawn that way *every* time, put it in the
configuration instead — and note this is only possible for an object in a
package, which is one more reason to prefer §3 over §4 when both would work:
```yaml
parts:
bracket:
type: step
path: bracket.step
render:
png:
viewport_origin: [0, -100, 0]
viewport_up: [0, 0, 1]
```
## 6. Several angles at once
A rendered file is named after the object, so views written into one directory
overwrite each other. Give each its own directory (`pc render`) or its own file
name (`pc adhoc render`):
```sh
for view in front top right iso; do
mkdir -p ./out/$view
pc --no-ansi render -t png --view $view -O ./out/$view bracket
done
```
```sh
for view in front top right iso; do
pc --no-ansi adhoc render part --view $view bracket.step bracket-$view.png
done
```
Then look at the images. Four views — `front`, `top`, `right`, `iso` — describe
most parts; add `back`, `left` or `bottom` only when the shape is not symmetric
about the axis in question.
## 7. Drawing the ports and interfaces
Ports and interfaces are not geometry — a port is a coordinate frame and an
interface is a named set of them — so nothing about them reaches a projection
unless it is asked for. `pc render` draws them (`pc adhoc render` does not: a
file with no package has none):
```sh
mkdir -p ./out/ports
pc --no-ansi render -t png --view iso -O ./out/ports --with-ports bracket
pc --no-ansi render -t png --view iso -O ./out/ports --with-interfaces bracket # overwrites the above
pc --no-ansi render -t png --view iso -O ./out/ports --with-all bracket # both at once
```
`--with-ports` marks and names every port, `--with-interfaces` names each
interface instance and joins it to the ports it owns, and `--with-all` draws
both. On an assembly or a scene all three walk everything inside it and place
each child's ports where it put the child, which is how a connection that went
wrong is found: two frames that should have met and did not. Every port drawn is
also named on stderr, which is where the exact string for an Assembly YAML file
comes from — so `--no-ansi`, and read both streams.
The overlays are subject to §6 twice over: each writes `<name>.png` like any
other render and so needs a directory or a name of its own, and a frame offset
along the line of sight is hidden exactly as a feature would be, so an ambiguous
port is worth the same several views the shape got.
A package can ask for this permanently instead, with `with_ports:` or
`with_interfaces:` on one of its `render:` file types. `/pc:add-interfaces`
covers reading these drawings when the ports themselves are what is being
worked on.
## 8. Report what happened
Name the files that were written, with their paths, and which view each one is.
Nothing in this skill changes `partcad.yaml` — say so if the user might have
expected otherwise. If PartCAD printed an error, surface it verbatim.
When the user wanted a description rather than the pictures themselves,
`/pc:describe` writes one from a render.