Notation used in Ruby API documentation
Module: lay
Description: A utility class for generating text bounding boxes including the glyph polygons
The geometry database regards text objects as point-like, hence the natural bounding box of a text object is a single point. To obtain the visual bounding box, you can use the TextInfo object. It is created from a layout view and allows computing bounding boxes from Text, DText or Shape objects which include the visual representation of the text.
That bounding box is given in the equivalent space of the original text object - i.e. when it is placed into the same cell and on the same layer than the original text.
This computation is not trivial, because there are fonts that do not scale with zoom level. Hence, the equivalent bounding bounding box depends on the zoom factor and other transformations that control the rendering of the text. Also, a number of settings from the layout view - specifically default font or default text height influence the appearance of the characters and need to be considered. The TextInfo object takes care of these things.
It does not take care however of transformations applied inside the hierarchy. Specifically, when a text object is not in the current top cell, different instantiation paths may exist that render different bounding boxes. Hence there not a single equivalent bounding box for a text object not inside the top cell. It is recommended to first transform the texts into the top cell before computing the bounding boxes.
Here is some sample code that places boxes over each selected text object. These boxes are identical to the selection markers of the texts, but this identity quickly vanishes if you zoom in or out:
begin
view = RBA::LayoutView.current
# Provide undo support, so it is more convenient to try out
view.transaction("Generate true label bounding boxes")
textinfo = RBA::TextInfo::new(view)
view.each_object_selected do |sel|
# Ignore selected objects which are not texts
sel.shape.is_text? || next
# Transform the text to top level
tl_text = sel.trans * sel.shape.text
# Compute the bounding box
bbox = textinfo.bbox(tl_text, sel.cv_index, sel.layer)
# Place boxes over the original texts
# Note that 'ctx_cell' is the true origin of the selection path, hence the one that 'sel.trans' applies to
view.cellview(sel.cv_index).ctx_cell.shapes(sel.layer).insert(bbox)
end
ensure
view.commit
end
This class has been introduced in version 0.30.5.
| new TextInfo ptr | new | (LayoutView ptr view) | Creates a TextInfo object for a given layout view |
| [const] | TextInfo ptr | _const_cast | Returns a non-const reference to self. | |
| void | _create | Ensures the C++ object is created | ||
| void | _destroy | Explicitly destroys the object | ||
| [const] | bool | _destroyed? | Returns a value indicating whether the object was already destroyed | |
| [const] | bool | _is_const_object? | Returns a value indicating whether the reference is a const reference | |
| void | _manage | Marks the object as managed by the script side. | ||
| void | _unmanage | Marks the object as no longer owned by the script side. | ||
| void | assign | (const TextInfo other) | Assigns another object to self | |
| Box | bbox | (const Shape shape) | Obtains the bounding box for the given text-type shape | |
| Box | bbox | (const Text text, unsigned int cv_index, int layer_index = -1) | Obtains the bounding box for the given text object | |
| DBox | bbox | (const DText dtext, int cv_index = -1, int layer_index = -1) | Obtains the bounding box for the given micrometer-unit text object | |
| [const] | double | border | Gets the border in pixels | |
| void | border= | (double pixels) | Sets the border in pixels | |
| [const] | new TextInfo ptr | dup | Creates a copy of self |
| void | create | Use of this method is deprecated. Use _create instead | ||
| void | destroy | Use of this method is deprecated. Use _destroy instead | ||
| [const] | bool | destroyed? | Use of this method is deprecated. Use _destroyed? instead | |
| [const] | bool | is_const_object? | Use of this method is deprecated. Use _is_const_object? instead |
_const_cast | Signature: [const] TextInfo ptr _const_cast Description: Returns a non-const reference to self. Basically, this method allows turning a const object reference to a non-const one. This method is provided as last resort to remove the constness from an object. Usually there is a good reason for a const object reference, so using this method may have undesired side effects. This method has been introduced in version 0.29.6. |
_create | Signature: void _create Description: Ensures the C++ object is created Use this method to ensure the C++ object is created, for example to ensure that resources are allocated. Usually C++ objects are created on demand and not necessarily when the script object is created. |
_destroy | Signature: void _destroy Description: Explicitly destroys the object Explicitly destroys the object on C++ side if it was owned by the script interpreter. Subsequent access to this object will throw an exception. If the object is not owned by the script, this method will do nothing. |
_destroyed? | Signature: [const] bool _destroyed? Description: Returns a value indicating whether the object was already destroyed This method returns true, if the object was destroyed, either explicitly or by the C++ side. The latter may happen, if the object is owned by a C++ object which got destroyed itself. |
_is_const_object? | Signature: [const] bool _is_const_object? Description: Returns a value indicating whether the reference is a const reference This method returns true, if self is a const reference. In that case, only const methods may be called on self. |
_manage | Signature: void _manage Description: Marks the object as managed by the script side. After calling this method on an object, the script side will be responsible for the management of the object. This method may be called if an object is returned from a C++ function and the object is known not to be owned by any C++ instance. If necessary, the script side may delete the object if the script's reference is no longer required. Usually it's not required to call this method. It has been introduced in version 0.24. |
_unmanage | Signature: void _unmanage Description: Marks the object as no longer owned by the script side. Calling this method will make this object no longer owned by the script's memory management. Instead, the object must be managed in some other way. Usually this method may be called if it is known that some C++ object holds and manages this object. Technically speaking, this method will turn the script's reference into a weak reference. After the script engine decides to delete the reference, the object itself will still exist. If the object is not managed otherwise, memory leaks will occur. Usually it's not required to call this method. It has been introduced in version 0.24. |
assign | Signature: void assign (const TextInfo other) Description: Assigns another object to self |
bbox | (1) Signature: Box bbox (const Shape shape) Description: Obtains the bounding box for the given text-type shape If the shape is not a text object or it is not part of a layout shown in the layout view, this method will return an empty box. Otherwise, it will return a Box object, representing the bounding box of the text object, including the label's character representation. The bounding box is given as an equivalent integer-unit Box object, when placed in the same cell and on the same layer as the original text object. |
(2) Signature: Box bbox (const Text text, unsigned int cv_index, int layer_index = -1) Description: Obtains the bounding box for the given text object This method returns a Box object, representing the bounding box of the integer-unit Text object. The cellview index needs to be specified, while the layer index is optional. The layer index is the layer where the text object lives in the layout, given by the cellview index. Without a layer, the bounding box computation will not take into account potential additional transformations implied by transformations present the layer view specification. The bounding box is given as an equivalent integer-unit Box object, when placed in the same cell and on the same layer as the original text object. | |
(3) Signature: DBox bbox (const DText dtext, int cv_index = -1, int layer_index = -1) Description: Obtains the bounding box for the given micrometer-unit text object This method returns a DBox object, representing the bounding box of the micrometer-unit DText object. The cellview and layer index is optional. Without a layer and cellview index, the bounding box computation will not take into account potential additional transformations implied by transformations present the layer view specification. The bounding box is given as an equivalent micrometer-unit DBox object, when placed in the same cell and on the same layer as the original text object. | |
border | Signature: [const] double border Description: Gets the border in pixels See border= for details about this attribute. Python specific notes: |
border= | Signature: void border= (double pixels) Description: Sets the border in pixels This attribute adds a border between the bounding box edges and the character polygons for better readability of the text when a box is drawn around them. The value is given in screen pixels. The default value is the one used for the markers in the application. Python specific notes: |
create | Signature: void create Description: Ensures the C++ object is created Use of this method is deprecated. Use _create instead Use this method to ensure the C++ object is created, for example to ensure that resources are allocated. Usually C++ objects are created on demand and not necessarily when the script object is created. |
destroy | Signature: void destroy Description: Explicitly destroys the object Use of this method is deprecated. Use _destroy instead Explicitly destroys the object on C++ side if it was owned by the script interpreter. Subsequent access to this object will throw an exception. If the object is not owned by the script, this method will do nothing. |
destroyed? | Signature: [const] bool destroyed? Description: Returns a value indicating whether the object was already destroyed Use of this method is deprecated. Use _destroyed? instead This method returns true, if the object was destroyed, either explicitly or by the C++ side. The latter may happen, if the object is owned by a C++ object which got destroyed itself. |
dup | Signature: [const] new TextInfo ptr dup Description: Creates a copy of self Python specific notes: |
is_const_object? | Signature: [const] bool is_const_object? Description: Returns a value indicating whether the reference is a const reference Use of this method is deprecated. Use _is_const_object? instead This method returns true, if self is a const reference. In that case, only const methods may be called on self. |
new | Signature: [static] new TextInfo ptr new (LayoutView ptr view) Description: Creates a TextInfo object for a given layout view Python specific notes: |