compas_timber.planning

Classes

Actor

Enum representing the types of actor which could execute an model instruction.

Functions

get_name classmethod

get_name(value)

Returns the string representation of given actor value.

For use in logging.

Parameters:

• value (int) –

  One of [Actor.HUMAN, Actor.ROBOT]

Returns:

• str –

  One of ["HUMAN", "ROBOT"]

BeamNester

BeamNester(model, stock_catalog, spacing=0.0, per_group=False)

A class for optimizing 1D nesting of beams into stock pieces.

This class implements algorithms to efficiently nest beams from a TimberModel into available stock pieces, minimizing waste and cost.

Parameters:

• model (:class:`~compas_timber.model.TimberModel`) –

  The timber model containing beams to nest

• stock_catalog (list[:class:`BeamStock`]) –

  Available BeamStock pieces for nesting.

• spacing (float, default: 0.0 ) –

  Spacing tolerance for cutting operations (kerf width, etc.)

• per_group (bool, default: False ) –

  Whether to nest beams per group or all together. Default is False (all together).

Attributes:

• model (:class:`~compas_timber.model.TimberModel`) –

  The timber model

• stock_catalog (list[:class:`BeamStock`]) –

  Available BeamStock pieces for nesting

• spacing (float) –

  Spacing tolerance for cutting operations (kerf width, etc.)

• per_group (bool) –

  Whether to nest beams per group or all together. Default is False (all together).

Attributes

stock_catalog property writable

stock_catalog

Get the stock catalog.

Functions

nest

nest(fast=True)

Perform 1D nesting of all beams in the model.

Parameters:

• fast (bool, default: True ) –

  Whether to use a fast nesting algorithm (First Fit Decreasing) or a more accurate one (Best Fit Decreasing). Default is True (fast).

Returns:

• class:`NestingResult` –

  Nesting result containing stocks with assigned beams and metadata

BeamStock

BeamStock(length, cross_section, spacing=0.0, element_data=None)

A class to represent a stock piece for nesting beams.

Similar to a Beam but represents raw material stock that can have beams assigned to it.

Parameters:

• length (float) –

  Length of the stock piece.

• cross_section (tuple of float) –

  Cross-section dimensions (width, height).

• spacing (float, default: 0.0 ) –

  Spacing tolerance for cutting operations (kerf width, etc.).

• element_data (dict[str, :class:`NestedElementData`], default: None ) –

  Dictionary mapping element GUID (str) to nested element data.

Attributes:

• length (float) –

  Length of the stock piece.

• cross_section (tuple of float) –

  Cross-section dimensions sorted in ascending order for consistent comparison.

• spacing ((float, optional)) –

  Spacing tolerance for cutting operations (kerf width, etc.).

• element_data (dict[str, :class:`NestedElementData`]) –

  Dictionary mapping element GUID (str) to nested element data.

Functions

add_element

add_element(beam)

Add a beam to this stock assignment.

Parameters:

• beam (:class:`~compas_timber.elements.Beam`) –

  The beam to add

Raises:

• ValueError –

  If beam doesn't fit in remaining space

can_fit_element

can_fit_element(beam)

Check if a beam can fit in the remaining space.

Parameters:

• beam (:class:`~compas_timber.elements.Beam`) –

  The beam to check

Returns:

• bool –

  True if beam fits in remaining length, False otherwise

is_compatible_with

is_compatible_with(beam)

Check if this stock can accommodate the beam type and dimensions.

For 1D nesting, we only optimize along the length dimension. The cross-sections must be identical.

Parameters:

• beam (:class:`~compas_timber.elements.Beam`) –

  The beam to check

Returns:

• bool –

  True if beam is compatible with this stock, False otherwise

BuildingPlan

BuildingPlan(steps=None)

Container for building steps, each steps is a collection of instructions which can be visualized

BuildingPlanParser

Provides class methods to parse and serialize building plans from and to json files.

This implementation does it the COMPAS way. Implemet your own parse() and serialize() methods if you want to use a different format.

Functions

parse classmethod

parse(filepath)

Parses building plan from json file.

Parameters:

• filepath (str) –

  Path to json file

Returns:

• class:`BuildingPlan` –

serialize classmethod

serialize(building_plan, filepath)

Writes building plan to json file.

Parameters:

• building_plan (:class:`BuildingPlan`) –

  Building plan to be serialized.

• filepath (str) –

  Path to json file.

Instruction

Instruction(id, location)

Base class for instructions

LinearDimension

LinearDimension(id, location, start, end, char_size, offset)

3d linear dimension

Model3d

Model3d(id, location, geometry, element_id, obj_filepath)

Instruction which incorporates a 3d model (beam, screw etc.)

NestedElementData

NestedElementData(frame, key=None, length=None)

Data container for elements nested within stock pieces.

Parameters:

• frame (:class:`~compas.geometry.Frame`) –

  The position frame of the element within the stock.

• key (str, default: None ) –

  A human-readable identifier for the element.

• length (float, default: None ) –

  The length of the element (for beams).

Attributes:

• frame (:class:`~compas.geometry.Frame`) –

  The position frame of the element within the stock.

• key (str or None) –

  A human-readable identifier for the element.

