Lucid Phoenix Builder
Installation Requirements
System Requirements
Windows OS
98/ME/NT(SP6a)/2000(SP3)/XP(SP1)
Pentium 166MHz
HD: 75MB
RAM: 32MB
Macintosh OS
OS X 10.3 or greater
HD: 51MB
RAM: 128MB
Linux OS
A flavour of Linux that supports J2RE, such as: Read Hat 7.3/8.0 SuSE 8.0, TurboLinux 7.0 or SLEC 8 Pentium 166MHz
HD: 85MB
RAM: 32MB
Solaris OS: 7, 8 or 9.
RAM: 128MB.
HD: Up to 70MB
Java
Java Runtime Environment (JRE) version 1.4.1 or greater must be installed. To check if you have Java installed on your system type "Java -version" in a Command prompt (Windows) or Terminal console (Mac, Unix).
For example:
If you receive an unknown command error message or your Java build number is less than 1.4.1 then you need to install the latest (free) edition of JRE, which can be found at http://www.Java.sun.com
For help installing the JRE please see: http://www.Java.com/en/download/help/index.jsp
For FAQ on the JRE please see: http://www.Java.com/en/download/faq/index.jsp
What is Lucid Phoenix?
Lucid Phoenix, a member of the Lucid family of products, is used to create, deploy, maintain and play interactive pathway keys (also often called dichotomous keys). Pathway keys are one of two main types of identification keys. The other type, matrix keys (also often called interactive or random-access keys) are built and played using other Lucid products (see www.lucidcentral.org for more information on the Lucid family of products).
A pathway key is a traditional form of identification guide that takes the form of a series of questions or statements, each question or statement leading to either another question or statement, or to a result (an identified taxon or entity). Pathway keys are so named because the questions or statements are arranged in the form of a branching pathway, each branch ultimately leading to an identification. At each branching point a question with two or more answers, or two or more statements, are presented. The answer or statement that best describes the entity (taxon or other thing) being identified is chosen at each step.
There are several traditional ways of writing pathway keys, but all have the same basic structure.
| An example of a simple coupleted statement key.
Statements are written in groups (couplets), each with a go-to. Choose which statement of the couplet is correct for the specimen to be identified, then go to the couplet number indicated.
1. Flowers blue.................................2
1a. Flowers red..................................3
2. Fruits fleshy...................Species 1
2a. Fruits woody.................Species 2
3. Trees..............................Species 3
3a. Shrubs..........................................4
4. Leaves hairy.................Species 4
4a. Leaves not hairy...........Species 5
|
The same key written as a simple indented statement key
Statements in a group (couplets) have the same indent level. Choose which statement of the couplet is correct for the specimen to be identified, then go to the couplet immediately below
Flowers blue
Fruits fleshy.......................Species 1
Fruits woody......................Species 2
Flowers red
Trees..................................Species 3
Shrubs
Leaves hairy....................Species 4
Leaves not hairy..............Species 5
|
| The same key written as a branching tree with questions and answers
Begin at the top of the key with the first question, choose which answer is correct for the specimen to be identified, then follow the arrow to the next question.
|
Lucid Phoenix comprises three main programs:
The Lucid Phoenix Builder is used to create, edit and manage pathway keys for the Phoenix system.
The Lucid Phoenix Importer is used to capture existing pathway keys, such as published dichotomous keys, into the Phoenix Builder.
The Lucid Phoenix Player is used to play interactive pathway keys deployed through the Phoenix Builder.
The Lucid Phoenix Builder and Player can handle keys in either the traditional statement form or the question-answer form. The Lucid Phoenix Importer can import digital copies of keys in either coupleted or indented form (although with some limitations - see The Phoenix Importer section for more information.
What does a Phoenix Key look like?
Phoenix keys look very different from traditional, printed pathway keys, but they work on the same principle. The Phoenix Player is divided into four windows:
Please note that all Phoenix programs will look slightly different on different computer platforms and under different operating systems. The example screen shots are indicative only.
The Questions panel at top left contains the pair or group of statements (or answers) to address. If the key is a question-answer key, the question is shown above the questions panel and the answers are shown within it. If the key is a statement key, the statements are shown in the panel.
Choose one statement or answer by clicking on it. Entities Remaining lists all entities that match the chosen path so far, while Entities Discarded lists entities that have been discarded from consideration. The History panel maintains a history of choices so far.
As you proceed through the key progressively addressing each couplet in turn, so the list of entities will be reduced until, hopefully, only one remains. The identification is complete.
Click here for more information on the Lucid Phoenix Player.
Lucid Phoenix Builder
Default Phoenix Builder Interface
under Windows XP.
The Phoenix Builder is used to create and maintain keys for the Phoenix Player. It comprises three main panels:
- The Couplet Tree Panel holds the structure of the Phoenix key (the couplets arranged in a tree).
- The Entities Panel holds lists of entities in the key and is used to associate entities with couplets of the key.
- The Properties panel is used to attach multimedia (images and html pages) to couplets and entities in the key.
Building and managing the Couplet Tree
The Couplet Tree is the core of a Phoenix key. It comprises couplets arranged in a tree, each couplet with two or more leads. Couplets and leads can be added, moved, removed or renamed at any time.
To begin creating a new key from scratch, first click the Add New Child button 
on the toolbar. A new couplet lead will be created:
Edit the text of the lead and/or the couplet question
Note: in a key using the question-answer form for couplets, use the couplet questions for the question text and the couplet leads for the answer text; in a key using the coupleted statement form, ignore the couplet question and use the couplet leads for the statements. You may hide the couplet questions using the 
toggle button on the toolbar.
Continue building the key's tree by adding more leads and couplet questions. Leads may be added as siblings, children or parents of any currently selected lead. Leads and couplet questions that have children may be opened or closed using their 
and 
buttons.
Moving leads
Leads in the couplet tree may be dragged and dropped to new positions, with the following restrictions:
1. A couplet lead cannot be dragged and dropped onto one of its children.
2. A couplet lead cannot be dragged and dropped onto a child of one of its sibling leads
Care should be taken moving leads, as it can destroy the logical structure of the key. Moving leads is most useful when a partially built key needs to be substantially rearranged. It is safest in this case to create a new lead at the root of the couplet tree, and move leads from the old to the new lead, rearranging the tree in the process.
Ctrl + Drag will change a sibling to a child drag, this function is only applicable to a couplet lead, not a couplet question.
Associating entities with leads
In a completed Phoenix key, every lead will either lead to another lead, or to an entity. No lead will lead nowhere, and no lead will lead to two or more entities.
Entities are added to the key and associated with leads using the four list panels in the Entities Panel.
To add an entity to any list of the entities panel (except the Other Entities list), click on the list and click the 
button on the toolbar (or use Ctrl-Shift-E keyboard shortcut). A dialog box will pop up for entering the name of the entity.
Two main strategies can be employed to associate entities with leads:
1. At any time during building of the couplet tree, select the topmost (root) couplet question, click on the Unassigned Entities list, then click the button and enter the name of an entity. The entity will be added to the Unassigned Entities list. Continue adding entities until all entities required for the key have been added.
To associate entities, click on a lead that you wish to assign with an entity, and drag the entity from Unassigned Entities to the topmost Entities list. Repeat for other leads and entities until all entities have been assigned. (Note: two or more entities may be selected (by holding down the Shift key while selecting a contiguous group of entities, or by holding down the Control- key while selecting a non-contiguous set) and dragged together to the appropriate list.)
2. At any time during building of the key, click on a lead that will be assigned an entity (that is, the lead will be a terminal lead in the key), click on the button (or use the Ctrl-Shift-E keyboard shortcut) and enter the name of the entity. The entity will be assigned to that lead.
Renaming, moving and deleting entities
Entities can be renamed at any time by right-clicking on an entity name and choosing Rename from the popup menu.
Entities can be deleted at any time by right-clicking on an entity name and choosing Remove or Delete. If the entity is in one of the two topmost entity lists, removing it will cause it to be moved to the Unassigned Entities list. If the entity is in the Unassigned Entities list, removing it will delete the entity permanently from the key. A warning message will appear confirming if you really want to do this.
Viewing the entities associated with a lead
As entities are progressively assigned to terminal leads, the entities lists may be used to check that entities are assigned correctly. Clicking on a lead will fill the topmost entities list with all entities that belong to the selected lead or to any child (descendent) lead of the selected lead. If the selected lead has one sibling, the second entities list will be filled with all entities that belong to the sibling lead or to any child (descendent) lead of the sibling lead. (Note: if the selected lead is one of three or more siblings, the second list will include all siblings of the selected lead).
When a lead is selected in the couplet tree its sibling leads are highlighted. The highlight colour can be defined in the Builder preferences.
Associating multimedia with items in the key
Any lead in the key may have a thumbnail image associated with it, which displays when the lead is displayed in the Phoenix Player. Any entity in the key may have a thumbnail that accompanies it in the Phoenix Player. It may also have an associated web pages, accessed via a hyperlink.
Thumbnail images and web pages are associated with leads and entities using the Properties Panel. Click on a lead or entity, then click on the Add Media button 
. A dialog box will appear to browse for the appropriate file.
When adding multimedia for leads, only the Images object will be available on the Properties Panel. When adding multimedia for entities, both the Images and HTML objects will be available. Click on one of these before clicking on the Add Media button, to add the appropriate file. Local HTML files must be located within the keys multimedia html folder. The HTML file selection dialog will only allow browsing within this folder or subfolder there in. Internet based URLs can be attached by using the Internet button located in the top right hand side of the browse dialog.
HTML file selection dialog
For a step by step example of building a key see the Phoenix Builder Tutorial.
Description:
Displays the text label of a selected item. Selected items can either be from the Couplet Tree window, such as couplet item or an entity from any Entities list.
Description:
Moves to the next valid item within either the selected couplet tree window or entity list.
Description:
Moves to the previous valid item within either the selected couplet tree window or entity list.
Phoenix keys can have images and html attached to couplet items and entities. The Phoenix player does not preform any dynamic image resizing therefore when attaching images within a Phoenix key you should ensure that the image is optimised for size and loading speed, especially if the key is destined for the Internet or Intranet.
Description:
Which ever node is selected will determine the type of media that is to be added.
Description:
Depending on which media node is selected will determine the add media function for either an image or HTML fact sheet. Both couplet items and entities may have one image but only entities may have an html fact sheet directly attached. Tip: To show more that one image for an entity or couplet item, create a collage image or add images into a fact sheet.
Description:
This will delete the selected media item from the currently selected item that is displayed in the property text.
Description:
This function will become available when a html media item has been selected. When clicked it will launch the operating systems default web browser to preview the html item.
Filters are a unique feature of Lucid Phoenix and are not possible in paper based keys. In the Phoenix Player, Filters are used to restrict the allowable entities in the key, according to their values in a score matrix associated with the key. For instance, a key to fly families of the World may include a filter that scores each family according to its distribution on the major continents. A user of the key may choose Africa from the filter set. Phoenix then removes all families that do not occur in Africa from the key and reformats the key's couplet tree to match the change, effectively producing a new key to the families of flies of Africa.
Filters are created by entering a list of filter items then scoring all entities in the key against the filter items.
Filters dialog.
Add Button - Adds a new filter item to the filter list.
Remove Button - Removes a filter item from the filter list.
Rename Button - Allows renaming of the selected filter item.
To score filters, select a filter item and check the box next to the entities associated with that filter.
Playing partially complete keys
The Phoenix Builder allows partially completed keys to be viewed within the Phoenix Player. If for example, a lead ends with no entity then the Builder will create an artificial entity called "UNKNOWN - KEY INCOMPLETE " within the Player file. This allows the key to be played for testing and shows that there is no entity on that path. If an end lead has more than one entity left then the Builder will create an artificial couplet that states: "This pathway has finished. The following entities remain:" Each of the entities left are then listed as leads.
These artificial items are not stored within the keys Builder files and are only created when the key is played within the Builder or deployed.
Shortcut key: Ctrl + N
Description:
Resets the Builder ready for the creation of a new key. If a key is already open and unsaved the Builder will ask to save the current key before resetting.
Description:
Opens an existing key in the Phoenix Builder format. Lucid Phoenix keys have the file extension "lp3".
Shortcut key: Ctrl + S
Description:
Allows the key to be saved to file. If the key has not been saved previously then a dialog to name and select the destination folder of the key will appear.
Note: When the key is saved a folder of the same name as the key is created by the Phoenix Builder. Contained within this folder are several other folders that the Builder requires. The "BuilderOnly" folder is used exclusively by the Phoenix Builder. This folder and its contents should not opened or modified in any way as this may cause your key to become corrupted. The "Media" folder contains two other folders called "html" and "images" these will be described in further detail in the "Adding Multimedia to a Key" section.
Shortcut key: Ctrl + A
Description:
Provides the option to save a key under another name and if desired in another location.
Shortcut key: Ctrl + D
Description:
Deletes items from within the key such as entities, couplet questions and couplet items. If an item can not be deleted then the delete icon will be ghosted. Note: there is currently no Undo Delete action available.
Shortcut key: Ctrl + R
Mouse event: Right click, within couplet tree or Entity lists, select option from pop-up menu.
Description:
Allows the renaming of text labels of items within the key such as entities, couplet questions and couplet items. Text within these labels can be modified via the text tool bar, for things such as bold, italics and font colour and size.
Description:
Shows or hides Couplet Question nodes in the couplet tree. Couplet Question nodes are used in a question-answer key. They can be hidden when creating a coupleted statement key.
Hides sub-branches within the couplet tree.
Reveals all sub-branches within the couplet tree
Shortcut key: Ctrl + Shift + P
Inserts a new couplet item above the currently selected couplet item or question. Default question text node is automatically created.
Shortcut key: Ctrl + Shift + C
Inserts a new couplet item below the currently selected couplet item or questions.
Shortcut key: Ctrl + Shift + S
Inserts a new couplet item within the selected couplet.
Causes the Add New sibling function to insert a new sibling couplet item above the currently selected couplet item.
Causes the Add New sibling function to insert a new sibling couplet item below the currently selected couplet item.
Shortcut key: Ctrl + Shift + E
Mouse event: Right click within an Entity box other than "Other Entities" or via the Edit Menu.
Description:
New Entities can be added through any Entity list other than Other Entities (See Entity list for more information).
When assigning entities to leads by dragging them from Unassigned Entities, Auto-Scoring will, if turned on, automatically assign all remaining unassigned entities to the alternate lead. Turning off Auto-Scoring will require that all entities be assigned manually to both leads.
Note: Auto-Scoring is only available when a couplet has only two leads.
Description:
Opens the Filters dialog, for scoring and maintaining a Filters set for the key. See Phoenix Filters for more information.
Play
Description:
Launches the current key in the Phoenix Player.
Menu Items - not reflected on toolbar
Delete Key
Location: File Menu
Use caution when using this function!
Description:
Deletes a selected key. This will remove the lp3 file and the associated key folder and subfolders.
Location: File Menu
Description:
Opens the key import dialog for importing existing text-based pathway keys or Phoenix lpxk files. The Import function is only available within an empty key. See Importing Existing Keys for further information.
Location: File Menu
Deploy key settings dialog.
Description:
This function deploys the Phoenix key you have built into the Lucid Phoenix Player format and wraps the key and Phoenix Player applet into a web page.
Key Title: This field sets the title of the encapsulating web page that holds the key and Phoenix applet player. This title is displayed within the web browsers application bar.
Phoenix window width: The Phoenix applet can be set to fill the entire available space within html page or defined to set proportion of it, either by a percentage or fixed width and height in pixels.
Destination: Used to select a folder where the Phoenix Player files and the key's media are exported to. The Phoenix builder will give a warning notice if a key already exists within the selected destination folder, with an option not to overwrite. It is possible for more than one key to be exported to a single destination as each key will be contained within its own key folder. The Player applet within the destination folder would then be common to all of the keys.
For example:
<Destination folder>\phoenix_player
\phoenix.jar <--- Phoenix applet.
\help <--- Phoenix Player help files
\<Key 1 Name>.html
\<Key 2 Name>.html
\<Key 1 Name Folder>\
\<Key 1 Name>.lpxk
\Images
\html
\<Key 2 Name Folder>\
\<Key 2 Name>.lpxk
\Images
\html
Posting a Phoenix key on the Internet
The following folders and files need to copied to the destination web server for the key to run correctly.
phoenix_player folder and sub folders
Key folder and sub folders
Key HTML file
The key html file is where the Phoenix Applet player is opened. An applet is a program written in the JavaTM programming language that can be included in an HTML page, much in the same way an image is included. When you use a Java technology-enabled browser to view a page that contains an applet, the applet's code is transferred to your system and executed by the browser's Java Virtual Machine (JVM).
The keys HTML page is standard HTML that contains a special applet tag that is used to open the Phoenix Player. This applet tag does not preclude the page from having normal HTML content with the Phoenix applet forming a element of the page such as with an image.
Closes the Phoenix Builder application. If a key is open and in an un-saved state then the option to save the key will be presented prior to closing.
Builder Preferences Dialog
Shortcut key: Ctrl + B
Description:
Allows the defaults setting for colour and fonts within the Phoenix Builder to be changed for both the main interface window and the filters window.
Description:
The colour selection dialog allows the selection of colour through a number of means. Each selection method gives a preview of the colour chosen.
Available colour selection dialogs.
Font Selection
Font selection dialog.
Description:
Available fonts that are present within the system are listed on the left hand side of the dialog. Click on a listed font to select it. The font size can be adjusted via the slider bar located in the middle of the dialog. A preview of the font is displayed within the bottom right hand pane. Select Set to accept the font.
Description:
Depending on which is selected the search option will find either entities or items within the couple tree.
Or
Location: File Menu
Description:
The Phoenix Builder contains a powerful import facility that can convert existing paper based keys into the Phoenix format. The import function can handle the two most common types of printed dichotomous keys, bracketed and indented. If your dichotomous key is only available in a printed format, scan the key using an Optical Character Recognition (OCR) program and save the key as a text file. You can then open this file through the Open dialog after selecting Import in the Phoenix Builder. Or once the Importer module is open by using open key. You can also use this dialog to open an existing LPXK file (for more information on LPXK file please see Appendix 1)
Import Key file selection dialog.
Import module dialog
Once a key has been loaded into the Import module it is analysed. If problems are found within the key, a 'To Do' list is generated. Each error or warning found within the key is marked with a wavy underline, red for an error and blue for a warning, at the point within the line where the error occurs. See example below.
Each couplet item must be on one line.
Each couplet item must have an identifier, question text and a destination. The second item within a couplet does not need an identifier as this can be assumed from the couplet item immediately above it.
Breakdown of a bracketed key example
The importer will change the colour of the text that represents each part of the couplet item that has been identified, as defined in the importer preferences. Between each component of the couplet item - identifier, question text and destination - there must be some form of separation. The separation can be in the form of spaces, tabs or three or more repeating characters. These separators are excluded when the text key is exported to the Phoenix Builder.
As errors or 'To Do' items are corrected within the key document window the key is re-analysed to find other errors that were hidden by previous errors. Each item within the 'To Do' list has a line number where the fault can be found within the document window. 'To Do' items can be clicked, this action takes the cursor to the line and position where the error is occurring within the key document window.
Simple example of an incomplete key showing "warning" 'To Do' items.
Once all 'To Do' items have been resolved the key can then be exported back to the Phoenix Builder.
Importer Module button bar
Shortcut key: Ctrl + N
Description:
Resets the Import module ready for the creation of a new text based key. If the text based key is already open and unsaved the Importer will ask to save the current key prior to resetting.
Shortcut key: Ctrl + O
Description:
Opens existing text based keys in the Phoenix importer module. The Importer module will open text files and LPXK files (for more information on LPXK file please see Appendix 1).
Shortcut key: Ctrl + S
Description:
Before a key can be exported back to the Phoenix builder any logical errors found within the paper based key must be corrected. These corrections or any changes that are made to the text file can be saved.
Description:
If changes have been made to the original text based key this option allows the changes to be saved in a new file.
Shortcut key: Ctrl + X
Description:
Cuts a selected piece of text into the memory clipboard.
Shortcut key: Ctrl + C
Description:
Copies a piece of text into the the memory clipboard.
Shortcut key: Ctrl + V
Description: Copies the memory clipboard where the current cursor is located.
Rolls back the previous editing history within the text based key.
Rolls forward the editing history within the text based key.
Shortcut key: Ctrl + C
Description:
Searches for a word or phrase within the text based key document.
Feature:
Start at Top: Starts the search process at the beginning of the document.
Wrap Around: Starts the search from the current cursor position and ends back at the cursor position.
Import module find dialog.
Description:
Looks for the next occurrence of the search text or phrase.
Description:
Exports the recognised text based key document that contains no 'To Do' items (See the 'To Do' items for more information) back into the Phoenix Builder. The import module closes automatically after the key has been successfully exported to the builder.
Shortcut key: F1
Description:
Displays help files associated with the import process.
Menu Items - not reflected on toolbar.
File Menu
Import Module preferences dialog
Allows for setting the colour preference for the different parts of the text based key that are recognised by the Phoenix Import Module. Selection of colours is the same as the Phoenix Builder colour preferences.
Closes the Import Module without exporting text based key data back to the Builder.
Edit Menu
Shortcut key: Ctrl + A
Description:
Selects all text within the text area of the Import Module.
Appendix
The LPXK file is the XML data file that is used by the Phoenix Player. It contains all of the information need to display and run your key.
LPXK files have the following format:
<?xml version="1.0" encoding="UTF-8"?>
<PhoenixKey title="<Key Title>" CreatedIn="<Software that created the key>">
<Identity id="<i0..i1.i.n>" name="<Identity Name>" icon="<path/graphic file>" url="<path/HTML file>" />
<FilterItem name="<Filter Name>" id="<f01..f02..fn>">
<FilteredItems><Identity Id><space><IdentityId></FilteredItems>
</FilterItem>
<Steps firstStepID = "<Step Id>">
<Step id="<s0..s1..sn>" text="<Step Description>">
<Lead stepid="<Step Id>" leadid = "<Step Id><Lead Id l0..l1..ln>" goto = "<Step Id or Identity Id>">
<Text><Lead Text></Text>
</Lead>
…
</Step>
…
</Steps>
</PhoenixKey>