Coords-Tag toolset...

Settings Dialog
Add Coords-Tag by Pick [Optional Incrementing Prefix/Ref]
Update All Tags
Text to Tag
Tag to Text
Tag at Cpoint
Cpoint at Tag
Export Coords-Tags to CSV
Import Coords-Tags from CSV
Add Coords-Tag by Dialog

#coordstexttagtoolfromdatum.rb

TIG (c) 2010 - 2014
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.
All rights reserved.

This Script adds a submenu 'Coords-Tag...' to the Plugins Menu, within that are several tools:

'Add Coords-Tag'

On clicking it becomes the active tool.
Selecting another tool stops this tool.
Hovering on a point tells you its Coords from a Datum (default [0,0,0])
The current Coords-Datum XY/Z/XYZ is displayed in the bottom VCB bar and varies depending on the Settings.
Left-clicking the mouse button will add a 'Coords-Tag' at that point, with the XY/Z/XYZ Coords adjusted to match the Datum.

NOTE:

Manually editing a Tag is not possible as it will revert to the specified format if it updates; however, if you end your text-string with '=' this is then taken taken as a 'Prefix' for the Tag; so if it reads:
1.2, 3.4, 5.6 and you add the prefix #pt001= the Tag becomes #pt001=1.2, 3.4, 5.6 ;
this also can be exported to CSV as a LAST*** column as a 'reference'
[also see below for the v2.4 auto-Prefix option].

Note from v2.4 the exported AND imported CSV formats are in the format X,Y,Z,# - where the FOURTH column is the Prefix - if any...

From v2.4 there is an option to 'Prefix Prompt?:' - Yes|No.
Initial default is 'No': if 'Yes' after each Tag is clicked you are prompted for the Prefix text - it initially defaults to '#001', if it is '' OR you press Cancel/Esc then no Prefix is added, otherwise on or a click on OK the Prefix text is added to the Tag, and the next pick is awaited for the next Tag.

The prompt has 'Auto-Increment?' Yes|No: if 'No' you must manually change the Prefix each time, the default 'Yes' will auto-increment the Prefix for the next Tag. You will usually want to increment numerical Prefixes [099 > 100 > 101...], but with 'Yes' letters increment too [A > B > C...]
The auto-incremented Prefix is remembered during the whole session [e.g. '#002'], so the next time the tool is used that is shown in the dialog.
If you change the Prefix and then OK that will form the basis for future auto-incremented Prefixes during that session.
Note that you do NOT need to add a '=' at the end of the Prefix this is auto-added for you.
You can change the default starting Prefix by editing the line starting:

'@@prefix='

To change the Datum XY/Z/XYZ values you use 'Coords-Tag' sub-menu item 'Settings, then Add' item.
You can set new values for X/Y/Z AND the units for each one.

The options are:
Datum-X value is shown in the Model's current units/accuracy.
Datum-Y value is shown in the Model's current units/accuracy.
Datum-Z value is shown in the Model's current units/accuracy.

these are the Coords-Datum's three values.

XY-Units "/'/yd/mile/m/cm/mm/km/LatitudeLongitude/LongitudeLatitude/
Z-Units "/'/yd/mile/m/cm/mm/km/

