LayOut Ruby API

The LayOut Ruby API provides an interface for reading and writing data to and from LayOut Layout::Documents (.layout files) via an intuitive and easy to learn programming language, Ruby. It can create new Layout::Documents as well as read or modify existing Layout::Documents.

LayOut Ruby API Documentation

The documentation contains reference material for all functions, data structures, constants, and enumerations in the LayOut Ruby API.

The online Ruby API documentation can be found here: LayOut Ruby API Online Documentation

Using the LayOut Ruby API in SketchUp

The LayOut Ruby API is included in the SketchUp application, meaning developers may utilize the LayOut Ruby API from within their SketchUp application via the console, or in their SketchUp Ruby extension without being required to include it. For an example of how to use the LayOut Ruby API from within a SketchUp extension, see the RubyExampleCreateLayOut sample.

Things To Know About The LayOut Ruby API

LayOut's Coordinate System

LayOut uses a 2D coordinate system for Layout::Entitys, whose origin is at the top-left corner of the page. The positive X axis extends to the right, and the positive Y axis extends downward. The units for all Geom::Point2d objects are inches. All 2D lengths and radii are also specified in inches, unless the function documentation specifies otherwise.

Geom::Point3d objects are used for certain functions that interact with a Layout::SketchUpModel. Geom::Point3d objects specify model-space coordinates within a Layout::SketchUpModel.

Shared and Non-Shared Groups

A Layout::Group may not contain a mix of Layout::Entitys on both shared and non-shared Layout::Layers. This is enforced when creating Layout::Groups (see Layout::Group#initialize) as well as when moving Layout::Entitys into a Layout::Group (see Layout::Entity#move_to_group). Also, functions that cause an Layout::Entity's sharedness to change may have the side effect of splitting Layout::Groups (see Layout::Entity#move_to_layer). In general, these operations follow the same behavior as the LayOut application itself.

To traverse the hierarchical Layout::Group structure of a Layout::Document, it is important to understand that due to the rule about shared and non-shared Layout::Groups, there are multiple Layout::Group structures in a Layout::Document. Each Layout::Page has its own Layout::Group structure that contains all of the Layout::Entitys on non-shared Layout::Layers for that Layout::Page (see Layout::Page#nonshared_entities). Likewise, the Layout::Document has a Layout::Group structure that contains all of the Layout::Entitys on shared Layout::Layers for the entire Layout::Document (see Layout::Document#shared_entities). These functions provide access to an object, Layout::Entities, which is a list of Layout::Entity objects at the top of the hierarchy. Furthermore, the Layout::Group#entities function provides an inlet to recursively traverse the Layout::Group structure.

Iterating Over Entities On A Page

In cases where you need to iterate over all the Layout::Entitys that are visible on a Layout::Page, including the Layout::Entitys on both shared and non-shared layers, you can use the Layout::Page#entities method. This method returns a list that, when iterated over, will visit Layout::Entitys in exactly the same order they are drawn by LayOut.

Locked Entities

Any Layout::Entity in LayOut can be individually locked or unlocked via the Layout::Entity#locked= method. Locked Layout::Entitys cannot be moved, rotated, scaled, or modified in any way, besides being unlocked.

Locked and Hidden Layers

In LayOut, the locked state of a Layout::Layer is a Layout::Document-wide setting, whereas the visible state of a Layout::Layer is a per-Layout::Page setting. LayOut has a rule that there must always be at least one unlocked, visible Layout::Layer on every Layout::Page. This rule is enforced by the LayOut Ruby API by methods such as Layout::Layer#locked=, Layout::Page#set_layer_visibility, and Layout::Layers#remove.

There Must Be At Least One Page And One Layer In A Document

There must be at least one Layout::Layer in a Layout::Document, and there must be at least one Layout::Page. Layout::Layers#remove and Layout::Pages#remove enforce this. Also, new Layout::Documents created by Layout::Document#initialize will create a blank Layout::Document that starts out with one Layout::Layer and one Layout::Page.

Explicit Transforms and Untransformed Bounds

Only some Layout::Entitys in LayOut have explicit Geom::Transformation2d: Layout::Ellipse, Layout::FormattedText, Layout::Image, Layout::Rectangle and Layout::SketchUpModel will always have an explicit Geom::Transformation2d. These are the only Layout::Entitys that will return a value for Layout::Entity#untransformed_bounds. Layout::Entity#transform! will work on any Layout::Entity type, regardless of whether the Layout::Entity has an explicit Geom::Transformation2d or not. It is important to note that LayOut will attempt to simplify the Geom::Transformation2d, which may affect both the untransformed bounds as well as the explicit Geom::Transformation2d of the Layout::Entity. Due to this, it is likely that the transform returned by Layout::Entity#transformation will be different than the one that was applied. Also, the bounds returned by Layout::Entity#untransformed_bounds will likely be different from the Layout::Entity's initial untransformed bounds.

Paths Must Have At Least Two Points

Layout::Path#initialize enforces the rule that every Layout::Path must contain at least two points. This is because a 0 or 1-point Layout::Path is not visible and cannot be selected (or deleted) in the LayOut application.

Text Cannot Be Empty

The functions for Layout::FormattedText enforce the rule that the content of the text cannot be empty. This is because an empty text box is not visible and cannot be selected (or deleted) in the LayOut application.