(c) TIG 2010/2011/2012
Permission to use, copy, modify, and distribute this software for
any purpose and without fee is hereby granted, provided the above
copyright notice appear in all copies.
THIS SOFTWARE IS PROVIDED "AS IS" AND WITHOUT ANY EXPRESS OR
IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED
WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.
Script:
#HolePunchTool.rb
place it in the ../Plugins/ folder...
From v1.6 it also requires 'deBabelizer.rb' in the ../Plugins/ folder and
any required locale lingvo files in the ../Plugins/TIGtools sub-folder...
e.g. #HolePunchToolEN-US.lingvo, #HolePunchToolFR.lingvo etc...
Overview:
This script adds a new tool for glued/cutting component-instances.
It allows them to punch linked 3D holes through the faces of double-skinned walls/roofs etc.
It is accessed through the right-click context-menu 'Hole Punching...' sub-menu, which offers various items depending on the current Selection.
Usage:
1. TO PUNCH A HOLE:
Select a component-instance** that has already been placed on the face of a wall or roof etc - e.g. a newly inserted/imported or created window component.
The right-click context-menu 'Hole Punching...' sub-menu should then include 'Punch' as an option - pick it.
Only selected component-instances of a definition with a gluing/cutting capability will be processed.
In addition to the externally 'cut' 2D hole, the instance will now punch a hole through to any inner-face of that 'wall' - using the inner-face's material/layer etc for the reveals, or if there is no inner-face it will make a maximum depth reveal using the outer-faces' material/layer etc for the reveals
[Note that there is a 'Set Depth' option - see below].
The component-instance and the punched-hole's reveals' geometry are given 'HolePunching' attributes that link them together so they will then 'transform' as one.
**Several component-instances can be selected and processed in one go - however, if any of the selected component-instances are already 'punched' [and therefore have 'HolePunching' attributes] then the 'Punch' option will not be available - only 'Undo Punch' will be shown - see below...
2. TO UNDO A PUNCHED HOLE:
Select a component-instance** that has been placed on a face that is 'punched' [i.e. it has 'HolePunching' attributes].
The right-click context-menu 'Hole Punching...' sub-menu should then include 'Undo Punch' as an option - pick it.
The selected component-instance will no longer punch a 3D hole through the whole 'wall' - it will only make the 2D 'cut' hole in its front 'parent' face as any normal 'cutting' component.
The punched-hole's reveals' geometry will be completely removed and the inner face healed.
That component-instance will also have its 'HolePunching' attributes removed.
**Several 'punching' component-instances can be selected and 'undone' in one go.
3. TO UNLINK A COMPONENT-INSTANCE AND ITS PUNCHED HOLE:
If you Select a 'Hole Punching' component-instance then its punched-hole's reveals will auto-select too, so that they will always 'transform' together - e.g. they will Move as one item.
If you Select any geometry forming a punched-hole all of its geometry will auto-select, but the linked component-instance will not be auto-selected.
You can 'unlink' a component-instance and its punched-hole.
Select a component-instance** that has been placed on a face that is 'punched' [i.e. it has 'HolePunching' attributes].
The right-click context-menu 'Hole Punching...' sub-menu should then include 'Unlink Punch' as an option - pick it.
The component-instance and its punched-hole's geometry are now 'unlinked' and their 'HolePunching' attributes are removed.
This 'unlinking' is permanent - so use it with care.
If later on you should want to 'Punch' the component-instance again you can, BUT the earlier punched-hole's geometry should perhaps be deleted or relocated, OR the component-instance relocated on the face to suit, to avoid clashes.
So for example the now 'unlinked' component-instance can be Moved, but the now 'unlinked' punched-hole will stay as where is; or you can Select+Erase the component-instance and the punched-hole will remain unselected and therefore unchanged.
Also the punched-hole geometry is no longer linked together and individual parts of it can now be edited as with any other 'hole' formed manually in faces.
**Several 'punching' component-instances can be selected and 'unlinked' in one go.
4. TO ERASE A PUNCHED HOLE:
If you Select the punching component-instance its punched-hole's reveals will also be auto-selected.
If you were then to press 'delete' the punching component-instance and all of its punched-hole's reveals will be removed.
Alternatively, if you Select any part of a punched-hole's reveals then all of the reveals' geometry is selected.
If you were then to press 'delete' all of that reveals' geometry will be removed; however, the punching component-instance is kept - in this case the punching component-instance automatically looses its 'HolePunching' attributes as it has no 'hole' remaining.
Therefore the right-click context-menu 'Hole Punching...' sub-menu should then include 'Punch' as its option.
If you use the Erase tool to remove a punching component-instance then the punched-hole and its reveals is NOT removed.
If you use the Erase tool [perhaps by accident] to remove only some of the punched-hole's reveals' geometry then the punching component-instance will still have its 'HolePunching' attributes linked to the punched-hole's remaining geometry, and in that case the right-click context-menu 'Hole Punching...' sub-menu will still include 'Undo Punch' as an option.
You can pick that to 'tidy up' and remove the punched-hole's remaining geometry.
You can always 'Punch' the component-instance afterwards to 'redo' the punched-hole properly, as by then the component-instance will not have 'HolePunching' attributes.
Note that you can also 'Unlink' the component-instance and its punched-hole - see above...
5. TO SWAP A PUNCHING COMPONENT-INSTANCE'S COMPONENT-DEFINITION FOR A DIFFERENT COMPONENT-DEFINITION:
You can swap a hole-punching component-instance's component-definition for a different component-definition using the tools built into the Component-Browser ["Replace Selected" etc].
This replacement component-definition might not cut a hole that is the same shape or size as the component-definition of the original component-instance.
Because the component-instance keeps its links to the reveals' geometry you can correctly this quite easily - use the 'Redo Punch' tool [or alternatively use 'Undo Punch' to remove the incorrectly formed holes/reveals, then immediately use 'Punch'], to re-punch the correct sized holes/reveals to suit the replacement component-definition's form.
6. TO SET THE MAXIMUM PUNCH DEPTH:
By default the 'Punch' will only operate on any inner-face found behind the wall's outer-face, and that in parallel it, AND that faces in the opposite direction, AND that is within 20" [500mm] of it - which is a reasonable maximum wall thickness to expect in most buildings.
However, you can adjust this maximum reveal depth at anytime - and its value is remembered with the SKP model.
To change this use the right-click context-menu 'Hole Punching...' sub-menu 'Set Depth'.
This item might be shown on its own if there are no suitable component-instances selected OR be displayed after 'Punch' or 'Undo Punch/Unlink Punch' depending on what is selected.
A simple dialog opens showing the current depth.
Enter a new maximum depth for the punched-hole's reveals, in the model's current units.
Click OK to save the currently entered value, or Cancel to leave it as it was originally shown.
The depth must be more that zero [0] and it should be carefully considered... because making it too large could result in the inner hole/reveals being formed with a face across the room !!!
However, if there is a suitable inner-face within the current maximum depth then the punched-hole will be made to suit the actual distance between the two faces.
Otherwise if there is no suitable inner-face within the maximum depth [e.g. it's a single skin wall, or the wall is very thick] then the punched-hole will be made using the maximum depth.
7. TRANSFORMATIONS:
The punched-holes/reveals geometry is linked to the punching component-instance with 'HolePunching' attributes and an 'observer'; therefore they will always 'Select' together.
Therefore the punched-hole/reveals geometry will Move, Rotate, Scale etc with the punching component-instance as if they were one item.
The punched-holes' perimeter Edges are also linked to the two faces by virtue of them being coplanar: so if either of the wall's two faces are moved relative to each other and thereby the wall's 'thickness' changes then the punched-hole's reveals will be automatically adjusted to suit, always filling the distance between the two faces.
8. COPYING:
With the newer version of this Tool you can now 'Copy' a punching component-instance [and its auto-selected punched-hole's geometry] using Move+Ctrl or Rotate+Ctrl [with xN or /N to 'Array' them if desired].
Each instance 'copy' will ultimately be 'made-unique' with its own linked punched-hole's geometry.
Note that while you continue using the Move Tool or Rotate Tool these copies will remain 'unbaked', so you must change Tool to another Tool - say the Select Tool - to complete these punched copies to re-glue/un-punch/re-punch them appropriately...
To undo this copying you will need to do two 'Undoes' - the first to undo the 'fix-duplicates' and the second to undo the Copy/Array itself that was done using the external tool. Do not leave the 'half-baked' copies after one undo, as the hole-punching will be 'cross-threaded' between instances and the new copies will not be glued to the face etc.
Note that this method of copying does mean that any 'tweaking' that might have been done to the original's reveals - e.g. splaying the sides - will be lost because ALL instances including the original one will need to be re-glued/un-punched/re-punched to resolve any copying conflicts and make them all unique.
If you are making many copies by 'Array' then it will be quicker to do this using a non-punched original component, then afterwards select it and all arrayed copies, and punch them en mass; rather that selecting a punched instance, arraying it etc, since all of them will then need re-gluing/un-punching/re-punching - which is over three times as many operations - so there will be a noticeable lag before the lot get made-unique... Remember that you can always quickly un-punch the original before copying and re-punch it with the rest after arraying...
If you do have customized reveals that you wish to retain then you need to place new instances, punch them and then 'tweak' each of their reveals as desired.
Also note that any punching-components within groups etc that are themselves copied and exploded together are also caught and will be 'made-unique'.
Note that using Edit>Copy>Paste with 'punching-components' might sometimes give unreliable results [depending on their geometry/origin], so be warned! It's recommended that you use Move+Ctrl for copying 'punching-components'...
9. REDO PUNCH:
The new version includes a 'Redo Punch' context-menu option.
It is useful if you have edited a component's shape so that the linked punched-hole's geometry is no longer the same shape as the punching-instance itself, or you have swapped an instance's definition for one with a different form.
This tool allows you to Select affected punching-instances and 'redo' their hole punching to match their current form. It is an alternative to using 'Undo Punch' and then 'Punch' on such instances.
10. REGLUE:
The new version includes a 'Reglue' context-menu option.
If you have erased a face that contained standard 'hole-cutting' instances you might have noticed that they are NOT automatically reglued to any new face you might try to reform to replace the original erased one.
This 'ungluing' will also occur with a 'hole-punching' instance made with these tools so that a full hole will no longer be punched through both wall faces.
This 'Reglue' tool can be used to reglue any such wayward instances.
Note that it works for both instances of standard 'hole-cutting' components AND this tool's own 'hole-punching' instances.
You simply Select the affected instances [you don't need to be too careful selecting as 'non-gluing' objects are ignored anyway] and then run the 'Reglue' tool from the context-menu - they will each glue to the face that they are currently placed on and 'cut' the appropriate hole in that face: with any hole-punching ones the full depth punched hole will also reappear as before...
11. UNDO:
All Hole-Punching operations are 'one step' undoable.
However, note that when copying punching component-instances the first 'undo' will undo the tool's 'fix-duplicates' operation but a second 'undo' is needed to undo the actual copying itself.
12. ACROSS-SESSION ATTRIBUTES:
The Hole Punching 'maximum depth' is remembered across sessions, saved within each model.
The connectivity between each punching component-instance and its punched-hole's geometry is remembered across sessions, using their linking 'HolePunching' attributes and 'observers'.
Provided that this script loads at startup, setting the 'observers', then they will continue to auto-select as one and therefore transform as one etc.
Donations:
by PayPal to info @ revitrev.org
Version:
1.0 20100914 First Release.
1.1 20100914 Components exactly matching wall-depth glitch fixed.
Zero depth in dialog trapped.
1.2 20100915 Finding correct inner-face methods improved.
'Unlink' option added.
1.3 20101002 New AppObserver added to keep hole_punch observers firing when
model is 'from menu' as 'open' or 'new'.
1.4 20101229 Copied/Arrayed punching-instances are now 'made-unique'.
1.5 20101230 'Reglue' and 'Redo Punch' options added.
1.6 20101231 DeBabelizer/lingvo-file language translation options added for
EN-US, DE, FR, ES etc. 'Reglue' only appears if selection
contains potential gluing instances.
1.7 20110121 Observers are now first removed then added to avoid
duplication and rare clashes with other scripts.
1.8 20110208 Finding Cutting Component's 'loop' edges to match with
Punched hole algorithm improved to avoid glitches if multiple
edges in the Z=0 plane.
1.9 20110209 Context-menu code recast to avoid exacerbating gray-out issue.
2.0 20110309 Punched hole algorithm improved for nested groups/components.
2.1 20110824 Input box code improved. If cutting defn has curved edges
then the extruded reveals are now 'smoothed' to match.
2.2 20120628 Fixed rare DefnsObserver Bugplat! onQuit with some DC coded edits.
