pcb-rnd knowledge pool

Extended objects (design plan)

extobj by Tibor 'Igor2' Palinkas on 2019-05-19	Tags: insight, extended, object, objects, extobj, via, stitching
node source

Abstract: n/a

What is an extended object?

An extended object (extobj) is:

stored as a subcircuit...
...which has floater objects (a line, arc, text or polygon) called the "edit-objects", usually on a doc layer, for graphical editing of geometry
(locked) subcircuit updated when the edit-object is changed or created
layers of the subcircuit can be bound to any board layers freely by the user, which provides a flexible way of mapping generated objects to board layers
updating/generation managed by a named extobj implementation provided by a plugin

The idea is best demonstrated with an example: via stitching and via shielding. In the stitching setup an area on the board needs to be filled with evenly spaced vias. This is very often used for getting more solid ground planes. In case of shielding, a smaller area of the board, typically an RF trace is guarded by a "fence" of evenly spaced vias; these vias are placed in a row, following the shape of the object to be fenced/guarded.

Both of these can be achieved by manually placing vias, but then if anything changes (the ground polygons or the guarded object), it takes a lot of manual editing to move or redraw all the vias.

In the extended object model, the via stitch is edited as a polygon, the via fence/guard is edited as a line (or arc). When the user clicks to grab it for move or modify, the object behaves as if it was a polygon or line (but in case it is a polygon, no clearance apply to it). However, when editing is over, the content of the subcircuit is removed (except for the edit-objects) and generated again, using the geometry of the edit object and data from attributes. In our examples, at the end of the edit, the polygon or the line/arc is filled with evenly spaced vias of the specified padstack prototype.

On screen and in the file, the subcircuit is stored with an extra attribute called "extobj". The value of this attribute is the name of the extobj implementation that shall manage the object. Other parameters of the extended objects are also stored as subcircuit attributes, prefixed with "extobj::".

Details and corner cases

Edit-objects

Floater objects of the subcircuit have an extobj::role attribute. The value of this attribute tells the code how the given floater contributes to the extended object. The default value is "edit", which makes the floater an edit-object. Some extended object implementations can handle multiple edit-objects, in which case multiple floaters may have the role set to edit.

An extended object implementation may use different floater objects for different purposes. The differentiation is done by using different values ion the extobj::role attribute.

The documentation of each extended object implementation should specify the type and number of edit-objects and other floater roles used.

Specific example

For example in case of via fencing, the extended object is called a "line-of-vias". The edit object is a line, which should be placed on a doc layer (purpose=extobj) so the line itself doesn't interfere with anything else on the board. The subcircuit generated will have vias evenly spaced, starting from the beginning of the line.

The user draws and edits the line only, the subcircuit is automatically re-generated upon any change to the line, when the plugin is available.

The subcircuit can host multiple edit-object lines, all of them with extobj::role=edit. This comes handy when the existing edit-object is edited using the route code, which may split the line into a 90 and a 45 degree segment, effectively creating a new line segment. The new line will inherit all attributes, including extobj::role, so the code will put vias on it automatically.

The subcircuit has an attribute "extobj=line-of-vias". This identifies the extended object implementation (code) that pcb-rnd will need to use for this object. The pitch of placing the via is specified as "extobj::pitch" on the subcircuit.

How to edit floaters and the extended object?

Geometric, buffer and remove operations are done on the floaters. Only floaters can be selected, the extended object subcircuit can not be (as it is locked).

Floater attributes can be edited normally, right clicking the floater.

The extended object (subcircuit) can be addressed by the 1*1 mm 'E' mark drawn as annotation. When right clicking on that, the extended object popup will be invoked. This is where the attributes of the extended object can be edited

Where to store extobj data?

Extobj data is some implementation-specific detail that needs to be stored with the object. In the via stitching/fencing example, this includes spacing and padstack prototype.

Since the extobj needs to be recalculated only upon edit, which won't happen too often, the extobj implementation doesn't need to be blazing fast in loading or saving its extobj specific data. Thus all data is stored in attributes prefixed with "extobj::", in plain text format, in the subcircuit. The extobj implementation is responsible for data marshaling and optional caching.

