Importing an STL or OBJ
Use Mesh (STL/OBJ) to bring a triangle mesh into your document as a body you can move, cut and build against. Deselect everything so the objects group appears in the toolbar, click Mesh (STL/OBJ), and the Insert Mesh panel opens in the bottom right.
Unlike a STEP import, this one asks questions first. A mesh has no units, no faces and no idea how accurate it is, and Kapy needs your answers to those before it can build anything.
The whole panel is in English whatever language the rest of the editor is in.
What to set before you insert
| Control | Default | What it decides |
|---|---|---|
| File | — | Choose STL / OBJ. The format is picked by the extension |
| Unit | mm | What one unit in the file means: mm, cm, m or in. Wrong here means a part a thousand times too big |
| Detect planar faces | On | Whether coplanar triangles are merged into single flat faces |
| Planar merge angle | 1.0° | How far two triangles may tilt apart and still count as the same flat face. 0 to 45 |
| Weld tolerance | 0.0001 mm | How close two points must be to be treated as one before anything else happens |
| Sewing tolerance | 0.01 mm | How wide a gap between face edges may be and still be stitched shut |
| Decimate | Off | Reduce the triangle count before building. Arms itself when the file is over budget |
| Target triangles | 50000 | The count to decimate down to |
Get the unit right the first time. Unit, weld tolerance and the decimation target are baked into the body when you press Insert and cannot be changed afterwards. Changing your mind means importing again.
Leave Detect planar faces on unless you have a reason. It is the difference between a body with a handful of usable flat faces and a body made of ten thousand triangles.
The 50,000 triangle ceiling
The readout under the file name tells you what the file holds. Over fifty thousand triangles it adds:
— over the 50,000 budget, decimate to import
and the Insert button goes dead. There is no import-anyway. Turn Decimate on, set a target, and Kapy thins the mesh before building. A scan or a sculpt will need this; a mechanical part almost never does.
The ceiling exists because every triangle that survives becomes real geometry, and a body with a million faces in it is not something you can work with even if it could be built.
What Kapy actually makes
The import is not a stored mesh with a pretty wrapper. Kapy builds a genuine solid body out of your triangles, in this order: it welds duplicate points, decimates if you asked, scales to millimetres, then grows flat regions, merging every run of coplanar triangles into one face with proper boundaries and holes. It sews those faces into a shell, and closes the shell into a solid only if that shell turns out to be watertight.
When it works, a toast reports what happened:
Mesh imported: 12,480 triangles → 214 regions → 231 faces · solid
Read the last word. solid means you have a closed body: booleans, cuts and printing all behave. open shell means the mesh had holes or unmatched edges and Kapy could not close it. It is still there, still visible, still exportable, but it is a surface rather than a volume, and operations that need a solid will not do what you expect. Raising the sewing tolerance and importing again is the first thing to try; repairing the mesh in a mesh tool is the reliable one.
Where the surface curves, there is nothing to merge, and each triangle becomes its own three-sided face. Click a curved area of an imported mesh and you select one triangle, not the cylinder it belongs to. That is the honest state of the geometry: the curve is gone, and no import setting brings it back. Flat regions that did merge, on the other hand, behave like any other flat face, and you can sketch on them and pick them normally.
If the same part is available as a STEP, import that instead. Importing a STEP File gets you true curves and a fraction of the faces.
After the import
The panel closes itself on success and the gizmo comes up, so drag the arrows to move the body and the rings to turn it. As with STEP, position and rotation are gizmo work and are not repeated in the timeline popover.
The popover holds what is still adjustable:
| Control | Note |
|---|---|
| File | Read-only. Which file this body came from |
| Scale | Uniform, minimum 0.001. This is on top of the unit you chose at import |
| Detect planar faces | Re-runs the merge. See the warning below |
| Planar merge angle | Same |
| Ghost | Draws the body semi-transparent and unpickable, as a reference |
Unit, weld tolerance and the decimation you accepted are not on that list. They are part of the body now.
The Ghost switch here behaves exactly as it does on a STEP import, including the part people get caught by: a ghost is drawn as a reference but is still written into an STL export. Hide or delete it before you export. Exporting Your Model has the whole list.
When it fails
The format comes from the extension, and only from the extension. A file ending .obj goes to the OBJ reader; everything else goes to the STL reader. Rename a .ply to .stl and it is fed to the STL reader, which fails with:
Could not read that file.
The same message covers a genuinely damaged STL. Binary and ASCII STL are both read, and Kapy tells them apart by the file's size rather than by its header, so an ASCII-looking binary file is not a problem.
The OBJ reader takes vertices and faces and ignores everything else: normals, texture coordinates, groups, smoothing and materials are all dropped. Faces with more than three corners are cut into triangles.
That file has no triangles.
The file was read and held no faces. An OBJ that is all curves and no mesh lands here.
This mesh has too many triangles — decimate it to a lower count and try again
The budget again, this time from the build rather than from the panel.
Could not build a body from this mesh — it may be empty or badly formed
The triangles were there and would not become a body. Try a larger sewing tolerance, then a larger weld tolerance, then repair the mesh outside Kapy. The panel stays open on an error precisely so you can change a number and press Insert again.
Meshes only come in through the editor
There is no mesh route in the file manager. Drop an STL there and you get Unsupported file. Import a .kpy or .step file., which does not point you here. Open or create a model first, then use this tool.
See also
- Importing a STEP File: the better import when you have the choice
- Exporting Your Model: what a ghost body does to your STL
- Creating and Importing Files: what the file manager will and will not accept
- Working with Several Bodies: hiding and naming the body you have just made