Categories
Lucid Builder v4

Configuring the Lucid Builder

First Loading the Builder

The first time the Builder loads you will be asked to define a workspace folder. This workspace folder will be where your preferences and other settings for the Lucid Builder and Player will be stored.

By default the Builder will suggest a ‘Lucid’ folder within your user profile folder. You may choose any location and folder name you desire, however the folder must be accessible and allow reading and writing. If the folder is deleted the stored preference will be lost and the Builder will ask you to define a new workspace.

Lucid Builder Workspace dialog
Lucid Builder Workspace dialog.

Preferences

The Preferences panel allows some aspects of the Lucid3 builder to be configured to your own specifications. The Preferences panel is accessed by selecting Builder Preferences from the Edit menu.

Preferences are arranged under four tabs – General Operations, Item Trees, Scoring, and Spreadsheet Scoring.

General Operations

Lucid Builder Preferences dialog
Lucid Builder Preferences dialog.

Key Options

Load last opened tree on startup

Check this to ask the Builder to automatically open the key that was open in the Builder when it was last shut down. This option is particularly useful if you work for a considerable time on one key.

Automatically save key when required

Certain operations within the builder require the key to be saved prior to the action being performed, such as Key Preview. If this option is checked the Builder will automatically perform the save operation before the action is taken.

Confirmation Prompts

Item or tree delete operations

Check this to ask the Builder to prompt with a warning dialog when an item in the Features or Entities trees is being deleted. By default, the Builder will warn of this operation, as a deletion operation cannot be undone. See the topic Deleting items in the Feature and Entity trees for more information.

Media delete operations

Check this to ask the Builder to prompt with a warning dialog when a media item is to be deleted. By default, the Builder will warn of this operation, as a deletion operation cannot be undone.

Item or tree cut operations

Check this to ask the Builder to prompt with a warning dialog when an item in the features or entities tree is being cut. See the topic Moving items using Cut, Copy and Paste for more information.

Tree drag drop operations

Check this to ask the Builder to prompt with a warning dialog when an item in the Features or Entities trees is dragged from one location and dropped to another. By default, the Builder will warn of this operation. See the topic Moving items using drag and drop for more information.

Changing feature score type

Check this to ask the Builder to prompt with a warning dialog when a feature score type is being changed using the menu items Change feature into a numeric feature or Change feature into a multistate feature. By default, the Builder will warn of this operation, as score data associated with the feature will be lost if the change is in error. See Feature type in Setting Properties for Items for more information.

Updates

Check for updates on startup

Check this option if you want the builder to check with Lucidcentral.org for a new update. An Internet connection is required for this option.

Item Trees

Lucid Builder Preferences dialog - Tree options
Lucid Builder Preferences dialog – Tree options.

Tree Colours

Selection colour for focused item trees

Sets the background label colour for the selected item within the active tree panel.

Selection colour for active item trees

Sets the colour used to highlight the selected item in the active tree panel. For example, items selected but focus has changed within the tree to a context menu.

Selection colour for inactive item trees

Sets the colour used to highlight the selected item in the inactive tree panel.

Background colour for item trees

Sets the background colour for the tree panels (active or inactive).

Scoring

Lucid Builder preferences dialog – Scoring Options.

Normal Scoring

Background colour for selecting panel (normal scoring)

Sets the background colour of the panel (features or entities) that holds the selected item currently being scored, when scoring multistate features.

Background colour for scoring panel (normal scoring)

Sets the background colour of the panel (features or entities) that holds the items with score boxes currently being scored, when scoring multistate features.

Dependency Scoring

Highlight colour for controlling feature or state (dependency scoring)

Sets the highlight colour of the controlling feature or state for which dependencies are being set.

Numeric Scoring

Background colour of selected row (numeric scoring)

Sets the background colour of the currently active row in the Numeric Scoring window.

Background colour of selected cell (numeric scoring)

Sets the background colour of the currently active cell in the Numeric Scoring window.

Score Table (Spread Sheet Scoring)

