Skip to content

nicklockwood/ShapeScript

Repository files navigation

Build Codecov Platforms Swift 5.1 License Mastodon

Screenshot

Introduction

ShapeScript is a hybrid scripting/markup language for creating and manipulating 3D geometry using techniques such as extruding or "lathing" 2D paths to create solid 3D shapes, and CSG (Constructive Solid Geometry) to combine or subtract those shapes from one another.

ShapeScript is also the scripting language used for the ShapeScript Mac and iOS apps.

ShapeScript is implemented on top of Euclid, a cross-platform 3D modeling library written in Swift. Anything you can construct using ShapeScript can be replicated programmatically in Swift using Euclid.

If you would like to support the development of Euclid and the ShapeScript language, please consider buying a copy of ShapeScript for Mac or iOS (the apps themselves are free, but there is an in-app purchase to unlock some features).

Mac App Store App Store

Installation

ShapeScript is packaged as a Swift framework, which itself depends on the Euclid framework, a copy of which is included in this repository.

To install the ShapeScript framework using CocoaPods, add the following to your Podfile:

pod 'ShapeScript', '~> 1.8'

To install using Carthage, add this to your Cartfile:

github "nicklockwood/ShapeScript" ~> 1.8

To install using Swift Package Manager, add this to the dependencies: section in your Package.swift file:

.package(url: "https://github.com/nicklockwood/ShapeScript.git", .upToNextMinor(from: "1.8.0")),

The repository also includes ShapeScript Viewer apps for iOS and macOS, a cut-down version of the full ShapeScript apps available on the Mac and iOS app stores. It is not currently possible to install or run these apps using CocoaPods, Carthage or Swift Package Manager but you can run them by opening the included Xcode project and selecting the Viewer (Mac) or Viewer (iOS) schemes. For Linux, see usage instructions below.

Note: ShapeScript Viewer requires Xcode 11+ to build, and runs on macOS 10.13+ or iOS 14+.

Usage (Mac)

The best way to try out ShapeScript is to run the ShapeScript Viewer app (see above).

Once you have opened the app, you can create a new ShapeScript document from the File menu, or open one of the example projects from the Help menu.

ShapeScript does not include a built-in editor. Instead, after opening a shape file in the ShapeScript Viewer, you can select Open in Editor (Cmd-E) from the Edit menu to open the source file in a text editor of your choice.

The ShapeScript Viewer will track changes to the source file and update in real-time as you edit it.

For more information, check out the help section.

Usage (Linux)

ShapeScript provides a command-line interface for Linux machines. You can download the latest CLI build from the releases page.

You can also install or run the ShapeScript CLI using Mint. If Mint is installed, you can run ShapeScript using:

$ mint run nicklockwood/ShapeScript@main

Alternatively, to build the tool yourself from source, you will need to install the latest Swift toolchain, then run the following commands:

$ git clone https://github.com/nicklockwood/ShapeScript
$ cd ShapeScript
$ swift build -c release

Like the GUI app, the ShapeScript CLI does not include an editor. Use a text editor of your choice to create your .shape file, then pass it to the CLI as follows:

shapescript myfile.shape

This will run the file and report any errors. On success, it will print some info about the model. To export the model, add a second parameter with the path you'd like to export an STL (Stereolithography) file to:

shapescript myfile.shape myfile.stl

Contributing

Feel free to open an issue in Github if you have questions about how to use the library, or think you may have found a bug.

If you wish to contribute improvements to the documentation or the code itself, that's great! But please read the CONTRIBUTING.md file before submitting a pull request.

Credits

The ShapeScript framework and apps are primarily the work of Nick Lockwood.