******************************
About SALOME SIERPINSKY sample
******************************

SIERPINSKY is a simple example of SALOME module written in C++ and
implementing services via CORBA interface. It works in conjunction
with SALOME RANDOMIZER sample module; with latter it interfers by means
of CORBA services (see below).

RANDOMIZER and SIERPINSKY modules implement simple interface to calculate
Sierpinsky fields.

For more information please visit the SALOME platform web site:

  <http://www.salome-platform.org/>

=======
License
=======

SALOME platform is distributed under the GNU Lesser General Public License.
See COPYING file for more details.

Also, additional information can be found at SALOME platform web site:

  <http://www.salome-platform.org/downloads/license/>

============
Installation
============

--------------
Pre-requisites
--------------

SALOME platform relies on a set of third-party softwares; some of them are needed
at build time only, while other ones are needed in runtime also.

For more information about the pre-requisites please visit SALOME platform web
site:

* Check Release Notes and Software Requirements of the latest SALOME release at

  <http://www.salome-platform.org/downloads/current-version/>

* Pre-requisites page at SALOME web site:

  <http://www.salome-platform.org/downloads/license/>

Note: SALOME SIERPINSKY needs SALOME KERNEL, SALOME GUI, SALOME RANDOMIZER and,
optionally, SALOME Mesh modules as pre-requisites.

------------------
Basic Installation
------------------

The build procedure of the SALOME platform is implemented with CMake.
In order to build the module you have to do the following actions:

1. Set up environment for pre-requisites (see "Pre-requisites" section above).

2. Create a build directory:

   % mkdir SIERPINSKY_BUILD

3. Configure the build procedure:

   % cd SIERPINSKY_BUILD
   % cmake -DCMAKE_BUILD_TYPE=<mode> -DCMAKE_INSTALL_PREFIX=<installation_directory> <path_to_src_dir>

   where
   - <mode> is either Release or Debug (default: Release);
   - <installation_directory> is a destination folder to install SALOME SIERPINSKY
     module (default: /usr);
   - <path_to_src_dir> is a path to the SALOME SIERPINSKY sources directory.

   Note: by default (if CMAKE_INSTALL_PREFIX option is not given), SALOME SIERPINSKY
   module will be configured for installation to the /usr directory that requires
   root permissions to complete the installation.

4. Build and install:

   % make
   % make install

   This will install SALOME SIERPINSKY module to the <installation_directory>
   specified to cmake command on the previous step.

-------------------
Custom installation
-------------------

SALOME SIERPINSKY module supports a set of advanced configuration options;
for more details learn CMakeLists.txt file in the root source directory.

You can also use other options of cmake command to customize your installation.
Learn more about available options by typing

   % cmake --help

=============
Functionality
=============

* RANDOMIZER module

SALOME RANDOMIZER module is implemented as pure Python module. It does not have
any GUI. The IDL interface includes two methods:

- void InitPoint( out double theX, out double theY );

  to generate a random 2D point; X and Y coordinates are in [0,1) range;

- long NextIteration();

  to calculate next random iteration step: the integer value in range {1,3}.

The functionality of this module is used by SIERPINSKY module to calculate
Sierpinsky fields.

* SIERPINSKY module

The engine interface includes the following methods:

- void Init( in double X1, in double Y1, in double X2, in double Y2, in double X3,
             in double Y3 );

  to initialize the engine with three points which will be used as reference points
  in the calculations;

- void Reset();

  to initializes the engine with three default reference points: (0.5, 1), (0, 0),
  (1, 0);

- void NextPoint( in double X, in double Y, in long iter, out double nextX,
                  out double nextY );

  calculates next iteration point, basing on the previous one and the iteration
  step given from RANDOMIZER engine; this method is called subsequently in the loop
  to generate the points cloud;

- boolean ExportToJPEG( in string fileName, in long size );

  exports the collected points data to the JPEG file;

- boolean ExportToMED( in string fileName, in double size );

  exports the collected points data to the MED file.

  The Init() and Reset() methods clear the collected points data and prepare engine
  to the new calculations. The JPEG file can be viewed with help of any image viewer
  supporting JPEG format. The MED files created by ExportToMED() method can be then
  imported in the SALOME ParaVis module for the visualization (see below).

=====
Usage
=====

* Start SALOME:

   ${KERNEL_ROOT_DIR}/bin/salome/runSalome --modules=SMESH,RANDOMIZER,SIERPINSKY

* Create new study: menu File - New

* Activate SIERPINSKY module: click the corresponding button on the 'Components' toolbar
  or select it in the "Components" combo-box.

  The only action of the SIERPINSKY module's GUI is available via 'Sierpinsky' main menu
  - it is a 'Run' command (there is also corresponding button on the toolbar).
  This command opens 'Run Sierpinsky Algo' dialog box which allows:
  - Defining a start point for the calculations; if 'Random' checkbox is turned on, the
    start point will be generated automatically via RANDOMIZER module functionality.
  - Defining three reference points for the algo; if 'Random' checkbox is turned on, the
    reference points will be generated automatically via RANDOMIZER module functionality;
    if 'Default' checkbox is turned on the default values will be used.
  - Entering the number of the points to be calculated.
  - Creating JPEG image after the calculcations are finished; 'Image size' parameter defines
    the size of the image side in pixels.
  - Exporting results to the MED file after the calculcations are finished; 'Mesh size'
    parameter defines the mesh range.

    After pressing the 'Start' button the calculation begins. It is possible to stop the
    calculation by pressing 'Stop' button. The progress bar in the lower part of the dialog
    box displays the calculation status.

===============
Troubleshooting
===============

Please, send a mail to webmaster.salome@opencascade.com.