|UI location||3D View Toolbox|
|Usage||The Export Paper Model operator produces an SVG document from the active Mesh object. Further controls are available in the 3D View Toolbox.|
|Version||0.9||Author(s)||Adam Dominec (Emu)|
|Current version download||https://raw2.github.com/addam/Export-Paper-Model-from-Blender/master/io_export_paper_model.py|
|Python modules||mathutils, bgl, re, itertools|
|Known Issues|| Doubled vertices and tilted polygon faces may result in a useless net or an error.
The feature Limit Island Size is currently broken. The new painting workflow of Blender 2.72 is not supported yet.
This script generates a flat net of a given mesh. It creates SVG files suitable for direct printing and paper modeling. The main goal is a maximal possible automation of the whole process. Common tasks like baking the model's texture into the output document are also supported.
- Download the file directly from the Git repository. If you directly use the "Save Link as..." function of your web browser, it should work. Or you can open the link and use "Save Page as...", just make sure that the file name ends in ".py".
- Launch Blender. In User Preferences (CtrlAltU), section Addons, click the Install From File... button below. Choose the file you downloaded. Then find an addon called Import-Export: Export Paper Model and enable it.
To avoid potential issues, switch to Object Mode. Then, select the mesh you want to export so that it is the active one. If you want to get results quickly, just execute this script from the File → Export menu (or find the Export Paper Model operator in the Space menu). It will ask for a file name and do everything else automatically. All related settings are in the bottom left corner. These are described in more detail below.
If you are somehow unhappy with the generated net, you can edit it manually. For this, you have to execute the Make Unfoldable operator first (available in the 3D View Toolbox or via the Space menu). Edges that will be cut in order to flatten the mesh must be marked as edit mode seams. You can use Clear Seam and Mark Seam tools to organize them as you wish. If you export the model afterwards, it will take the given seams and add some more cuts as necessary.
You can call the Make Unfoldable operator just to have a preview of the net. It will list all islands of the produced net in 3d View T toolbox and if you enable so in the operator's settings, it will also create an UV layout showing the islands. Note that island positions are not calculated, so that they will just lay on top of each other. You can use Blender's Pack Islands operator to see them all.
N-gon faces (i.e., all except triangles) that are not perfectly flat will not get exported correctly and may distort the whole net. You will not be warned about that (except for a messy message in the console), so if you have a suspicion, better convert the mesh to triangles (CtrlT).
Exporting Textured Meshes
To export your model with a hand-painted texture, you have to unwrap the model, paint an image and assign it to all faces of the model's active UV Map. You can use any tools you like for these tasks.
Especially if you use Texture Paint Mode for the drawing, make sure to select all faces in Edit Mode and assign the right image to them in the UV/Image editor. The new Paint Slots stack is not supported yet. Switch to Object Mode and deselect any objects except the one to be exported. Then execute Export Paper Model and when the file dialog appears, switch the Textures dropdown menu to Face Texture.
The exported image is supposed to ignore all material settings and lighting conditions – in fact, the script creates a temporary shadeless material for that purpose. If you prefer to use the material settings, you have the option to export the model in all its glory by choosing Full Render from the dropdown menu.
You also have several options how to include the images in the file. All the options are explained in more detail in the section Available Settings.
The script cannot process the texture directly; rather, it exploits Blender's bake render functionality to do so. The script makes an attempt to sanitize all the related settings so that the result does not depend on their original state. If you find something (a switch in the properties panel, perhaps) that breaks the export, please report it to the Issues tracker on Github or in the BlenderArtists thread.
How to Read the Net
Most of the document's appearance can be customized during export (see below). However, the default style is supposed to be familiar to paper modelers: dashed lines represent folding outwards, dash-dotted lines inwards (i.e., to form concave shapes). Boundary of each part of the net is rendered in solid lines. Currently, sticking tabs are also separated by a solid line -- that is clearly inconvenient and will be solved in the upcoming version of the script.
A label is written on a tab if its target edge might not be clear. Specifically, the label is omitted if the edge will be sticked to the same place as its both neighbors or if one of these is the target itself. The format of labels is island abbreviation:edge number. Island abbreviation is written in square brackets under the corresponding island, before to its full-length name. Edge number is written as a triangle arrow next to that target edge, outside the net.
If Create Tabs is disabled, the same format is used for labels along each of the related edges, inside the net. It is designed for modeling from hard and/or thick materials, for which sticking tabs are quite pointless. If Create Numbers is disabled, the labels are omitted whatsoever.
How to Print the Net
The SVG graphic format can be opened in most of today's Web browsers, and directly printed. A downside of this approach is a waste of space to the top and the bottom of the page, where browsers usually print some information about the document.
A more flexible option is to use a vector editor such as Inkscape or Illustrator, which support direct printing and/or export to PDF. This way also allows you to pack the islands manually to spare on paper. PDF may be a preferred format for sharing paper nets but the script cannot export it directly, yet.
You have to choose an appropriate Margin distance during the export. Setting this value to zero and allowing the printer to scale your document appropriately may be the easiest solution, but it may cause a different scale be applied to each page. For instance, if just a single small island remains on the last page of the document, the printing software may be overly involved and scale it up so as to cover the whole page. To prevent this, it is more reliable to set a Margin according to your printer and print in 100% scale. The actual margin values vary but are easy to find out by a single trial and error.
3d View Toolbox
The Paper Model tab in the toolbox offers two buttons for calling the Make Unfoldable and Export Paper Model operators conveniently.
Once the Make Unfoldable operator is called, the model is split into islands and these are presented in a list between the two buttons. The list allows you to change the label of each island, but that currently has no effect (but will in the future).
If you select an island and enable the Highlight Selected Island button (and the mesh you unfolded is the active one), the island will be highlighted in orange in the 3d View. Using the slider below, you can change the highlighting opacity.
You can edit the label of each of the islands. If Create Numbers is enabled during export, abbreviations of these labels will be used to describe which tab should be sticked to which island. After running the Make Unfoldable operator, these island labels are recalculated so that as many faces as possible remain under the same label. It may cause several islands to be labeled the same way.
Make Unfoldable Operator
The first option is Create UVMap. If enabled, a new UVMap will be generated to show all the islands. However, their positions are not calculated yet at this time of the export process, so they are all just placed in the bottom left corner. They are all in the same scale, which need not correspond to their scale during export. This option is useful when editing the cutting lines by hand. You can use the Unwrap operator to get a similar result.
The operator has three sliders, which all adjust edge cutting priority (namely: Face Angle Convex, Face Angle Concave, Edge Length). A high value gives an edge with the corresponding property more chance to be cut. Because of that, it is usually better to set Edge Length to a negative value, letting long edges stay connected. Blindly moving them may often help to reduce the count of islands in the net. For information about the meaning of these values, read the How It Works → Make Unfoldable part of this document.
Export Paper Model
When the export is initiated, the script silently unfolds the mesh (without marking any seams) and divides all faces into islands, which may take a few seconds for complex meshes. Then, a file select window is displayed. The file name you choose will get a "_page<number>.svg" suffix, even if only one page was needed. If images are needed, they are saved under the same name with an extension ".png".
Settings of this operator are presented in the bottom left corner of the file select window.
Model Scale can be used to scale the whole net. If you want to have a model in 1:72 scale, just set this to 72. This is an important option also because the script often produces islands bigger than the page. By default, this value is set so that even the biggest island fits onto the page. If set to one, the real model should have the same dimensions as the virtual one.
Create UVMap has a similar effect as the eponymous option of the Make Unfoldable operator, but not the same. It will create a new UV Map that exacly reflects the placement of all the model's islands. Unfortunately, islands from all pages are placed atop of each other, since it is not easy to group them apart.
Settings closely related to the format of the output document are in the frame Document Settings.
First list box allows you to choose one of the most common paper sizes quickly. If you need something else, choose User Defined and
The Page Margin makes it easier to export models in exact scale (if you set the Model Scale slider to 1). You can set it to the width of the non-printable border of your printer, in order for the resulting SVG document to be printable without further scaling. However, exporting in-scale models is still difficult, as the script does not automatically split oversize islands.
The next value is DPI, which defines the overall resolution of the net. That is, not only resolution of baked images (if any), but also line thickness.
Create Tabs controls if the sticking tabs are created at all. For example, uncheck this if you want to stick the model using duct tape.
Create Numbers adds numbers to some edge pairs that are to be sticked together. These numbers are excluded if the correct destination is easy to guess from the neighboring edges. However, the resulting SVG will be bigger and may not render correctly in some programs. Disabling this option may help solve such issues. If Create Tabs is disabled, the numbers will be rendered inside of the net.
Tabs and Text Size sets maximal width of the sticking tabs around islands. The actual size of each tab is adjusted to be at most half the length of the corresponding edge. In some special cases, tabs are made not to overlap with real faces, but it does not work reliably yet. If Create Tabs is disabled, this slider controls the size of numbers on edges.
The Textures drop-down menu lists options for exporting textured meshes. By default, it is switched to No Texture, which just creates the net on a white background (it used to be called Pure Net). The remaining options invoke Bake Render and therefore are noticeably slower. Face Texture exports the image that is assigned to each of the model's faces (regardless of their material), likely as you see it in the Texture Paint mode. Full Render and Selected to Active correspond to the respective Bake Render options. They both render all the materials and illumination: Full Render renders the model only, while Selected to Active projects other nearby selected objects onto the model. It may be helpful for creating patterns such as fur or leaves procedurally.
The Images drop-down menu allows you to choose how to include the baked images in the SVG file. If you want to edit the layout of the net in an SVG editor, choose either Linked or Embedded. The Embedded option creates stand-alone SVG files, making them bigger but portable.
A plentiful of options related to the drawing style is packed in the Colors and Style frame. I believe these are all self-explanatory. Please note that the line width is in units of pixels, so increasing the DPI option above makes the lines thinner.
Feature requests, bug reports and all other constructive comments are most welcome. A publicly accessible TODO list is managed along with the git repository. Or if you prefer so, you may comment on the script at Blenderartists.org thread.
How It Works
Firstly, the algorithm assigns every edge a "priority", depending on its angle and length. Edges with higher priority will more probably be cut apart in the final net. Shorter edges have higher priority (they are easier to glue on) and sharper angles too (that makes the net easier to understand).
Faces form a concave angle if their normals are pointing against each other. Such angles have even a bit higher priority which is supposed to help for typical models. If some face normals are flipped, the algorithm always assumes the angle between them be convex.
If more than two faces are connected by an edge, two of them are designated as the main ones and all others will have to be glued. The main faces are chosen so that they form the smallest angle possible.
The actual priority effect of angle versus length may change the resulting net very much. The default values were chosen by trial and error for soma basic models, but may be a bad choice for others. If you want to tweak them, the Make Unfoldable operator allows you to: they are the operator's three only settings.
The cutting algorithm begins with all faces separated and tries to connect them to form bigger islands, ordered by the connecting edge's priority. If some of the faces of the resulting island would overlap, the operation is canceled and the algorithm continues with another edge. If some vertices or edges end up close enough to each other, they are merged. The process stops as soon as all edges of the mesh have been visited.
The overlap check is basically the Bentley-Ottmann algorithm for line segment intersection, applied to the boundary of the resulting island. To handle some special cases, the algorithm automatically switches between a slightly quicker and a more robust version of itself. Another check is applied to detect if the boundary crosses itself in a vertex of the resulting island – such cases have to be tested explicitly as they need not cause any intersecting line segments.
Positioning the Nets on Pages
Because the nets are not consisting only of the real faces, but also of the gluing tabs around, they cannot be positioned by the internal Blender operator (Pack Islands). Therefore, a stand-alone algorithm had to be written.
For a great simplification of the process, all nets are packed into (smallest possible) bounding rectangles. These are then ordered by size (largest first) and in this order the algorithm tries to emplace them on a page. The positions tested for the lower left corner are given by an n×n grid resulting from all the corners of islands already positioned. A position is accepted or rejected by checking overlaps with each of the islands' bounding rectangles.
When there are any islands left that could not be placed onto the page, a new free page is created.
This algorithm should work reliably and quite fast. However, it is clearly inefficient if the bounding rectangles contain much free space. Also, the packing depends heavily on the order in which the islands are processed, which is in no way optimal.