Hi Ed,

re:
> That's a great feature. Is it possible to create or append a note via a script?

Yes, it's a property script can access through moi.geometryDatabase.notes .

So for example:

var notes = moi.geometryDatabase.notes;

moi.geometryDatabase.notes = 'set notes to this';

moi.geometryDatabase.notes += 'add this to notes';


The next v5 beta will have an additional channel of document and object user text available for scripts to store data attached to the .3dm file or to individual objects. Those will be stored as key/value pairs so that a script can use its own unique key name and not stomp on some other script's data as can happen using notes as a script data store.

- Michael

Sounds like a great new feature!

If a new script has added some notes to the current .3dm file,

how are the notes read back from the .3dm file and displayed on the screen?

Or is the next beta5 required?

- Brian

Hi Brian, in the current v5 beta you can display the file notes using this button on the File menu:



The part that will be new for the next v5 beta is that the notes dialog will have this button for "Document user text":



That will allow you to view or set key/value pairs that will be stored in and read back from the .3dm file like notes, but these
will work better than notes for storing scripting data because a script can use a unique id for the Key part and so avoid having
other scripts overwrite its data which is what will happen if a bunch of scripts all try to put stuff into the regular "notes":




Then also another new thing for the next v5 beta is on the "Details..." object properties dialog there is similar Key/Value text that can be set on objects:





- Michael

Thank you Michael.

Looking forward to examples of how users will use these features.

A user could write, or modify a brief script to add some personalized notes to his .3dm file? Say a car design...
The script would have some sort of key label or code?
The key label is private? or public?
Another user could utilize the same key label?
Another user could have their own script and different key label, to add additional personalized notes to the .3dm file?

(These questions are an attempt to better understand the beneficial use of notes.)

- Brian

Hi Brian, notes are for whatever information you might want to keep track of for a particular .3dm file.

You could put in for example the date the project started, customer name and e-mail address of the client who commissioned some work that this is a part of, paste in e-mail discussion from the client, paste in a web site address where you found some relevant information, etc...

You could do all of this kind of stuff in a text file saved alongside of your .3dm file, but the advantage of notes is that they are packaged inside of the .3dm file and so can be a little easier to manage.

But you can think of the notes as basically a text file packaged inside the .3dm file.

Also if the notes window is open when you save the .3dm file, it will be automatically displayed in the same position when the .3dm file is reopened so you can put information in there that will be shown to someone when they open the file if there is information that you want them to know about.


The key/value document user text is a place for scripts to save data inside the .3dm file instead of them needing to use a separate text file for data storage as well. The Key values are not private but the intent is they should be some identifier unique to the script (such as the script's name for example) so that it will not be likely to be accessed and overwritten by some other script.

- Michael

Would it be feasible to add a password protection/security mechanism to the extended data like notes and key/value pairs?

Thanks for your response Michael.

One of the reasons for my original question is that I was wondering if the Notes feature could be a way to embed instructions for running a complex script.

For example, if instructions were in the script's JS file, they could be copied over to a Note. If the Note could be opened with a button in the script, then the user would have an easy way to read the instructions.

Currently script instructions are either in a forum posting, or in the JS code as remarks. Neither is easy to get to. We've seen recently with Max's scripts how forum postings and code can become deleted or decoupled, making it difficult to patch information back together.

So, just wondering if you think Notes are a viable way to give users easy access to script instructions, or is there a better way?

Ed Ferguson

Hi Burr,

re:
> Would it be feasible to add a password protection/security mechanism to the extended data like notes and key/value pairs?

Not really - the notes and user text are part of the regular structure of .3dm files and there is not any provision for them to be encrypted.

- Michael

Hi Ed, you don't need to try and funnel the text through file notes in order to show it, the script can just display an alert dialog or show its own custom dialog to display text.

Check out this thread for an example of setting up a help button in a script's UI and having the text displayed when the button is pushed:
http://moi3d.com/forum/index.php?webtag=MOI&msg=10768.1

The Notes function is a text field that's saved in the .3dm file where the user can record any information they want so it would not be good for a script to funnel its own text through there, that would mangle the user's note information.

- Michael

See recent LogSpiral8 script for script blue help button example, as per Michael's link.

- Brian

Notes can embed an image, or just put the image as imported image on the scene in the 3Dm itself ?

These notes features are super cool Michael!

Although I did read the release notes, thanks Ed for asking about them as Notes had slipped my mind.

I like to keep notes on things I'm building (materials list, order of operations, etc.) and having these notes as embedded text objects within the .3dm file is wonderful as it seems that separate notes often get "separated" from the model in question (due to my own sloppiness).

The key/value pair idea seems apt for Teddy's ViewManager script to avoid the separate json file & would probably work well for the recent request to be able to save CPlane(s).

Christmas is all year long when you're in a beta cycle Michael!

--Larry

@Pilou
> Notes can embed an image, or just put the image as imported image on the scene in the 3Dm itself ?

No, notes are plain text only, no images.


@Larry,
> The key/value pair idea seems apt for Teddy's ViewManager script to avoid the separate json file & would
> probably work well for the recent request to be able to save CPlane(s).

Yup, it should be good for that type of stuff.

- Michael

Thanks Michael for explaining the intent of the MoI Notes feature.

Given that Notes is not a good fit for my script's large Help File, I decided to use a variant of Brian's (bemfarmer) & BurrMan's ideas:

Rather than use an HTML file or plain text, I'm using a PDF file. The PDF contains text, embedded images and links to websites (even YouTube videos).

If you have a MoI script named FooBar:

Write a help file in MS Word. Paste in images and links as needed. Save the Word document as PDF to your commands subdirectory.

Add this division to the script's FooBar.htm

      

<div>
            <!--  Help file is located at: 
            On Windows:  C:/Users/<username>/AppData/Roaming/Moi/commands/FooBarHelp.pdf
            On Mac:  /Users/<username>/Library/Application Support/Moi/commands/FooBarHelp.pdf
            -->
           
            <moi:LabelButton onclick="moi.filesystem.shellExecute( moi.filesystem.getAppDataDir() + 'commands\\FooBarHelp.pdf' );">
            
            <img src="moi://ui/icons/HelpIcon.png" style="width:2em;"/>
            
            Help
</div>

When finished, C:/Users/<username>/AppData/Roaming/Moi/commands/ [ On a Mac: /Users/<username>/Library/Application Support/Moi/commands/
contains:

FooBar.js
FooBar.htm
FooBarHelp.pdf

When Help is clicked, your browser opens and displays the Help contents.

Note: Even though Microsoft Edge is not my default browser, Edge opens when I click Help. Microsoft Edge comes with a built-in PDF reader that lets you open your local pdf files, online pdf files, or pdf files embedded in web pages. Chrome should also view PDFs. Other browsers may require a PDF plugin.

Ed Ferguson

Hi Ed,
I think that your technique is excellent.

Having the PDF help files in the appdata commands folder seems OK.
Should the PDF's be in a separate directory under appdata?

It seems to me that writing documentation is as hard as writing the script.
Need to improve skills in document writing.
Maybe the PDF could have sub sections?
Overview, with pictures.
Main text, and pictures.
Credits.
Links.
?

- Brian

Thanks Brian,

Yes - the PDF Help File can have all those things and more :)

I like that images can be embedded, making additional subfolders & image files unnecessary.

Plus, it's easier to write a PDF in MS Word than make an HTML file and mess with all the formatting tags.

Also, you could have multiple Help files as MS Word can translate into another language before saving as PDF. That may be an option in cases where translating the script's controls would cause text labels, dropdowns, sliders, and inline check boxes to no longer fit the allotted space.

I chose to name and place the three related script files:

FooBar.js
FooBar.htm
FooBarHelp.pdf

together inside the commands subfolder because:

1) It keeps the files clustered together in the file manager list, thus easy to see everything related to a given script at once.