Lucid Builder Preferences dialog - Score Table options
Lucid Builder Preferences dialog – Score Table options.

Highlight font colour

Sets the font colour for highlighted row and column headers in the Scoring Spreadsheet.

Highlight cells when the mouse moves

Check this to set the Spreadsheet Scoring panel to display highlighted tracks to the current cell. On a slow computer, this may unduly slow down scoring operations.

Highlight background colour

Sets the background colour for highlighted row and column headers in the Scoring Spreadsheet.

Categories
Lucid Builder v4

Lucid Builder Exporting keys using XML datasets

Applies to Matrix key projects

Lucid Builder Export Key Menu
Lucid Builder Export Key Menu

To create an XML Dataset, choose Export Key from the File menu, click the browse button in the Export Key dialog, then within the File Export dialog provide a file name, select the XML dataset file type and then click save. Finally click the export button in the Export Key dialog to complete the export.

Step 1.

Lucid Builder Export key dialog
Lucid Builder Export key dialog.

Step 2.

Lucid Builder Export Key File Browser dialog with Dataset XML type selected
Lucid Builder Export Key File Browser dialog with Dataset XML type selected.

Step 3.

Lucid Builder Key Export dialog. XML Dataset selected. Click the Export button to complete the export.

Note

The XML dataset file does not contain the key’s media, only references to where the media can be found. Therefore if you need to transfer a XML dataset file to another computer you should also copy the key's media directories.

Categories
Lucid Builder v4

Lucid Builder Exporting keys using LIF3

Applies to Matrix key projects

Lucid Builder Export Key Menu
Lucid Builder Export Key Menu.

To create a LIF3, choose Export Key from the File menu, click the browse button in the Export Key dialog, then in the Key Export file dialog provide a file name, select the LIF3 file type and click save.

Step 1.

Lucid Builder Export key dialog
Lucid Builder Export key dialog.

Step 2.

Lucid Builder Export Key File Browser dialog (LIF3 selected)
Lucid Builder Export Key File Browser dialog (LIF3 selected).

Step 3.

Lucid Builder Export Key dialog
Lucid Builder Export Key dialog file name and path specified. Click the Export button to complete the export process.

The LIF3 file does not contain the key’s media, only references to where the media can be found. Therefore if you need to transfer a LIF3 file to another computer you should also copy the media directories.

Note

If the LIF3 file and media directories are moved to another computer it may be necessary to modify the reference to where the key’s media can be found on the new computer. You can do this by opening the LIF3 file in a standard text editor, searching "for media base_path", and editing the path name of the Media directory.

For example:

<media base_path="C:\program files\Lucid3\my key\Media">

Should be changed to:

<media base_path="{new_computer’s_path}\Media">

Where new_computer’s_path is the full path name including drive letter of the Media directory on the new computer.

Categories
Lucid Builder v4

Lucid Builder Importing keys using LIF and LIF3 files

Applies to Matrix key projects

Lucid Builder - Import key menu option
Lucid Builder – Import key menu option.

LIF (exported from the Lucid Version 2 Builder), and LIF3 files exported from the Lucid3/4 Builder can be imported into the Lucid4 Builder using the following steps:

  1. Create a new key (New from the File menu)

  2. Save the key (Save or Save As… from the File menu)

  3. Choose Import Key from the File menu, select the desired file type, then browse for the appropriate file and follow the prompts.

If any errors are detected when importing a key, they will be listed in a dialog box for review. The file can still be imported, but errors may result in only a partial import. For example, if an image is missing the key can be imported but the reference to the image will be removed.

Categories
Lucid Builder v4

Lucid Builder Import Merging

Applies to Matrix key projects

Import merging allows key authors to work collaboratively, with individual keys, or parts of keys, edited separately and then merged into a single key. Feature, States, Entities and scores in the individual keys are merged.

To merge keys, open the base key (usually the most complete version of the key; but see under Score Merging below to understand score dominance) into which the others will be merged, then import a second key (the import key) using the Import option from the File menu. If the Feature/State or Entity lists in the two keys being merged are not identical, the merged key will comprise the entire, combined set of Feature/States and Entities.