these are the displayed units in the 'Coords-Tag' itself.
The default for both is 'm' [meters].
Examples:
setting 'XY' to '' and 'Z' to 'feet' ['] makes the tag display as "Z: 1.234" [i.e. in 'feet'];
setting 'Z' to '' and 'XY' to 'm' makes the tag display as "XY: 1.123, 4.567" [in 'meters' (m)];
[Note: You can't have both XY and Z == '' !];
setting 'XY' to 'km' and 'Z' to 'm' makes the tag display as "XYZ: 1.234567km, 8.901234km, 5.678m" [if units=='Yes'];
setting 'XY' to 'Latitude_Longitude' etc >>> Y=Latitude & X=Longitude, which is based on the current Geo-Referencing of the Model - *this is irrespective of the values set for the X/Y Datum as set in the earlier items.

The Z Datum is shown in the 'LatitudeLongitude' if the Z-Units is not set to .
If you change the Geo-Referencing and have 'LatitudeLongitude' tags use the 'Update' menu item - see below...

You set the number of d.p. in the next two items in the dialog...

XY-DP 0 to 6 [suggested] default is 3: suggest >=6 for Lat-Long.
Z-DP 0 to 6 [suggested] default is 3.
you'll want values like mm = 0 so "123mm, 456mm, 789mm", m = 3 so "1.234m, 5.678mm, 9.012m", or for imperial perhaps feet = 3 "1.234'".

The XY and Z values are set separately since using km and m you'll probably want xy = 9 & z = 3 >>> "1.234567km, 8.901234km, 5.678m".

The next dialog item lets you choose to show the Coords' 'units' suffix:

DecSep: ./, [default '.'] - to change the decimal-separator to locale.
LatLongFmt: +/- [default NSEW] - alternative +ve/-ve format for KML etc.
Units?: Yes/No [default is 'No'] e.g. if in meters "1.234m" or "1.234".

The next item lets you choose to place the 'Coords-Tags' onto a layer called 'COORD'.
The layer is made if it doesn't exist:

Layer?: Yes/No [default is 'No']

The last item:

From v2.4 there is an option to 'Prefix Prompt?:' - Yes|No:
Initial default is 'No': if 'Yes' after each Tag is clicked you are prompted for the Prefix text -
it initially defaults to '#001', if it is '' OR you press Cancel/Esc then no Prefix is added,
otherwise on or a click on OK the Prefix text is added to the Tag,
and the next pick is awaited for the next Tag.

The prompt has 'Auto-Increment?' Yes|No:

if 'No' you must manually change the Prefix each time,
the default 'Yes' will auto-increment the Prefix for the next Tag.
You will usually want to increment numerical Prefixes [099 > 100 > 101...],
but with 'Yes' letters increment too [A > B > C...]
The auto-incremented Prefix is remembered during the whole session [e.g. '#002'],
so the next time the tool is used that is shown in the dialog.
If you change the Prefix and then OK that will form the basis for future auto-incremented Prefixes during that session.
Note that you do NOT need to add a '=' at the end of the Prefix this is auto-added for you.
You can change the default starting Prefix by editing the line starting:

'@@prefix='

On OK any existing 'Coords-Tags' will be updated to the new datum/format.

The 'Coords-Datum' is remembered as an Attribute with the saved Model.
If you subsequently Move a 'Coords-Tag' it will update to show its new location relative to the current Datum.
On exiting the 'Settings' dialog the 'Add Coords-Tag' tool is activated...

Other 'Coords-Tag...' menu options include:

'Update All Coords-Tags'

This updates any existing 'Coords-Tags' to use the current 'Settings'.
They will auto-update when the Model opens, and when the 'Settings' dialog is OK'd,
and also when a 'Coords-Tag' is moved;
however, if you change a Model's Geo-referencing and have the 'XY-Units' set as 'Latitude_Longitude',
then an existing 'Coords-Tag' will not update until either the Model re-opens,
the 'Settings' dialog is OK'd or it is moved -
therefore this option will force ALL 'Coords-Tags' to update.

'Text to Coords-Tag'

This changes all selected 'Text' into 'Coords-Tags'.
If a 'Coords-Tag' layer [COORD] is set they are moved onto that too.
Use with care because the Texts' contents will be lost in the change...
UNLESS you answer 'NO' in the dialog to use the original text as a Prefix...

e.g. If the original text were "#001" on answering 'YES' it is discarded and the Tag becomes
"1.234m, 8.901m, 5.678m"
or on answering 'NO' the Tag gets the original text as a Prefix + '=', as
"#001=1.234m, 8.901m, 5.678m"
It is one step undo-able.

'Coords-Tag to Text'

This changes all selected 'Coords-Tags' into 'Text'.
That is they are 'frozen' and no longer seen as being a 'Coord-Tag' to be updated automatically.
It is one step undo-able.
You can always convert selected ones back into a 'Coords-Tag' using the menu item 'Text to Coords-Tag' explained above.

'Coords-Tag at Cpoint'

This adds a 'Coords-Tag' at all selected Cpoints [Guide-points].

'Cpoint at Coords-Tag'

This adds a Cpoint [Guide-point] at all selected 'Coords-Tags'.

'Export Coords-Tags to CSV'

This exports all of the 'Coords-Tags' in the Model into a CSV file in the format

[units],Y[units],Z[units],#***
or
LAT,LONG,Z[units] || LONG,LAT,Z[units] (Yes|No choice from an additional v3.2 dialog)

The 'units' used in the XYZ values in the CSV file are those currently set in the tool's settings/dp etc, NOT the display setting.
***The '#' is any Tag's 'Prefix' (if any) like '#001=', which can be optionally added to the CSV in the FOURTH column (without the final '=') [from v2.4]...

'Import Coords-Tags from CSV'

This imports all of the 'Coords-Tags' in the Model from a CSV file in the format

X,Y,Z or LAT,LONG,Z or LONG,LAT,Z

the values must be comma separated and consist of numerals onl,
with '.' as the decimal separator,
one point per line.
A dialog then requests the 'units' used in the CSV file for XY and Z,
and if you want to add Cpoints [defaults are 'm' and 'Yes'].
If the CSV file has a '#header' line etc it is ignored.
If a 4th 'column' contains 'text' it is used as a prefix,
e.g. the line "1.2,3.4,5.6,#001" becomes the Tag "#001=x1.2, 3.4, 5.6"

'Add Coords-Tag by Dialog'

This opens a dialog into which you can type the X/Y/Z values for a new 'Coords-Tag':
you can also choose to add a Cpoint at that point Yes/No, and an optional 'Prefix',
e.g. #001 - this is added on to the Tag as #001= .
The values of the X/Y/Z should match the current 'Coords-Tag Settings'.
The tile-bar will shows these as say XY=km,Z=m
Remember - Latitude/Longitude +ve is North/East and -ve is South/West.

Notes:

You can 'attach' a 'Coords-Tag' to any specific point in the Model by using the main Sketchup 'Text' tool to drag/re-snap its arrow to any location.

In the start of the CoordTool_Datum code, you can change the default text-offset-vector,
edit its class-variable values inside the []:

@@vec= [2,2,2] ### xyz offset for text from arrow-head

You can also change the text prefixes etc used for the 'Coords-Tag'/Prompts inside their "":

@@sufXY= "XY: "***
@@sufZ= "Z: "*** ### e.g. "Height: "
@@sufXYZ= "XYZ: "***
@@sufLL= "LL: "***
@@sufLLZ= "LLZ: "***
@@sufCD=" Coords-Datum: "
@@sufCDXY= "Coords-Datum XY: " ### e.g. "E&N: "
@@sufCDZ= "Coords-Datum Z: " ### e.g. "Datum Height: "
@@sufCDXYZ= "Coords-Datum XYZ: "

and the 'Coords-Tag' layer name can be changed too:

@@layer_name="COORD"

EOF

1.1 20101104 First Release.
1.2 20101118 Tool extended: Add/Settings/Update/Text to Coords-Tag/Coords-Tag to Text/Coords-Tag at Cpoint/Cpoint at Coords-Tag.
1.3 20101118 Export Coords-Tags to CSV option added.
1.4 20101119 'Add by Dialog' option added. Error is reading datum fixed.
1.5 20101120 Balls up on datum v. tag values sorted !
1.6 20101120 Dialog forces 'units' choice. Decimal-separator ./, option.
1.7 20110123 Typo in dialog Longitude/Latitude corrected. Starts with model Long/Lat in 'Add-dialog'.
1.8 20110124 Typos in Import-CSV fixed to allow -ve values, z=0 & no z.
1.9 20110206 Glitch with XY/Z== fixed.
2.0 20120828 Inputbox code improved. LatLong now has variable dp . Text2Tag now has option to keep original text as Prefix=, and option added to 'Add' dialog and Import-CSV [4th column], also Export-CSV option to make 1st column of 'Prefix='. Separator corrected to ,/; for ./,
2.1 20120829 LatLong +/- option added [thanks @pmolsen] to match KML etc.
2.2 20120829 Incorprates minor code improvements in NSEW v. +/- [from pmolsen].
2.3 20130611 CSV -ve values now import properly.
2.4 20130809 Option to add Prefix under 'Add' added - input dialog + enter... The imported AND exported CSV files now both use the last column as #Prefix/Reference - X,Y,Z,#.
2.5 20130811 #Prefix dialog now has Auto-Increment?: Yes|No option.
2.6 20130828 Glitch with Z only coord's XY fixed...
2.7 20130904 Minor typos in code addressed. Units now always show in CSV header.
2.8 20131205 Major rewrite. Future-proofed.
2.9 20131228 More future-proofing.
3.0 20131230 Glitch in plugin naming fixed.
3.1 20140228 Error in CSV Importer corrected.
3.2 20140301 Options for Lat+Long || Long+Lat in display and CSV import/export.
3.3 20140318 CSV import strings forced to UFT8 for v2014.
3.4 20140321 CSV import strings more robustly forced to UFT8 for v2014.