2) I hate hunting through subdirectories unless they are absolutely necessary to keep things organized.

- Ed Ferguson

Hi Michael, I like the look of these "notes" feature in V5.
I might help me save some of the gems in this forum ;o)

Understand this is almost brand new, but do you think it
would it be soon be viable to be able to export (or import)
this note data into a .csv?

Can see some pretty good ways to use this for simple job
costing etc.

Kindest

Stefano

Hi Stefano, for "Notes" you can get them in v5 under File > Notes.

That's just one piece of text, so I'm not sure how you would want that in .csv form?

Then there is also "Document user text" which scripts can use to store Key / Value pairs of text.

Is it the Document user text that you want to export to .csv ?

- Michael

Hi Michael, I was looking at the user values behind the
The object properties “details” initially thinking this could be useful.

Maybe this is only for storing scripts or could any values be assigned under key/value

Example
Key = object name
Value = object name

Key=cost/sqm
value =100

Key = object m2
Value = 1

Export this to csv - you’d have a list of 3 columns
and 3 values. 4th column could be a calculation in excel.
Idea to bring in object data into key values would make this very interesting. Maybe we could quote from a drawing.

Hi stefano, so the user data is primarily intended to be a way for scripts to store data on either the document or on individual objects.

The script can use a unique name for the "key" part to avoid having some other script trying to store data in the same spot.

Scripts can access document user text by using these functions:

moi.geometryDatabase.setUserText( key, value );
var text = moi.geometryDatabase.getUserText( key ); // returns undefined if no user text is there.
var list = moi.geometryDatabase.getAllUserText();
moi.geometryDatabase.removeUserText( key );
moi.geometryDatabase.clearAllUserText();

Document user text is stored inside .3dm files.

The user can see and add or modify document user text values in the UI under File > Notes > “Document user text”.


User text can also be set on individual objects. The UI for setting these is under Details… > Object user text.

The object level user text has the same functions that are on the document:

obj.setUserText( key, value );
var text = obj.getUserText( key );
var list = obj.getAllUserText();
obj.removeUserText( key );
obj.clearAllUserText();


MoI itself does not currently make use of any user text value, it’s there for scripts to use if the script wants to store some data on particular objects or for the document.

You wrote:
> Maybe this is only for storing scripts or could any values be assigned under key/value
>
> Example <...>

Sure, you can set these values on the user text. They will only be very useful though if you have set up a script that will access those values and do something with them.

re:
> Export this to csv - you’d have a list of 3 columns

Do you mean you want something like column A quantity, column B object name, column C cost/sqm ?

It is possible for a script to write to a text file. Some info here:
http://moi3d.com/forum/index.php?webtag=MOI&msg=9665.2

- Michael