All import options support merging.

During the import process, if an item in the imported key is found to be identical to an item in the base key, the imported item’s score data will be merged with the base key’s item’s scores. If an imported item is not identical to any items in the base key, it will be added, with its score data, to the base key’s item tree. In some cases, imported data will result in unresolvable conflicts, usually due to tree structure constraints; see below for information relating to resolving such conflicts.

Score Merging

In all cases the imported item’s scores are dominant compared with the base key’s scores, and are merged using the following rules:

  • Multistate scores: Present > Rare > Misinterpretation > Absent > Uncertain
  • Dependency scores: Negative > Positive > Absent
  • Subset scores: Present > Absent

Numeric scores are merged using the following rules:

  • Features to be merged must have equivalent measurement units.
  • Rows are merged based on equality and overlap, as shown below.
ImportedExistingResult
Non-overlapping import
(1-)2-3(-4)(10-)20-30(-40)(1-)2-3)(-4), (10-)20-30(-40)
Overlapping import
(5-)8-15(-30)(10-)10-20(-40)(5-)8-20(-40)

Import Conflicts

If any unresolvable conflicts are detected during the merging process, the imported nodes that resulted in the conflict will be placed under an ‘Unmerged’ node at the root of the tree. These nodes will need to be dealt with manually dragging and dropping them to a suitable location in the key. Typical causes of unresolvable conflicts are tree structure constraints (E.g. Attempting to import a Feature as a child of a multistate Feature).

Categories
Lucid Builder v4

Lucid Builder XML Dataset Files

XML Dataset files are xml documents containing all the data (Feature and Entity lists, item properties, score data and media attachment references) for a key. XML Dataset are primarily used as the data format for upload to the Lucid Key Server Player application.

See the Key deployment help topic for further information on key deployment options.

Note

A XML Dataset file for a key does not contain the key’s media, only references to where the media can be found. Therefore if you need to transfer a XML Dataset file to another computer you should also copy the key’s media directories.

Categories
Lucid Builder v4

Lucid Builder LIF3 (Lucid Interchange Format version 3) Files

LIF3 files are xml documents containing all the data (Feature and Entity lists, item properties, score data and media attachments) for a key. LIF3 files can be used to back up keys, and for easily transferring keys from one computer to another.

Note

The LIF3 file for a key does not contain the key’s media, only references to where the media can be found. Therefore if you need to transfer a LIF3 file to another computer you should also copy the key’s media directories.

You can do this by opening the LIF3 file in a standard text editor, searching “for media base_path”, and editing the path name of the Media directory. For example:

<media base_path=”C:\Fungi\Lucid\my fungi key\Media”>

should be changed to:

<media base_path=”{new_computer’s_path}\Media”>

where new_computer’s_path is the full path name including drive letter of the Media directory on the new computer.

Categories
Lucid Builder v4

Lucid Builder LIF (Lucid Interchange Format) Files

Applies to Matrix key projects

Keys exported as LIF files from the Lucid2 Builder can be imported into the Lucid Builder using LIF (Lucid Interchange Format) files. A LIF file is a simple text file with sections for the different data elements (Feature and Entity lists, multistate and numeric score data, and multimedia attachments).

Note

The LIF file includes references to the directories holding media (html and image files) for the original key. If you have moved the key after creating the LIF file, you may need to modify the path for each of the five media directories. Open the file in a standard text editor, search for "[..Multimedia Directories..]" and edit the media references, changing the path in each reference to an appropriate path for the folder that holds the media:

[..Multimedia Directories..]
Sounds "C:\Program Files\Lucid\My key\Sounds\"
Images "C:\Program Files\Lucid\My key\Images\"
Macros "C:\Program Files\Lucid\My key\Macros\"
Text "C:\Program Files\Lucid\My key\HTML\"
Video "C:\Program Files\Lucid\My key\Video\"

Categories
Lucid Builder v4

Lucid Builder CSV (Common Separated Value) Files

Applies to Matrix key projects

