|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://git.blender.org/gitweb/gitweb.cgi/blender-addons-contrib.git/blob_plain/refs/heads/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 eventual 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 relevant 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 Unfold 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, or use the helper button Clear All Seams in Object mode to start from scratch. When you export the model, it will use all the given seams and add some more cuts if necessary.
You can also call the Unfold operator just for 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 in this stage, so that they will all just lay on top of each other. You can use Blender's Pack Islands operator to arrange them.
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). Usually, there is nothing to lose.
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 the model so that it has an effect during render. You can use any tools you like for these tasks. What the script does is simply that it uses Bake render in Textures mode.
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 From Materials.
You also have several options how to attach the images to the SVG file. All the options are explained in more detail in the section Available Settings.
The resulting texture does not depend on any scene settings except for the given material, and on the other hand, all settings should be intact after doing the export. If you find any problem with the previous sentence (such as, it be not true), please report it in the Blenderartists forum 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. Sticking tabs have a greyish fill color to be distinguishable from other parts of the net.
A label is written on a tab when 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 some 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 then force printing in 100% scale. The actual margin values vary but are easy to find out by a single trial and error.
Placing marks on the net
Edges with a Freestyle Mark (CtrlE → Mark Freestyle Edge) will be highlighted with a user-defined color and drawing style. This is helpful especially when used on flat edges, which would normally not be drawn at all. If you draw a shape with the Knife Tool and then mark some of the edges as Freestyle ones, you can create a simple line drawing.
When used on folding edges, the highlight will be drawn below the folding line. Therefore, you will probably have to change the Freestyle Lines drawing style to make it wider and not black, so that the lines stay distinguishable.
3d View Toolbox
The Paper Model tab in the toolbox offers two buttons for calling the Unfold and Export Paper Model operators conveniently. It also offers buttons for marking and clearing seams, depending on the context, and the experimental functionality Limit Island Size.
Once the Unfold operator is called, the model is split into flattened parts and these are presented in a list called Islands. The list allows you to change the label of each island. 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 Unfold operator, these island labels are recalculated so that as many faces as possible remain under the same label. Unfortunately, it may cause several islands to be labeled the same way.
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 opacity of the highlight.
The first option from top 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 a higher chance to be cut. Because of that, it is usually better to set Edge Length to a negative value, letting long edges stay connected. Randomly modifying 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 Unfold 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 browser window.
The Preset menu allows you to quickly save and recall all the settings below it, including model scale and color style.
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 Unfold 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 set the dimensions manually.
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. From Materials exports the image that is assigned to each of the model's faces in their active material. 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. They should be quite self-explanatory. Please note that 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 the 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 visually 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 Unfold 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. During this process, each edge is visited exactly once.
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 just 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.