Struct Document

Source

pub struct Document { /* private fields */ }

Expand description

A model with product structure, appearance and names over it.

The model stays reachable (construction, booleans and measurement all operate on it directly), and the document adds what a model alone does not say: which shapes are products, how they assemble, what they are called and what colour they are.

Implementations§

Source §

impl Document

Source

pub fn new() -> Self

An empty document over an empty model.

Source

pub fn over(model: Model) -> Self

A document over an existing model.

Source

pub const fn model(&self) -> &Model

The model under the document.

Source

pub const fn model_mut(&mut self) -> &mut Model

The model, for construction and modification.

Source

pub fn add_part(&mut self, name: impl Into<String>, shape: Shape) -> ProductId

Add a part: a named product carrying a shape.

Source

pub fn add_assembly(&mut self, name: impl Into<String>) -> ProductId

Add an empty assembly.

Source

pub fn add_instance( &mut self, assembly: ProductId, product: ProductId, at: Transform, name: Option<String>, ) -> OgeomResult<()>

Place product inside assembly at at.

The transform becomes a datum in the model’s own store, so the instance’s placement is structural (comparable by identity, shared by every traversal) rather than a matrix to be compared with an epsilon.

§Errors

OgeomError::Construction if assembly is not an assembly, or placing product there would make a product contain itself; OgeomError::Dangling if either id is not in this document.

Source

pub fn add_instance_at( &mut self, assembly: ProductId, product: ProductId, location: Location, name: Option<String>, ) -> OgeomResult<()>

Place product inside assembly at an already-resolved location.

The persistence path: a file carries the instance’s location chain verbatim, and re-minting a datum for it would renumber what the file preserved. Checks are as Document::add_instance.

§Errors

As Document::add_instance.

Source

pub fn get(&self, id: ProductId) -> Option<&Product>

The product behind an id.

Source

pub fn products(&self) -> impl Iterator<Item = (ProductId, &Product)>

Every product, in the order added.

Source

pub fn roots(&self) -> Vec<ProductId>

The products no instance places: the top of the tree.

Source

pub fn occurrences_of(&self, product: ProductId) -> OgeomResult<Vec<Occurrence>>

Every placed part under product, shapes moved into world space.

The flattening every consumer of an assembly wants: two instances of one part come back as two occurrences whose shapes share a topology node and differ only in their location chains.

§Errors

OgeomError::Dangling if product is not in this document.

Source

pub fn set_product_colour( &mut self, product: ProductId, colour: Colour, ) -> OgeomResult<()>

Colour a product: the fallback for everything in it.

§Errors

OgeomError::Dangling if product is not in this document.

Source

pub fn add_texture(&mut self, texture: Texture) -> TextureId

Add a texture the document can lay on shapes.

Source

pub fn set_texture(&mut self, shape: &Shape, texture: TextureId)

Lay a texture on a shape, replacing whatever was on it.

Source

pub fn texture_of(&self, shape: &Shape) -> Option<&Texture>

The texture on a shape, if it has one.

Source

pub fn textures(&self) -> &[Texture]

Every texture the document holds, in the order they were added.

Source

pub fn checkpoint(&mut self)

Mark the document’s current state as one an undo can return to.

Call it before the change a caller might want back. Anything undone and not redone is dropped at the next checkpoint, which is the usual rule: a new branch replaces the abandoned one.

Source

pub fn undo(&mut self) -> bool

Step back to the last checkpoint. false when there is none.

Source

pub fn redo(&mut self) -> bool

Step forward again. false when nothing was undone.

Source

pub fn undo_depth(&self) -> (usize, usize)

How many steps back are available, and how many forward.

Source

pub fn product_index(&self, id: ProductId) -> usize

The position of a product in write order: how the native format refers to one across a save.

Source

pub fn add_view(&mut self, view: View) -> usize

Add a saved view; its index is how STEP and the native format refer to it.

Source

pub fn views(&self) -> &[View]

The saved views, in order.

Source

pub fn add_note(&mut self, note: Note) -> usize

Add a note.

Source

pub fn notes(&self) -> &[Note]

The notes, in order.

Source

pub fn set_colour(&mut self, shape: &Shape, colour: Colour)

Colour a shape: a whole part’s shape or one sub-shape of it.

Keyed by the topology node, so every occurrence of an instanced shape shows the colour: the colour belongs to the entity, not to one placement of it.

Source

pub fn colour_of(&self, shape: &Shape) -> Option<Colour>

The colour set directly on a shape’s node, if any.

Source

pub fn resolved_colour(&self, part: ProductId, sub: &Shape) -> Option<Colour>

The colour a sub-shape of a part actually shows.

Most specific wins: the sub-shape’s own colour, else the colour of the part’s whole shape, else the product’s, else nothing.

Source

pub fn set_name(&mut self, shape: &Shape, name: impl Into<String>)

Name a shape’s node: a face someone will want to find again.

Source

pub fn name_of(&self, shape: &Shape) -> Option<&str>

The name set on a shape’s node, if any.

Source

pub fn colours(&self) -> impl Iterator<Item = (TShapeId, Colour)> + '_

Every node-attached colour, for a writer to carry out.

Source

pub fn names(&self) -> impl Iterator<Item = (TShapeId, &str)>

Every node-attached name, for a writer to carry out.

Source

pub fn replace_part_shape( &mut self, product: ProductId, shape: Shape, ) -> OgeomResult<()>

Replace a part’s shape: the modification step of an edit.

The old shape’s node-attached colours, names and PMI stay where they are: entities that survived the modification keep their annotations, entities that did not simply no longer resolve.