Render

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:setup 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

shCopy code
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

shCopy code
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:

shCopy code
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:

yamlCopy code
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):

shCopy code
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

shCopy code
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):

shCopy code
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. --port <name> narrows that to one port, repeated for several — named the way the log names it, which for a port inside an assembly is the path of links and then the port (head:head_half_1:TL-m3). It says which ports rather than that any are drawn, so it goes with one of the three:

shCopy code
pc --no-ansi render -t png --view iso -O ./out/ports --with-all --port TL-m3 bracket

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. Rendering part of an assembly

--filter keeps only some of the links of an assembly or a scene, so a picture can be of one sub-assembly without a declaration for it. It takes a JSON or YAML file naming the links, or the same written out on the command line:

shCopy code
pc --no-ansi render -a -t png -O ./out --filter ./head.yaml logo
pc --no-ansi render -a -t png -O ./out --filter '{bone1: null, bone2: null}' logo
pc --no-ansi render -a -t png -O ./out --filter '[bone1, bone2]' logo

A link the filter names is kept and a link it does not name is dropped. A link named with nothing under it keeps everything under it; a link named with children under it keeps those children and drops its other ones. A link is named the way the Assembly YAML file names it — its name:, or the part or assembly it places — which is also the name a connect: uses, so read the .assy file to find out what the names are.

It needs the object named, with -a or -S saying which kind it is: a part has no links, and neither has a whole package, so both are refused. It is subject to §6 as well — the file is the one an unfiltered render would have written, under the object's own name — so give each filter a directory of its own.

Nothing is written into the package. There are two other ways to ask for the same thing, and the right one depends on how long the answer should last:

• a filter: on a render: file type in partcad.yaml — per file type, so one object can have a picture of one sub-assembly checked in beside the drawing of the whole of it. Use this when the user wants the subset kept; --filter overrides it for one run.
• pc filter FILTER SRC DST, which writes DST.assy and declares it beside SRC. Use this when the user wants the subset to become an object of the package — one that renders, exports and has a bill of materials of its own.

Say which you did rather than filtering the same assembly again and again.

9. 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.