What if the plugin is missing?

Corner case: an extobj (e.g. via stitch) is created on system A where the required plugin exists. The board file is then moved to system B where the plugin is not available.

Display on B: the via stitch is displayed as if it was a (locked) subcircuit - because it is really just a subcircuit (originally generated by the extobj implementation found in that plugin). So the extended object does render perfectly without the plugin.

Editing in B: the user can move, remove or copy the subc easily (once the lock is removed).

Content edit is also possible, the same way as for any subcircuit. However, this edit will be literally manual work, as there's no extobj implementation to re-generate the vias. The edit-object can be edited too, and should be, to keep it up-to-date with the subc.

Displaying again on A: moving back the file to system A; loading the file won't change the subc content, only editing triggers re-generation. So until the first edit, all manual edits happened on system B are preserved. So the extended object does render the same way as it did on B.

Editing again on A: since the edit on B wouldn't remove any of the attributes (unless the user explicitly went on to remove them by hand), and we assume the user on system B also updated the edit-object, the extended object can be edited as an extobj on A. After any edit, it is re-generated; if there was any manual edit to the subc on B, it is then overridden by the new version created by the extobj implementation on A. However, this is no different from any other editing plain objects in team work: any change to the stored subc happens only when B started to edit.

Do all HIDs and export code need to understand this?

No. The only code that needs to understand it is for editing. When the plugin is available, upon hitting an extobj edit-object, the code needs to ask the extobj implementation to act and update the subc.

For on-screen rendering the subc draw code needs to call an extra, extobj-implementation-provided function for the annotation instead of drawing the dashed subc frame and printing the ID (refdes). This way the extended object's subcircuit doesn't really look like a subcircuit (dashed bounding box) but can have its own annotation graphics.

However, for any other part of the code it is nothing special, just a plain old subc. For example these parts are unaffected:

load/save (in any file format)
export (to any file format)
on-screen rendering of the result ("copper"; except for the optional annotation)

Does an extended object survive any file format conversion?

It may, but not always. Conversion does fully survive in file formats where attributes are supported and where the layer that hosts the edit-object can be saved. pcb-rnd native formats obviously support attributes, so do a few alien formats.

Where attributes are not supported or the edit-object's layer can not be saved, the subcircuit is saved as a normal subcircuit, so the only info lost is the extobj-related info, but the board will still look the same. The only drawback is that loading back such a file won't let pcb-rnd edit the subc as an extobj anymore.

The most common reasons the extended object will not survive a conversion:

the format doesn't support every object type used in the subc in its footprint format
the format doesn't support the doc layer used for the edit-object in its footprint format
the format doesn't have footprint attributes

How many extobj plugins can we have?

Virtually unlimited. The only requirement is each extobj implementation needs to have an own, unique name. For core plugins this is obviously centrally coordinated. For 3rd party plugins and user scripts it can not be guaranteed, but with some care it can be quite safe.

Corner: buffer and remove

Since the host extobj subcircuit is locked, the user can not delete or move or cut/copy it to buffer: all such operations are done on a floater instead.

In buffer copy/cut, the extobj central code will simply translate the call from the floater to the parent subc in case of extended objects.

In case of delete, the extended object implementation gets a callback to decide what to do. For example if there can be multiple floaters within an extobj (e.g. line-of-vias), removing one will not cause any harm, but removing the last should remove the extobj instead. In other cases (e.g. dimension), removing any floater should remove the extobj.

Important limitations

An extobj is updated only when its edit-object changes. It will not update if other sorrunding objects change, not even if updating/generating the extobj considers those objects. For example a line-of-vias will skip generating vias that are too close to existing vias. If a via was skipped because of an offending existing via, removing that offending via will not regenerate the line-of-vias. But a click on the line will.

Extobjs can not be used in subcircuits before we have subc-in-subc support. That is, the subcircuit of the extended object must be placed directly on the board and can not be part of a footprint.