CSV files are text files that hold the basic data for the key (feature and entity lists and multistate and numeric score data), with one row per state, and entities and their scores separated by commas. CSV files can be opened in many spreadsheet and database programs such as Microsoft Excel and Access. If you have data in an Excel file or database, you may structure the file into a format compatible with the Lucid CSV format (see below) and export as a CSV file for import into the Lucid Builder.

Download a test key (lucid v4) and its corresponding CSV to help see how they correspond to each other.

CSV Import Options

Lucid Builder Import CSV import dialog
Lucid Builder Import CSV import dialog.

File orientation

Entity columns

If selected, Entities are expected in the columns of the CSV file.

Feature/State Columns

If selected, Features/States are expected in the columns of the CSV file.

Import options

Merge existing scores

Scores contained within the CSV file will be merged with any existing scoring contained for the feature/state entity combination.

Replace existing scores

If selected, any matching feature and entity will have it’s scores removed and replaced with the scoring contained within the CSV file.

Export CSV Key

Lucid Builder Export CSV Key dialog
Lucid Builder Export CSV Key dialog.

Filename

Enter or browse for the destination CSV filename using the Browse button located to the right of the Filename text box. If the defined file name already exists within the file system you will need to confirm the file is to be overwritten when Export is selected.

Export Options

Transposed (entities as rows)

If selected, the CSV file that is output will have the Entities are rows, rather than the default Entities as columns.

Split Files

If your key is particularly large, or your version of Excel is quite old and doesn’t support the larger row and column counts now available, the you can tell the Builder to export the key across multiple CSV files based on the maximum rows and columns defined.

Maximum Rows

Maximum rows of data to be output into each CSV file.

Maximum Cols

Maximum columns to be output into each CSV file.

CSV Structure

The structure of a CSV file compatible with the Lucid Builder can be represented as follows:

CSV structure

Entity 1Entity 2Entity 3 ...etc
State 1ScoreScoreScore
State 2ScoreScoreScore
State 3 ...etcScoreScoreScore

Entities are represented using the full path name (colon-separated) of the entity in the entity tree. For example, if a key has the following entity hierarchy:

Brassicaceae
        Brassica
                Brassica oleracea
                Brassica juncea

The entity Brassica oleracea would be represented as:

Brassicaceae:Brassica:Brassica oleracea

States are represented using the full path name (colon-separated) of the state in the feature tree. For example, if a key has the following feature hierarchy:

Flowers
        Colour
                White
                 Yellow

The state white would be represented as:

Flowers:Colour:white

For multistate features

The value of Score will be as follows:

0 – absent
1 – present
2 – rarely present
3 – uncertain
4 – present by misinterpretation
5 – rarely present by misinterpretation
6 – not scoped

For more information on the Lucid score values, see the topic About Lucid Scores

For numeric features

Numeric features are represented using the full path name (colon-separated) of the feature in the feature tree, suffixed with ‘#’. For example, if a key has the following feature hierarchy:

Flowers
         Petals
                  Length

Where Length is a numeric feature, the feature Length would be represented as:

Flowers:Petals:Length#

The value of Score is a string with five colon-separated values in the format:

Score Type: Rare Low Value: Low Value: High Value: Rare High Value

For more information on numeric values, see the topic Scoring Numeric Features.

Note

Numeric measurement units are not supported by the CSV format and will need to be defined manually after import.

Importing and Exporting data from Excel

If you wish to exchange data between the Lucid Builder and Microsoft Excel via CSV, please note the following:

  • Only one worksheet may be imported at a time.
  • The first row must contain Entity names and the first column must contain feature:state names. Use colon-separated values to create trees of Features and Entities.
  • The first cell must be blank.
  • Excel worksheets can have a maximum 1,048,576 rows by 16,384 columns. The maximum characters supported within a column is 255 characters.

Tip

The fastest way to see what the Lucid CSV file looks like is to create a small key with a couple Features, States and Entities. Then export the key to CSV. Open the exported CSV file in Excel or your preferred text editor, such as Notepad++.

