Copyright 2011-2012 TIG (c)
Permission to use, copy, modify, and distribute this software for
any purpose and without fee is hereby granted, provided something 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.
###
Name:
TIG-AreaTextTag.rb
Description:
NOTE from v1.1 this tool loads as an extension and needs activating
using Window > Preferences > Extensions > AreaTextTag when it is first
installed. Thereafter it will load until you deactivate it.
It adds a submenu to the Plugins menu OR a Toolbar of the same name
which needs activating from View > Toolbars [after the Extension is
loaded]:-
'AreaTextTag Tools...' containing...
'Tag Picked Faces'
This lets you add a special 'AreaTextTag' onto a Face by Picking it.
This 'Tag' is a component flat 3d Text, colored 'black', although you
can recolor it later as desired.
This 'Tag' is glued to the picked Face, centered on the picked point
Because it is glued the 'Tag' moves with the Face.
The 'Tag' can be manually relocated anywhere on the Face's plane.
By default the area in the 'Tag' is formatted in 'm2' or 'ft2'
depending on the SKP's units.
The 'm2' value is rounded to 2 dp [12.34], and the 'ft2' value is
rounded to 1 dp [1.2].
These 'units' and 'dps' can be reset using the 'Change Settings...'
menu option.
By default the 'Tag' is simply named "1.23 m2" [assuming that's the
area/units], upon making it a dialog asks for the Tag's 'text', press
Cancel to leave it as "1.23 m2", or enter additional text and press
OK, the text/area updates with the new values.
NOTE: that there are several tricks to formatting the Tag's text:
You enter/reuse/leave <> where the 'area' value is to go.
updated area text will be added later, therefore text without a <> has
one appended so that the area is appended to it [with a units suffix].
Entering <> or leaving the text blank OR pressing Cancel gives
"1.23 m2"
Using <-> gives
"1.23" [i.e. no units suffix is shown]
Entering Office 666 <> OR Office 666 [WITHOUT the <>]
"Office 666 1.23 m2"
Entering Office 666 <->
"Office 666 1.23" [i.e. no units suffix is shown]
You can also add text after the 'area' thus:
<> Office 999
"1.23 m2 Office 999"
or
Office 666 <> (Admin)
"Office 666 1.23 m2 (Admin)"
You can also separate the text over two or more lines by including
'\n' to denote the newlines, e.g:
Office 666\n<>
"Office 666
1.23 m2"
Note that the only limitation on the characters that can be used in
the Text are the combinations '<>' and '<->' which determine where the
numeric 'area' comes.
Commas ',' are best avoided if CSV files are anticipated as they are
replaced with a ';' anyway.
The Tool lets you place Tags until you press <Esc> or choose another
Tool to exit.
Later on, if desired you can Edit a 'Tag' - to change the its 'Text' -
e.g. to alter its associated room/area name - Select it and use the
appropriate 'Edit Selected Tag' tool.
If the associated Face is changed then you should Update the Tag so
that the reported area will be updated automatically for you.
If a Face is erased and it had an 'Tag' associated with it then that
Tag returns an error if you try to Edit it.
Note that AreaTextTags should always be placed in the same context as
the Face itself - in fact the tool prevents you selecting a face
outside of the active_entities.
From v1.3 there is an option to report 'Surface Areas'. If this is
set then a Face forming part of a larger mesh Surface [soft edges]
shows the area of the Surface rather than that of the Face itself.
Remember not to pick more than one Face within a mesh as you'll get
duplicate Tags.
'Tag Selected Faces'
Similar to 'Tag Picked Faces' but you Preselect the faces to be tagged
and there is no option to add additional text to the Tag, although you
can Edit a Tag later to add this. Also the Tags are glued on the
center of each Face, although these can be Moved later if desired.
Note that if there is no Selection you are give the option to Tag
ALL Faces in the active_entities...
From v1.3 there is an option to report 'Surface' areas. If this is
set then a Face forming part of a larger mesh Surface [soft edges]
shows the area of the Surface rather than that of the Face itself.
Because Selected Faces might belong to the same Surface, then only one
Face per Surface will be filtered from the Selected Faces.
To maintain control over which Face in a Surface gets the Tag added
the 'Tag Picked Faces' option is recommended [see above].
'Edit Selected Tag'
This opens a dialog in which you can change the 'Text' part of a
Selected AreaTextTag. It also updates the Tag to use the face's
current-area; however, the current Tag's units etc are retained, so to
update these to have the current-settings use the 'Update' tool...
'Change Settings + Tag Picked Faces'
This opens a dialog in which you can change the units that the
'Area Text Tag' will use from then on, drop a drop-down list, thus:
'Area Units:'
in2
ft2***
yds2
acres
mm2
cm2
m2***
hectares
m2(ft2)
The ones marked with *** are the automatic defaults for
imperial/metric SKP models.
The m2(ft2) option is for the UK where areas are measured in m2 BUT
commercial floorspace is rented in £/ft2 ! With that option the dp is
overridden and m2 are reported to 1 dp and ft2 to 0 dp*** thus:
1.0 m2
(11 ft2)
The 'current units' etc are remembered within the saved model SKP,
across sessions.
In this dialog you can also change the Area Tag's
'Text DP:' - default 2 for m2 and 1 for ft2***
'Text Font:' - default 'Arial'
[some fonts might be unavailable on your OS]
'Text Height:' - default 100mm/4"
From v1.3 there's an option to
'Report 'Surface' Areas:' - default 'No'
If this is set to 'Yes' then any Face within a mesh Surface [soft
edges] is given a Tag that reports the Surface area, rather than just
the area of the Face itself.
On OK the 'Tag Picked Faces' Tool then starts, it will now use the
'current-settings'...
'Update Selected Tags'
All selected 'AreaTextTags' are updated
You are then asked if you want to update:
AREAS ONLY [=Yes]
or
AREAS AND ALL OTHER SETTINGS [=No]
i.e. to use the 'current-settings' - units, dps, font, height.
The current area of each Tag's 'glued_to face' is ALWAYS updated
within the Text of the Tag.
The Selection can contain other non-Tags, which will then be ignored.
Note that if there is no Selection you are give the option to Update
ALL Tags...
From v1.3 there's an option to 'Report Surface Areas:' if it's set to
'Yes' then any Face within a mesh Surface [soft edges] has a Tag that
reports the Surface's area, rather than just the area of the Face
itself. So any Face that has been changed since it was last Tagged,
or its Tag was updated, will also change the reported area -
e.g. Faces might have been added to [or removed from] a mesh, or the
Face itself might be not even be part of a mesh any longer.
'Export Tags' to CSV'
You must save a new model before running this tool.
It processes Tags in the current active context.
All Tags have their areas auto-Updated, then this tool runs.
Note that from v1.3 Faces that are part of a Surface will report the
Surface's are IF the current-settings specify this.
Any Tags that are NOT glued to a Face are NOT Reported [the closing
dialog tells this and highlights them].
Any Tags that are 'duplicated' on a Face are NOT Reported [the closing
dialog tells this and highlights them].
It then makes a report of the Tags in CSV format, listing them by:
LAYER, TEXT, PERIMETER, AREA, UNITS
Reporting the 'Layer' helps divide the results up, so putting your
Tags onto Layers named 'Level0', 'Level1' etc helps you use the report
more easily.
The reported Perimeter/Area is in each Tag's 'units' - typically m/m2
or ft/ft2 - however, areas in acres have perimeters is ft and if in
hectares perimeters are in meters.
If the units are 'm2(ft2)' two extra columns are added for AREA2 and
UNITS2 to show the m2 AND ft2 version.
Any commas [,] in reported Text/Layers are changed into colons [;] to
avoid formatting errors in the CSV.
If the Model name is XXXX the report is written into
XXXX_AreaTextTagReport.csv.
The CSV report is made in the Model's folder.
If that Report is already open [>>>error] you are told/warned.
Otherwise the CSV is written and on completion the CSV file is opened.
A CSV file is readable by Excel and similar programs.
It can be linked into a XLS file that has 'formatting' so then if the
CSV updates the pre-formatted linked XLS file will change to suit.
Donations:
Are welcome by PayPal to info @ revitrev.org
Version:
1.0 20111222 First Issue.
1.1 20111224 Now made as an Extension and Toolbar added.
UK friendly 'm2(ft2)' units option added to Settings.
Edit/Update now ensures each Tag is a unique instance.
Update ALL option added if there is NO Selection.
Update highlights unglued/duplicated tags, for deletion.
Update is done automatically before making a CSV export.
CSV report ignores unglued/duplicated tags [highlighted].
CSV report includes extra columns if units are 'm2(ft2)'.
New 'Tag Selected Faces' tool added for batch tagging.
1.2 20111226 Update now has an option to update 'area only' or
'everything' including current-settings.
Update before CSV export now will only update the areas.
1.3 20120102 A Face forming part of a 'Surface' [a mesh, soft edges]
when the new current-setting "Report 'Surface' Areas:"
is set to "Yes" uses that Face's 'Surface' area, and not
the area of just that Face itself.
1.4 20120321 UTF8 accented characters etc in area-tags now resolved.
1.5 20120322 CSV fixed - uses UTF8 accented characters, now reports Tags
in active context properly.
###