• length (float or None) –

  The length of the element (for beams), None if not applicable.

NestingResult

NestingResult(stocks, tolerance=None)

A wrapper class for nesting results that provides serialization capabilities.

Parameters:

• stocks (list[:class:`Stock`]) –

  List of stock pieces with assigned beams

• tolerance (:class:`~compas.tolerance.Tolerance`, default: None ) –

  The tolerance configuration used for this model. TOL if none provided.

Attributes:

• stocks (list[:class:`Stock`]) –

  List of stock pieces with assigned beams

• tolerance (:class:`~compas.tolerance.Tolerance`) –

  The tolerance configuration used for this model. TOL if none provided.

• total_material_volume (float) –

  Total material volume across all stocks in cubic millimeters

• total_stock_pieces (dict) –

  Detailed report of stock pieces needed with their dimensions

• summary (str) –

  Human-readable summary of the nesting result

Attributes

summary property

summary

Return a human-readable summary of the nesting result.

total_material_volume property

total_material_volume

Calculate total material volume across all stocks in cubic millimeters.

total_stock_pieces property

total_stock_pieces

Generate a detailed report of stock pieces needed with their dimensions.

PlateStock

PlateStock(dimensions, thickness, spacing=0.0, element_data=None)

A class to represent a stock piece for nesting plates.

Similar to a Plate but represents raw material stock that can have plates assigned to it.

Parameters:

• dimensions –

  Dimensions of the stock piece (length, width).

• thickness (float) –

  Thickness of the stock piece.

• spacing (float, default: 0.0 ) –

  Spacing tolerance for cutting operations (kerf width, etc.).

• element_data (dict[str, :class:`NestedElementData`], default: None ) –

  Dictionary mapping element GUID (str) to nested element data.

Attributes:

• dimensions (tuple of float) –

  Dimensions of the stock piece (length, width).

• thickness (float) –

  Thickness of the stock piece

• spacing ((float, optional)) –

  Spacing tolerance for cutting operations (kerf width, etc.).

• element_data (dict[str, :class:`NestedElementData`]) –

  Dictionary mapping element GUID (str) to nested element data.

SimpleSequenceGenerator

SimpleSequenceGenerator(model)

Generates a simple sequence of steps, one step per element. Order of steps is the same as order of elements in model.

Parameters:

• model (:class:'compas_model.Model') –

  Model to be sequenced.

Attributes:

• result (:class:`BuildingPlan`) –

  Resulting building plan.

Step

Step(
    element_ids,
    actor=None,
    location=None,
    geometry=None,
    instructions=None,
    is_built=False,
    is_planned=False,
    elements_held=None,
    priority=0,
)

Container for building instructions which assemble a single element

Attributes:

• actor (:class:`Actor`) –

  Actor which executes the step. one of [Actor.HUMAN, Actor.ROBOT]

• element_ids (list(int)) –

  List of cad element ids which are associated with the step.

• elements_held (list(int)) –

  List of cad element ids which are held by the actor (typically a robot) during this step.

• location (:class:`compas.geometry.Frame`) –

  Location of the step.

• instructions (list(:class:`Instruction`)) –

  List of instructions which support the step.

• is_built (bool) –

  Whether the step has been executed.

• is_planned (bool) –

  Whether the step has been planned. Allows for incremental planning.

• geometry (str) –

  Geometry type of the element to be assembled. One of ["obj", "cylinder", "box"]]. Used for visualization.

• priority (int) –

  Priority of the step. Steps within the same priority can be executed in parallel.

Stock

Stock(length, width, height, spacing=0.0, element_data=None)

A base class to represent a stock piece for nesting.

Parameters:

• length (float) –

  Length of the stock piece.

• width (float) –

  Width of the stock piece.

• height (float) –

  Height of the stock piece.

• spacing (float, default: 0.0 ) –

  Spacing tolerance for cutting operations (kerf width, etc.).

• element_data (dict[str, :class:`NestedElementData`], default: None ) –

  Dictionary mapping element GUID (str) to nested element data.

Attributes:

• length (float) –

  Length of the stock piece.

• width (float) –

  Width of the stock piece.

• height (float) –

  Height of the stock piece.

• spacing ((float, optional)) –

  Spacing tolerance for cutting operations (kerf width, etc.).

• element_data (dict[str, :class:`NestedElementData`]) –

  Dictionary mapping element GUID (str) to nested element data.

Functions

add_element

add_element(element)

Add an element to this stock assignment.

Parameters:

• element (:class:`~compas_timber.elements.Element`) –

  The element to add.

Raises:

• ValueError –

  If element doesn't fit in remaining space.

can_fit_element

can_fit_element(element)

Check if an element can fit in the remaining space.

Parameters:

• element (:class:`~compas_timber.elements.Element`) –

  The element to check

Returns:

• bool –

  True if element fits in remaining space, False otherwise

is_compatible_with

is_compatible_with(element)

Check if this stock can accommodate the element type and dimensions.

Parameters:

• element (:class:`~compas_timber.elements.Element`) –

  The element to check

Returns:

• bool –

  True if element is compatible with this stock, False otherwise

Text3d

Text3d(id, location, text, size)

Text overlay