Copyright (C) 2014 Attila Bagyoni
OrigamiScript is an open scripting language and an open-source scripting engine written as part of Origami Editor 3D. Its main purpose is simulating the mechanism of 3-dimensional paper folding in rigid origami.
The OrigamiScript Terminal can be accessed under the Scripting tab of the program. Commands entered into that interface are executed on the same origami model that is currently being edited in the GUI. In other words, GUI edits and OrigamiScript commands are interchangeable.
Origami Editor 3D can also open text files written in OrigamiScript as origami models; such files are much more verbose than standard ORI files.
This documentation explains the syntax and functions of OrigamiScript Version 1 and provides examples to cover all of its use cases.
Every OrigamiScript session has an own origami model it works on. In OrigamiScript, an origami is defined as a mapping from the 2-dimensional Euclidean space ('paper space') to the 3-dimensional Euclidean space ('origami space') for which there exists a finite cover of the domain consisting of polygons with disjoint interiors such that the mapping's restriction to each of these polygons is an isometry.
An origami model can be initialized, modified and outputted by using commands. Usually, a command takes one or more parameters specified before itself. A parameter is always written as a keyword followed by a vector or several vectors. A vector is a collection of strings or numbers separated by space characters and enclosed by square brackets: [ at the beginning and ] at the end. When a vector contains only one component, the brackets can be omitted.
The curved bracket { can be used for starting a comment, and } for escaping it. Strings between these brackets will not be parsed or executed.
Sets the OrigamiScript version used in the script. Has no use as of yet; currently, only version 1 is available.
If not specified, the interpreter's own version will be used by default.
Not disposable.
version version_number
where
Every command in this documentation
Sets the language for the current session. This includes the language of error messages, user prompts and exported PDFs. If the session is run inside an instance of Origami Editor 3D, it will also set the UI language. None of these changes abide after the current session is closed.
If not specified, English or, if supported, the system locale will be used by default.
Currently available languages:
locale[en US]locale[hu HU]locale[ja JP]Not disposable.
Creates a new paper of a preset shape or a rectangle with the specified dimensions.
Deletes every previously given corner parameter from memory.
Disposable.
paper [left bottom right top]
where
This syntax acts as a shorthand for corner [left bottom] corner [right bottom] corner [left top] corner [right top].
paper paper_type
where
square for a paper with corners [0 0], [0 400], [400 0] and [400 400]a4 for a paper with corners [0 0], [0 300], [424.3 0] and [424.3 300]hexagon for a paper with corners [300 346.41], [400 173.205], [300 0], [100 0], [0 173.205] and [100 346.41]usd for a paper with corners [0 0], [0 170], [400 0] and [400 170]huf for a paper with corners [0 0], [0 181.82], [400 0] and [400 181.82]Adds a new corner to the paper.
Still works without a paper parameter being specified beforehand.
Disposable.
corner [x y]
where
Creates a new plane with the specified position and direction.
Disposable.
plane [x y] [normal_x normal_y normal_z]
where
plane [x y z] [normal_x normal_y normal_z]
where
Changes the plane's position so that it goes through the specified point without its normal vector being changed.
Disposable.
planepoint [x y]
where
planepoint [x y z]
where
Changes the plane's normal vector.
Disposable.
planenormal [x y z]
where
Creates a new plane that goes through the specified 3 points.
Disposable.
planethrough [x1 y1] [x2 y2] [x3 y3]
where
planethrough [x1 y1 z1] [x2 y2 z2] [x3 y3 z3]
where
Origami space and paper space formats can be mixed, i. e. planethrough [x1 y1 z1] [x2 y2] [x3 y3 z3] is also a correct syntax.
Creates a new plane perpendicular to the specified triangle, that bisects the triangle's inner angle at the 2nd vertex.
Disposable.
angle-bisector [x1 y1] [x2 y2] [x3 y3]
where
angle-bisector [x1 y1 z1] [x2 y2 z2] [x3 y3 z3]
where
Similarly to the planethrough parameter, origami space and paper space formats can be mixed: angle-bisector [x1 y1] [x2 y2 z2] [x3 y3] is also a correct syntax.
Selects a new target point.
Disposable.
target [x y]
where
While executing a folding command with the target point on the plane throws no exceptions and has no known bugs, it should be avoided because the result will not be predictable, beating the whole concept of this parameter.
Creates a new rotation angle equal to the specified integer in degrees (°).
Disposable.
angle phi
where
Creates a new camera direction.
Disposable.
camera [x y z]
where
Creates a new file path based on the specified string.
Not disposable.
filename [name]
where
All duplicate white space characters will be removed by the parser. This is not an issue for UNIX-like operating systems and Mac OS X but can be a problem in Windows.
Sets the title for the PDF file generated by the next export-autopdf command.
Disposable.
title [name]
where
All duplicate white space characters will be removed by the parser.
Sets the paper color for the GIF file generated by the next export-gif or export-revolving-gif command.
Disposable.
color [rgb]
where
color [r g b]
where
Sets the origami model to the convex hull of all the currently loaded corner parameters, including the ones implicitly given in the last paper parameter. An [x y] corner in the paper space will be mapped to the [x y 0] point in the origami space.
This command deletes all disposable parameters from memory.
{Makes a square piece of paper}
paper square new
{Makes a house-shaped piece of paper}
paper [0 0 400 400] corner [200 -200] new
{Makes an octagonal piece of paper}
corner [0 100]
corner [100 0]
corner [300 400]
corner [400 300]
corner [300 0]
corner [400 100]
corner [0 300]
corner [100 400]
new
{Makes a square piece of paper, then overwrites it with a hexagonal one}
paper square new
paper hexagon new
Modifies the origami model by creasing it along the specified plane, then reflecting certain parts of the paper over it.
If a target has been created, the points reflected over the plane will be the ones that can be reached from the target point by moving on the paper continuously without passing through the plane.
Otherwise, the command will reflect every point that is on the same side of the plane as where its normal vector is pointing to.
Finally, it removes any unnecessary creases created in the process.
This command deletes all disposable parameters from memory.
paper [0 0 400 400] new
plane [200 0 0] [1 0 1]
reflect {We reflected the right half over a plane 45° apart from the paper space; this is equivalent to a 90° rotation}
planethrough [0 200 0] [200 250 0] [400 200] {We select the points we want to include in the new folding line}
reflect {And we have a reverse fold}
planethrough [0 250] [200 300] [400 250] {This time we give every point in paper space format}
target [50 350] {We select the lower half of the paper}
reflect {And the reverse fold becomes a crimp fold}
Modifies the origami model by creasing it along the specified plane, selecting certain parts of the paper, and, if the plane intersects these parts in a straight line, rotating them around the line by the specified angle. Nothing will be done if the intersection is not a non-degenerate line segment.
If a target has been created, the points to be rotated will be the ones that can be reached from the target point by moving on the paper continuously without passing through the plane.
Otherwise, the command will rotate every point that is on the same side of the plane as where its normal vector is pointing to.
Finally, it removes any unnecessary creases created in the process.
This command deletes all disposable parameters from memory.
Since there is no distinct "clockwise" or "counter-clockwise" direction in a 3-dimensional space, the rotation's direction is decided in an unpredictable manner. Typically, the desired direction is to be determined by trial and error. This behaviour may be changed in future releases.
paper [0 0 400 400] new
plane [200 0] [1 0 0]
angle 150
rotate {Rotates the right half of the paper by 150°}
plane [100 0] [1 0 0]
angle 30
rotate {Nothing will be done because the intersection points are not collinear}
{However, when selecting a target point, one can choose a specific flap to rotate:}
plane [100 0] [1 0 0]
angle 30
target [50 200]
rotate
Modifies the origami model by creasing it along the specified plane, then deleting certain polygons from the model.
If a target has been created, the polygons to be deleted will be the ones that can be reached from the target point by moving on the paper continuously without passing through the plane.
Otherwise, the command will delete every polygon that is on the same side of the plane as where its normal vector is pointing to.
Finally, it removes any unnecessary creases created in the process.
This command deletes all disposable parameters from memory.
The command does not remove any vertices from the model, only the polygons. This can cause the Editor interface snapping the liner to points seemingly not there.
See the kirigami snippet.
Cancels the last reflect, rotate or cut operation called in session. Can be applied repeatedly.
This command deletes all disposable parameters from memory.
Cancels the last undo operation called in session. Can be applied repeatedly.
This command deletes all disposable parameters from memory.
Executes the text file specified in the filename parameter in a new OrigamiScript session. This has no effect on the session that called it.
This command deletes all disposable parameters from memory.
Loads the ORI file specified in the filename parameter in a new OrigamiScript session. The new session overwrites the one that called it.
Executes the text file specified in the filename parameter in a new OrigamiScript session. The new session overwrites the one that called it.
Attempts to load the file specified in the filename parameter as the paper texture for any later export-ctm commands to use.
Cancels the effect of the previous load-texture command; that is, export-ctm commands after this command will not use a texture for the origami.
Exports the origami created in the current session as an ORI file, into the file specified in the filename parameter.
An ORI file is a highly but losslessly compressed file capable of storing reflect, rotate and cut commands with all their parameters. This makes it an effective way to store origami models created in OrigamiScript.
This command deletes all disposable parameters from memory.
Exports the origami created in the current session as an OpenCTM file, into the file specified in the filename parameter.
OpenCTM is an open 3D file format for triangle meshes. You can download the latest OpenCTM viewer and converter here.
Files generated with this command are uncompressed.
This command deletes all disposable parameters from memory.
Exports the origami created in the current session as a PDF 1.3 file, into the file specified in the filename parameter.
The exported document contains the auto-generated folding diagram of the model with up to 6 figures and the corresponding folding instructions per page. The title of the document will be the string assigned to the last title parameter, aligned to the center with whitespace.
Currently available locales are English and Hungarian.
Files generated with this command are uncompressed.
This command deletes all disposable parameters from memory.
Exports the origami created in the current session as an animated GIF file, into the file specified in the filename parameter.
The exported file is a looped animation of the folding process in 1 second long frames, as viewed from the specified camera direction.
Files generated with this command are uncompressed.
This command deletes all disposable parameters from memory.
Exports the origami created in the current session as an animated GIF file, into the file specified in the filename parameter.
The exported file is a looped animation of the origami revolving around a vertical axis, its initial orientation being the specified camera direction.
Files generated with this command are uncompressed.
This command deletes all disposable parameters from memory.
Exports the crease pattern of the origami created in the current session as a PNG file, into the file specified in the filename parameter. The JVM will use the system's default PNG-capable image editor, if any.
This command deletes all disposable parameters from memory.
Exports the origami created in the current session as an ORI file wrapped in a Java archive that, when opened, runs a minimalistic viewer to display it. The result is a self-displaying origami file.
This command deletes all disposable parameters from memory.
Grants the calling session root privileges after prompting the user for approval. This will prevent all the commands listed in this documentation from throwing H011.
If you are prompted to enter root while compiling or loading a file, please do not accept it before making sure it does not contain malicious code.
Thrown when the new command is called on the corner list of a non-convex polygon, i. e. some of the corners defined by the corner and the paper parameters are located in the interior of the others' convex hull.
paper [0 0 100 100] corner [50 50] new
Thrown when the export-ori, export-ctm or export-autopdf command fails to write to the file specified in the filename parameter.
Thrown when the open command recognizes the file specified in the filename parameter as an ORI file, but fails to process it.
Thrown when the open command fails to recognize the file specified in the filename parameter as an ORI file.
Thrown when a command fails to read or write the file specified in the filename parameter.
{Assuming that the x.ori file does NOT exist in the program's directory,}
filename x.ori open
{causes an H005.}
Thrown when a keyword is identified as an OrigamiScript keyword, but not available for the currently set version.
Thrown when a parameter is used with an incorrect number of vectors or vectors with an incorrect number of components.
{Incorrect number of vectors}
version 1 plane [1 2 3] [4 5 6] [7 8 9]
{Incorrect number of components}
version 1 paper [0 0 0 100 100]
Thrown when the planethrough parameter is used on three collinear points, and therefore a unique plane going through all of them cannot be constructed.
planethrough [1 2 3] [4 5 6] [7 8 9]
Thrown when the paper parameter is used with a single-component vector that can not be recognized as a paper type identifier in the currently set version.
paper funky {This will never be implemented.}
Thrown when a command is used without the necessary parameters being specified beforehand.
version 1 load-texture filename [a.png] {The 'filename' parameter is supposed to be written before the 'load-texture' command}
Thrown when a keyword is identified as an OrigamiScript keyword, but the user does not have permission to use it.
Calling the compile command on an OrigamiScript file that itself also uses the compile command will cause H011. This is for safety reasons.
Thrown when the angle-bisector parameter is used on a zero angle, and therefore a unique plane bisecting it cannot be constructed.
angle-bisector [0 0] [100 100] [0 0]
version 1
{Take an A4 sheet of paper:}
paper a4
new
{Fold it back at the top and the bottom so that it becomes a square:}
plane [62.15 0] [-1 0 0] angle 180 rotate
plane [362.15 0] [1 0 0] angle 180 rotate
{Fold it in half:}
plane [212.15 150] [0 1 0] angle 180 rotate
{Fold the upper corners down:}
plane [212.15 150] [1 1 0] angle 180 rotate
plane [212.15 150] [-1 1 0] angle -180 rotate
{Open it to make it 3D:}
plane [212.15 150] [1 0 0] angle 45 rotate
planethrough [62.15 0] [212.15 150] [362.15 0] target [212 75] reflect
{Arrange the flaps:}
planethrough [62.15 0] [212.15 150] [362.15 0] target [322 110] reflect
planethrough [62.15 0] [212.15 150] [362.15 0] target [10 290] reflect
planethrough [62.15 0] [212.15 150] [362.15 0] target [410 10] reflect
{Make the sail with a sink fold:}
plane [212.15 60] [-14.64466 -100 35.355] reflect
{Finished.}
{The Miura fold was used by JAXA to deploy solar panel arrays in space}
version 1
paper square new
{First an accordion fold:}
plane [0 50] [0 1 0] angle 40 target [200 390] rotate
plane [0 100] [0 1 0] angle -40 target [200 390] rotate
plane [0 150] [0 1 0] angle 40 target [200 390] rotate
plane [0 200] [0 1 0] angle -40 target [200 390] rotate
plane [0 250] [0 1 0] angle 40 target [200 390] rotate
plane [0 300] [0 1 0] angle -40 target [200 390] rotate
plane [0 350] [0 1 0] angle 40 target [200 390] rotate
{Then some reflection magic:}
planethrough [20 0] [60 50] [20 100] target [390 200] reflect
planethrough [100 0] [140 50] [100 100] target [390 200] reflect
planethrough [180 0] [220 50] [180 100] target [390 200] reflect
planethrough [260 0] [300 50] [260 100] target [390 200] reflect
planethrough [340 0] [380 50] [340 100] target [390 200] reflect
{A very basic paper flower}
version 1
paper square new
{Fold in half twice:}
plane [200 200] [1 0 0] reflect
plane [200 200] [0 1 0] reflect
{Cut some paper:}
angle-bisector [200 0] [100 0] [200 100] cut
angle-bisector [0 200] [0 100] [100 200] cut
plane [130 200] [1 1 0] cut
{Unfold:}
target [100 100] plane [200 200] [1 0 0] reflect
target [100 100] plane [200 200] [0 1 0] reflect
{At times, it is much harder to fold something in OrigamiScript than it is in real life.}
version 1
paper square
new
plane [200 0] [1 0 0] reflect
plane [200 200] [1 1 0] angle 60 rotate
plane [200 200] [0 1 0] angle 60 rotate
plane [200 200] [-1 1 0] angle 60 rotate
planethrough [200 0] [200 200] [200 400] target [100 50] reflect
planethrough [0 0] [200 200] [400 0] target [100 50] reflect
planethrough [0 400] [200 200] [400 400] target [100 350] reflect
{This was the minimal code required to fold this particular 'rocket'}
Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.3 or any later version published by the Free Software Foundation; with no Invariant Sections, no Front-Cover Texts and no Back-Cover Texts.