Caméléon language
Caméléon language
Introduction
Concepts article is a good start to understand Caméléon underlying concepts.
Caméléon is a graphical algorithm editor. You can combine elementary components to create new compositions [Fig. 1]. All component construction features are based on a drag & drop mechanism.
Caméléon allow the creation of those components:
* Operator: Like a mathematical function, an operator, f, produces output data, y, from input data, x, as follows y = f(x). An operator (big center circle) has some input connector containing input data (little black circles including little colored or gray circles) and some output connector containing output data (little colored or gray circles including black circles).
* Control: A control is an elementary component to manipulate, set or view datas. It can be connected to operators inputs & outputs.
* Pattern: A pattern is a set of operators & controls aggregate in an elementary component. From a part of a composition you can create a sub composition, a sub process. A sub composition is reusable & sharable as pattern.
* Text & Shape: Text & Shape are used to structure & comment compositions.
Instance
A Caméléon instance is a directory holding all files, binaries needed to execute Caméléon Editor.
In the Caméléon, some directories and files are available:
/log /ressource /pattern /project instance.conf [on linux] cameleon [on windows] cameleon.exe
The root directory contains all binaries to execute Caméléon.
The log directory contains all Caméléon instance log files.
The ressource directory contains all ressource file needed by Caméléon (images …).
The pattern directory is the directory where patterns are stored by Caméléon Creator.
The project directory contains example projects. This directory must be used to store your projects.
The instance.conf file is an XML configuration file for Caméléon.
Composer
The composer allows to create and connect graphically elementary components (operator, controls, patterns) to build new composition.
* Menu Bar [Fig. 3]: The menu bar gives you access to management features
* Player Bar [Fig. 5]: Start, pause & stop the engine. You can either launch the engine step by step.
* Mode Bar [Fig. 6]: Three editing modes are available; composition (arrow icon), shape (square icon) & text (A icon).
* Comment Bar [Fig. 7]: Set up text & shape style & color.
* Glossary Tree [Fig. 4]: The glossary is like a component repository. You can create component from here.
* Project Tree: The project tree expose your prototype structure. You can navigate through sub processes & interfaces. You can add or delete interfaces.
* Composition View: The black center square. This is the place to create operators, controls & set up compositions.
* Caméléon Outputs: At the bottom, two tabs are available. The first, consol outputs, shows all Caméléon outputs. To set console outputs, go to windows > properties > project > Consol Outputs, set outputs to enable & select your outputs level for each logs. The second, Executions problems, shows all execution problmes actualy avaible. By clicking on them, the system highlight the erroneous component.
Menu gives access to saved file manager, properties etc.
* File: Save & Load Caméléon *.cm files.
* Windows: Hide & Show windows.
* Properties: Go to project or instance properties dialogs.
* Help: Go to Caméléon web site to find information.
The glossary gives access to all components which can be created by Caméléon Creator.
The glossary is a tree list view which exposed all components which can be created.
The glossary is devided in three parts:
* Operator: Set of all available algorithms. Directories under the Operator directory are named glossary.
* Control: Set of all available controls. Directories under the Control directory are named glossary.
* Pattern: Set of all available user created patterns.
Browse the glossary:
1- Open a component directory,
2- Little O icons identify components which can be created. Drag & Drop it to the composition view to create a component.
Search an operator:
1- Click on the search edit box,
2- Write a key word to search,
3- The search tool highlight corresponding components.
The player bar allow you to launch or stop the Caméléon engine.
* Run: to launch the composition execution,
* Pause: to pause the execution,
* Stop: to stop the execution,
* Next step: in pause mode, allow you to process one next operator.
The mode bar allows to change the edition mode.
* Composition Mode: The mode to compose with operators & controls,
* Shape Mode: The mode to draw shapes,
* Text Mode: The mode to write text (comments …).
The comment bar allow to manage text style & shape colors.
Those actions has effect on selected texts. Multiple selection is allowed.
* Police selector: Change selected text police,
* Size selector: Change selected text size,
* Bold button: Change selected text to Bold,
* Italic button: Change selected text to italic,
* Underline button: Underline selected text,
This action has effect on selected texts & shape. Multiple selection is allowed.
* Color selector: Change selected text or shape color.
The bring & send bar allows to manage component Z axis.
Those actions has effect on selected components. Multiple selection is allowed.
* Bring to front: Bring selected components to front,
* Send to back: Send selected components to back.
File menu allows to manage load & save project.
* new Project …: Create a new project,
* open recent project: Open a recent project list. Select a project to open it,
* open project …: Open a project on your computer,
* save project: Save a project on your computer,
* save project as …: Save a project in a specific directory,
* exit: Close Caméléon,
* save and restart: Save and restart Caméléon.
The windows menu allows to manage windows visibility.
* controller: Show/Hide the controller window,
* project tree: Show/Hide project tree,
* console output: Show/Hide console outputs,
* glossary tree: Show/Hide glossary tree.
The properties menu allows to manage instance & project properties.
* cameleon: Show Caméléon properties dialog,
* project: Show project properties dialog.
Help menu gives access to support & documentation web links.
* documentation …: Open online documentation in a web browser,
* community …: Open community links in a web browser,
* report a bug …: Open the online contact form,
* about: Open the about dialog (Caméléon version & licence are available from here).
1- Identify the operator you want to create by browsing or searching the glossary,
2- Operators are available behind the “operator” directory and are identified by a O icon,
3- Drag the operator’s name from the glossay and drop it in the composition view,
4- It creates an operator at the dropping position,
5- You can drag & drop it on the composition view to change its position (also works in multi selection).
The operator status gives information about its execution.
Connector status gives information about the connector’s data.
Organize simply the composition changing connector’s position.
1- Drag a connector to another position,
2- Be careful to keep your mouse into the connector circle,
3- Drop the mouse to set the connector position.
Hoover your mouse on an operator or a connector to show information. Select one or more component, press the ‘W’ key to show more informations.
Right Click on an operator to show the menu.
* show infos: As ‘W’ key press, it shows operator description,
* delete: delete the operator.
* (optional) actions: can expose operator specific actions.
1- Drag a connector from its position to somewhere on the composition view,
2- It shows compatible connectors (identified with yellow circles),
3- Drop on a compatible connector to connect.
After a connection, when a data will be available on output connector, it will be automatically dumped into input connector.
Note: Some datas are shared by reference or by value. The next 2.0.8 version will expose this characteristic more clearly.
Right click on a connector to show the connector contextual menu.
* disconnect: disconnect the connector,
* disconnect control: disconnect the connector from a control connector,
* show control: show the control connector connected to this connector.
1- Drag the mouse from an empty space on the composition view to somewhere,
2- It draws a selection square,
3- Drop somewhere,
4- It selects components which are under the selection square.
After multi-selection, click right somewhee to show the multi-selection contextual menu.
* show infos: show information about selected components,
* merge into sub process: merge selected component into a new sub process,
* delete: delete selected components.
1- Identify the control you want to create by browsing or searching the glossary,
2- Controls are available behind the “control” directory and are identified by a O icon,
3- Drag the control’s name from the glossay and drop it in the composition view,
4- It creates a control at the dropping position,
5- You can drag & drop it on the composition view to change its position (also works in multi selection).
Some controls are just data view, other can just edit & set data (often by pressing enter after edition). An other kind of control can edit datas using inputs datas.
You can resize the control by drag & dropping the little bottom right gray circle.
Delete selected controls.
1- Click on a control connector,
2- See highlighted compatible connectors,
3- Click on one compatible connectors to connect,
4- Connector connected to control are identified with a white circle.
1- Double click on a connector connected to a control,
2- It highlights the connected connector.
Outputs operator connector can be connected to one operator connector and one control connector. In this case, the output datas can be used by an operator and, also, be viewed by a control.
Note: Be careful to data by reference.
1- Select more than one component (operator, control, text or shape),
2- Click left somewhere,
3- A multi selection menu appears,
3- Click on “merge into sub process”,
4- It creates a sub process, a gray circle.
1- Double click on a sub process to get into,
2- Double click on the sub process background to go to the upscale level.
1- Drag a connector,
2- See highlighted compatible connectors and the sub composition highlighted,
3- Drop your mouse on the sub composition external background,
4- It create a new connector bridge on the sub composition and connect the connector to it.
1- In a sub composition, drag a connector,
2- Drop it on a sub composition connector,
3- Connectors are connected.
1- At upper scale, drag a connector,
2- Drop the mouse on a sub composition,
3- It create a new sub composition bridge & connect the dropped connector to it.
Click right on a sub composition to show the sub composition Menu.
* show infos: Show information about the sub process (those information are editable through the properties dialog),
* save as a pattern: Save this sub composition as a reusable pattern (see the pattern directory in the glossary),
* properties …: Show the properties dialog,
* delete: delete the sub composition,
* unmerge: restore the composition without the sub process.
* First edit box: This is the sub composition name field. You can edit the name here,
* Second edit box: This is a description field. You can write the sub composition description here,
* Connector List: This is the list of all sub composition connectors. The name field is editable,
* Apply button: Click on this button to apply your change,
* Cancel button: Click on this button to discard your change.
1- Identify the pattern you want to create by browsing or searching the glossary,
2- Operators are available behind the “pattern” directory and are identified by a O icon,
3- Drag the pattern’s name from the glossay and drop it in the composition view,
4- It creates a sub composition at the dropping position,
5- You can drag & drop it on the composition view to change its position (also works in multi selection).
Like for operator, you can change a connector’s position by drag & dropping it.
Click right on the pattern directory or on an other directory under pattern and click on add directory. Select a name and it will create a new directory under the selected clicked right directory.
For sub directories or patterns,
1- click right on a sub directory or a pattern,
2- select rename menu to rename the directory or the pattern,
3- select delete menu to delete the directory or the pattern.
Drag & drop pattern names or directories to organize patterns.
1- Click on the shape mode button,
2- Drag your mouse from somewhere on the composition view,
3- It draws like a selection square,
4- Drop your mouse to define the size of the shape,
5- Click on the composition mode button,
6- By drag & drop, move the shape position,
7- By drag & dropping little circle on the bottom right, you can change the shape size.
1- Click on the text mode button,
2- Right click somewhere on the composition view,
3- Write your text,
4- Click on the composition mode button,
6- By drag & drop, move the text position,
Delete selected shape and text.
* Hold the Q key on the keyboard and drag & drop your mouse to change the composition view position,
* Hold the Q key on the keyboard and use the wheel of the mouse to zoom in & zoom out.
The controller is used to create functional interface prototype usable without using the composer.
* Player Bar [Fig. 5]: Start, pause & stop the engine. You can either launch the engine step by step.
* Mode Bar [Fig. 6]: Three editing modes are available; composition (arrow icon), shape (square icon) & text (A icon).
* Comment Bar [Fig. 7]: Set up text & shape style & color.
* Glossary Tree [Fig. 4]: The glossary is like a component repository. You can create component from here.
* Project Tree: The project tree expose your prototype structure. You can navigate through sub processes & interfaces. You can add or delete interfaces.
* Interface View: The black center square. This is the place to create operators, controls & set up compositions.
The controller’s glossary is a tree list view which exposed all components which can be created with the controller.
* Control: Set of all available controls.
1- Identify the control you want to create by browsing or searching the glossary,
2- Controls are available behind the “control” directory and are identified by a O icon,
3- Drag the control’s name from the glossay and drop it in the composition view,
4- It creates a control at the dropping position,
5- You can drag & drop it on the composition view to change its position (also works in multi selection).
* persist: If active, the control will be available at the same position in all interface (see create an interface),
* delete: Delete the control,
* disconnect all: Disconnect all control connectors.
1- Click on a control connector on the controller window,
2- See highlighted compatible connectors on the composer window,
3- Click on one compatible connectors to connect,
4- Connector connected to control are identified with a white circle.
Note: Be careful to find the right position & size for both controller window & composer window. We must see both the to composition view & the interface view to connect correctly a control on the controller side to an operator on the composer side.
You can double click on the connected connector to see highlighted connected connector.
The project tree (right part of the composer or the controller) can be shown or hided using menu windows > project tree action.
The project tree allows to browse composer sub compositions or controller interfaces. It allows to create sub processes or interfaces.
Double click on a process (O icons) to show the corresponding process on the composer.
The top process (named “process”) goes to the main top composition.
Double click on a process (Square green icons) to show the corresponding interface on the controller.
The interface under pattern (named “creation”) goes to the main interface.
Click on the square green plus icon to create a new interface. A pop-up to set up its name will appear.
Click on the blue/green graph node icon to create a new sub process. A pop-up to set up its name will appear.
The sub composition is created at the center of the current composition/sub composition.
A project directory must be created by user for each new project. The save as feature must be used in this directory. For instance, we save as a new project named “project_name” in an empty project_name directory. The directory is composed of those sub-directories & files:
project_name/log project_name/ressource project_name/target project_name/tmp project_name/project_name.cm
The log directory contain the cameleon.log file (and maybe others). In case of a crash, this file can be usefull to analyse the problem. Log output is configurable through the Project Properties Logs dialog.
The ressource diretory is used to put all datas file used by the project. To share a project, it’s usefull to have a place to put those data sources (images, raw files, videos etc.).
The target directory is deprecated.
The tmp directory contain data file copy produced by the composition.
The project_name.cm file is the XML file descriptor of the project (reference to operators, data, controls, interfaces & sub compositions).
* Instance path: The instance path,
* Pattern path: Patterns are stored here,
* Plugins path: deprecated,
* Dictionaries path: dictionaries shared libraries are stored here,
* Projects path: project must be saved here,
* Ressources path: unstable,
* Auto-save step number: Number of action to launch an auto-save.
Table:
* name: The dictionary name,
* path: The dictionary path,
* version: (error) The version or an error message if miss loaded,
* activated: enable or disable the dictionary (need a Caméléon restart).
* project name
* project version
* tmp path
* log path
* projects path
* ressources path
* target directory
* connectors behavior: debug tool
* max threads: disabled because unstable
The project readme editable text box.
Firet section:
* log enabled check box: Enable or disable all logs.
Table:
* component name: Log component are autonomous log which focus on specifics parts of the Caméléon execution.
* log level: You can select your log level or shutdown a log component.
* First edit box: This is the sub composition name field. You can edit the name here,
* Second edit box: This is a description field. You can write the sub composition description here,
* Connector List: This is the list of all sub composition connectors. The name field is editable,
* Apply button: Click on this button to apply your change,
* Cancel button: Click on this button to discard your change.
When an error occurs, Caméléon highlight in red erroneous components.
You can browse error using the Execution problems tab on Caméléon Outputs (bottom part of the composer).
Double click on an error id show on the composer or controller the component where the error occurs.
At stop or pause, a Lock pop-up may appears when a component has not yet finished its work. You can press the save & restart button to relaunch Caméléon. It may be useful in debug mode when components has some infinite execution problems.
Command Line Interface (CLI)
In a command line (use git bash on windows), in the instance/bin directory, you can launch a composition like this:
./cameleon-cli.exe -mode="CLI" -cm="../project/yourProject.cm"
The help menu can be displayed with:
./cameleon-cli.exe -h
NAME
Cameleon program launcher
SYNOPSIS
ide.exe [options]
DESCRIPTION
If no option is specified, it launch the .cm file specified in the Caméléon instance file
-h: print this help or print the .cm file help if -cm option is specified
-cm=[.cm file path]: launch a specific .cm file
-mode=[IDE, GUI, CLI]: set the Caméléon mode
IDE: launch Caméléon creator in IDE mode,
GUI: launch Caméléon app with the related GUI interface (only controller windows),
CLI: launch Caméléon in a command line mode (without any GUI),
EXAMPLES
Standard launch with full IDE cameleon.exe
See the help of a specified .cm file cameleon.exe -h -cm="../project/tutorial/example-0XY-Arguments/example-0XY-Arguments.cm"
Launch a specified .cm file with full IDE cameleon.exe -cm="../project/tutorial/example-0XY-Arguments/example-0XY-Arguments.cm"
Launch a specified .cm file in command line application mode cameleon.exe -mode="CMD" -cm="../project/tutorial/example-0XY-Arguments/example-0XY-Arguments.cm"
Launch a specified .cm file in GUI application mode cameleon.exe -mode="GUI" -cm="../project/tutorial/example-0XY-Arguments/example-0XY-Arguments.cm"
Caméléon (2.1.3-testing) is an open source software edited by shinoe,
designed & developed by O. Cugnon de Sevricourt & V. Tariel
MIT license | contact | community | credits
Caméléon users :