Categories
Lucid Builder v4

Importing and Exporting

Lucid supports import and export via a number of file formats:

  • Lucid Interchange Format (LIF) files are simple, text-based files that are used to import keys from the Lucid Builder Version 2.

  • Lucid Interchange Format version 3 (LIF3) files are XML-based files that can store all Lucid key data, allowing you to back up your key or to exchange it with other key developers.

  • Lucid XML Dataset (XML Dataset) files are XML-based files that can store all Lucid key data. The primary use is for uploading key data to the Lucid Key Server Player application.

  • CSV (Comma separated Value) files are text files with data items separated by commas. CSV files are used to import and export key data between the Lucid Builder and spreadsheet program such as Microsoft Excel, or databases such as Microsoft Access.

  • Media List files are XML-based files that contain entities and their associated media.

  • Simple text files can be used to import and export the feature and entity trees.

Lucid Builder Data Import and Export options

FILE TYPEDATA INCLUDEDIMPORTEXPORT
LIFFull keyYESNO
LIF3Full keyYESYES
XML DatasetFull keyYESYES
CSVFeatures, entities, score dataYESYES
Media ListFeatures and Entity media referencesYESYES
TextFeatures and EntitiesYESYES

In addition, DELTA (Descriptive Language for Taxonomy) files can be imported into the Lucid Builder via LIF files created by the Lucid Translator, available from the Lucidcentral website. See the Lucidcentral topic Notes for DELTA Users for more information.

LIF (Lucid Interchange Format) Files

Keys exported as LIF files from the Lucid2 Builder can be imported into the Lucid3 Builder using LIF (Lucid Interchange Format) files. A LIF file is a simple text file with sections for the different data elements (feature and entity lists, multistate and numeric score data, and multimedia attachments).

Note: The LIF file includes references to the directories holding media (html and image files) for the original key. If you have moved the key after creating the LIF file, you may need to modify the path for each of the five media directories. Open the file in a standard text editor, search for “[..Multimedia Directories..]” and edit the media references, changing the path in each reference to an appropriate path for the folder that holds the media:

[..Multimedia Directories..]

Sounds “C:\Program Files\Lucid\My key\Sounds\”

Images “C:\Program Files\Lucid\My key\Images\”

Macros “C:\Program Files\Lucid\My key\Macros\”

Text “C:\Program Files\Lucid\My key\HTML\”

Video “C:\Program Files\Lucid\My key\Video\”

LIF3 (Lucid Interchange Format version 3) Files

LIF3 files are xml documents containing all the data (feature and entity lists, item properties, score data and media attachments) for a key. LIF3 files can be used to back up keys, and for easily transferring keys from one computer to another.

Note: The LIF3 file for a key does not contain the key’s media, only references to where the media can be found. Therefore if you need to transfer a LIF3 file to another computer you should also copy the key’s media directories

You can do this by opening the LIF3 file in a standard text editor, searching “for media base_path”, and editing the path name of the Media directory. For example:

 

should be changed to:

 

where new_computer’s_path is the full path name including drive letter of the Media directory on the new computer.

CSV structure

Entity 1Entity 2Entity 3 ...etc
State 1ScoreScoreScore
State 2ScoreScoreScore
State 3 ...etcScoreScoreScore

Importing/Exporting Data

Lucid Builder Export Key dialog
Lucid Builder Export Key dialog.
To export a key, choose File > Export > Export Key from the menu, choose the file type and a location for the exported file, enter a name for the file and click Save. Flatten Entity Hierarchy – this option will covert the keys entity tree view into a flat list using List View names (edited or automatic). This is useful if preparing a key for the Lucid Mobile Platform, which doesn’t support tree view hierarchies or if you prefer a simpler entity list for a target user group. To export a feature or entity list, choose File > Export > Export Feature List or File > Export > Export Entity List from the menu. To import a key, choose File > Import > Import Key from the menu and browse for the appropriate file To import a feature or entity list, choose File > Import > Import Feature List or Import > Import Entity List from the menu and browse for the file.