File formats

Terrafold saves models in its own .tfo format and exchanges models with other programs through common 3D formats. This page lists what Terrafold reads and writes, and introduces the terrafold-cli command-line tool.

Terrafold models (.tfo)

A .tfo file holds everything in your model: geometry, groups and components, tags, materials with their textures, scenes, matched photos, garden elements, plants and the garden time, the environment, and a preview image. Textures are stored inside the file, so you can share a single file.

File ▸ Open… (Ctrl+O) opens a .tfo file. Files in other supported formats open as a new, untitled model.
File ▸ Save (Ctrl+S) and File ▸ Save As… save it.
When you save over a file, the previous version is kept as <name>.backup.tfo.

Models saved by earlier versions of Terrafold as .3dc files still open. Terrafold doesn't write .3dc files: save them as .tfo.

Templates

File ▸ Save As Template… saves the current model as a template. File ▸ New from Template and the Welcome window start a new model from it. To make a template the default for new models, choose it in Preferences ▸ Template.

Import a model

File ▸ Import… brings a model file into the open model as one component, named after the file. The component follows the cursor; click to place it, or type [x,y,z] to place it at an exact point. Its materials and textures come along. If a material name is already used, the imported one gets a new name.

3D formats

Format	Extensions	Import	Export	Notes
Terrafold model	`.tfo`	yes	yes	the native format
Earlier Terrafold model	`.3dc`	yes	no	read only
COLLADA	`.dae`	yes	yes	keeps component copies as instances
glTF binary	`.glb`	yes	yes	full physically based materials, instances
glTF	`.gltf`	yes	no	with its `.bin` buffers and textures next to it
Wavefront OBJ	`.obj`	yes	yes	with an `.mtl` material file
STL	`.stl`	yes	yes	binary or ASCII
3D Studio	`.3ds`	yes	yes	objects, materials, textures, smoothing
AutoCAD DXF	`.dxf`	yes	yes	lines, polylines, arcs and circles, 3D faces and meshes, blocks as components, layers as tags; binary DXF is not read
Google Earth	`.kmz`	yes	yes	with placement and geo-location
.skp	`.skp`, `.skb`	yes	no	preview, see below

File ▸ Export ▸ 3D Model… writes any format with "yes" in the Export column. Hidden geometry is left out of COLLADA, glTF, 3DS, DXF and KMZ exports.

Units

Formats that store their units (glTF, COLLADA, KMZ, and DXF files that declare units) arrive at their real size. For formats without units, Terrafold assumes:

Format	Assumed unit
STL	millimetres
OBJ	metres
3DS, DXF without units	inches

OBJ files are read as Y-up, the usual convention for that format.

.skp files

Terrafold imports .skp and .skb files saved by versions up to 2017 of the format. This import is a preview. It brings in geometry, components, tags, materials and textures, scenes, shadow settings, geo-location, axes, section planes and animation settings. Style settings are not imported yet, and newer files are not supported yet. Terrafold doesn't write .skp files.

Images and other exports

What	Command	Format
The current view	File ▸ Export ▸ 2D Graphic…	PNG
A section cut	File ▸ Export ▸ Section Slice…	SVG
The scene animation	File ▸ Export ▸ Animation…	a series of PNG images
A photoreal render	Save PNG… in the Render window	PNG
The plant schedule	File ▸ Export ▸ Plant Schedule…	CSV
The garden quantities	File ▸ Export ▸ Garden Quantities	CSV
Your keyboard shortcuts	Export… in Preferences ▸ Shortcuts	JSON

See Rendering, Planting and Hardscape for details.

Terrafold reads these images:

PNG and JPEG images as material textures and for Match Photo.
.hdr and .exr panoramas as the environment of the Realistic style and renders.

The command-line tool

The desktop packages include terrafold-cli, which works with models without opening a window. It is handy for converting many files, making images on a server, or automating repetitive work.

Command	What it does
`terrafold-cli info FILE`	prints a summary: format, units, counts, size, tags, materials and warnings (`--json` for JSON)
`terrafold-cli convert IN OUT`	converts between formats, chosen by the file extensions; `--unit` sets the unit of unit-less formats, `--ascii` writes ASCII STL
`terrafold-cli export FILE OUT.png`	renders a quick image of a model, with `--view`, `--style`, `--width`, `--height` and `--zoom-extents`
`terrafold-cli render FILE OUT.png`	makes a photoreal render; see Rendering
`terrafold-cli animation FILE OUT.png`	exports the scene animation as PNG frames
`terrafold-cli run FILE --script SCRIPT`	runs a script of commands on a model, then saves it (`--out`) or renders it (`--export`)
`terrafold-cli extension`	runs an extension on a model; see Extensions
`terrafold-cli sample --out FILE`	writes the sample house
`terrafold-cli commands`	lists every command with its parameters

Add --help after any command for its options, for example terrafold-cli render --help. Use --sample instead of a file name to work on the sample house.

Scripts

A script is a text file with one command per line. Lines starting with # are comments. For example, this script sets the units, draws a rectangle and plants a tree:

command units {"length": "m"}
command rectangle {"corner": [0, 0, 0], "size": ["14m", "10m"]}
command place_plant {"species": "betula-pendula", "position": ["2.5m", "7m", 0]}
command garden_time {"years": 5, "month": 6}
view iso
zoom_extents

Run it and save the result as a model and an image:

terrafold-cli run --script garden.txt --out garden.tfo --export garden.png

Scripts can also start tools and simulate clicks and typing (tool, pointer, key and vcb lines). The script stops at the first error unless you add --keep-going. terrafold-cli run --help describes every kind of line.

The command-line tool returns exit code 0 on success, 1 on an error and 2 when the command line itself is wrong.