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:
Create a new key (New from the File menu)
Save the key (Save or Save As… from the File menu)
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.
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:
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.
Imported
Existing
Result
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).
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.
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:
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:
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.
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.
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 1
Entity 2
Entity 3 ...etc
State 1
Score
Score
Score
State 2
Score
Score
Score
State 3 ...etc
Score
Score
Score
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:
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
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.
The CSV is UTF-8 encoded.
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++.
CSV Special Characters
If your CSV file contains special characters (e.g. non-Latin alphabet) and you wish to open it in Excel then you may need to do the following to open the CSV with the correct encoding:
Start a new empty spreadsheet.
Using the ‘Data’ menu. Select the ‘From Text/CSV’ option. Normally the second option on the toolbar as shown here: Lucid CSV file open in Excel – handling special characters.
Browse for the CSV file. The import dialog should then show, and the correct encoding options should be detected and automatically selected as show here: Lucid CSV Excel automatic encoding detection.
Finally, click the ‘Load’ button. The CSV data should now appear correctly encoded in your spreadsheet.
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 TYPE
DATA INCLUDED
IMPORT
EXPORT
LIF
Full key
YES
NO
LIF3
Full key
YES
YES
XML Dataset
Full key
YES
YES
CSV
Features, entities, score data
YES
YES
Media List
Features and Entity media references
YES
YES
Text
Features and Entities
YES
YES
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.
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.
Media List is an open XML based format that enables the Lucid Builder to import media data for Entities,Features or Couplets.
Lucid Builder Import Media List dialog
The media files referenced within the Media List file must be located within the keys media folder, normally within the HTML or Images folders, prior to importing. Unless you are using a Force or Ignore option within the ‘Other options’ dialog section.
Importing a Media List file
From the menu File > Import > Import Media List
Select the Media List file by browsing your computer file system. Before importing you have the following options.
Import Options
Import Feature/Couplet media
Match and import media specified by the selected Media File to the keys Feature or Couplet list, depending on the project key type.
Import Entities media
Match and import media specified by the selected Media File to the key Entity list.
Matching Options
Match partial names
Your media list may not contain an exact match for the Entity or Feature/Couplet name label listed in the Builder. For example, within your key you may have the taxonomic name for the Entity followed by a common name, where the media list file may only contain the taxonomic name. The builder can use a partial match method to link the media to the correct Entity or Feature. If no match can be found then the non-matching items from the Media List file will be reported prior to the import occurring.
Attach to best match
When the Builder is matching the Media List item to a Feature/Couplet or Entity it may encounter multiple valid matches, especial when the ‘Match partial names’ option is selected. The ‘Attach to best match’ will try to determine the best (closest matched) Entity or Feature/Couplet and only perform one attachment for that Media List item. If this option is not selected and the Builder encounters multiple valid matches, then the Media List item will be attached to multiple items in the Feature/Couplet or Entity tree.
Media Options
Import image media
Check this option if you want image media types from the Media List to be imported.
Import text media
Check this option if you want HTML media types from the Media List to be imported.
Import File references
Check this option if you want to import media items that are file references found in the selected Media List file.
Import URL references
Check this option if you want to import media that are URL references found in the selected Media List file.
Other Options
Remove Existing Media
This option will remove all the media associated with all the Entities or Features within the key, depending on which is selected in the Import Options section of the dialog. Use this with caution if you have manually attached other media to the entities prior to using this option. Re-importing a Media List that contains the same items will not cause duplicate media attachments within the key.
Create or replace thumbnails
If selected, during the import process, any image attachments from the Media List will be thumbnailed. Reattachments will also be thumbnailed. Thumbnail sizes will be set based on the maximum thumbnail dimensions set within the Key Options dialog.
Force import of all media
The Builder will create the media linkage based on the Media List location reference, even if the media location doesn’t match what the Builder is expecting based on the keys Media folder structure.
Ignore missing files
The Builder by default checks for the presence of the file prior to attaching it during the import process, unless this option is checked. If this option is checked the Builder will create the media linkage in the key regardless if the media image exists where specified by the Media List. If you use this option, you are are expected to deal with any broken media linkages within the key. You can check for ‘broken’ or missing media attachments via the ‘Tools…Check Media’ report tool from the main menu.
Tip
The Fact Sheet Fusion content editor supports the export of media lists, which can be used in the Lucid Builder to quickly attach all your media.
