commit 5fbeb5c6df8797aa26d9d03904862bcf52a8be9c
parent edc920604a2c4766308c06b8eab522f5b3583702
Author: Vincent Forest <vincent.forest@meso-star.com>
Date: Fri, 12 Feb 2016 15:34:51 +0100
Push further the project overview in the README file
Diffstat:
| M | README.md | | | 79 | ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++----------------- |
1 file changed, 62 insertions(+), 17 deletions(-)
diff --git a/README.md b/README.md
@@ -1,29 +1,74 @@
# Star 3D
-The purpose of the library is to declare a virtual 3D environment that can be
-ray-traced and sampled efficiently. Currently, the virtual scene can contain
-triangular meshes only.
+## Overview
-## How to build
+Star-3D is a C/C++ library whose purpose is to manage a virtual environment
+composed of 3D triangular meshes. The resulting virtual world can then be
+ray-traced and sampled, providing an efficient way to deal with geometric data
+of arbitrary 3D contents. In addition of purely geometric data, user defined
+per vertex attributes can be defined. This provides a simple way to handle 3D
+attributes that spatially varies over the geometry surface. The target user of
+Star-3D are software engineers that have to deal with complex 3D environments
+as numerical simulation engineers, researchers in complex systems or graphics
+programmers. Its backend relies on the [Embree](https://embree.github.io)
+library to ensure high ray-tracing performances on a wide range of x86
+architectures.
-The *Star-3D* library uses [CMake](http://www.cmake.org) and the
-[RCMake](https://gitlab.com/vaplv/rcmake/) package to build. It also
-depends on the [RSys](https://gitlab.com/vaplv/rsys/) and
+The main concept exposed by the Star-3D C API are *shapes*. A *shape*
+represents a 3D object whose data is defined by the user and can be updated at
+any time. A 3D environment is built by attaching one or several *shapes* to a
+*scene*. To access the *scene* data through sampling, ray-tracing or indexing,
+one have to enable a *scene session* that commits the current *scene* geometry
+as the geometry to use. We point out that a *scene* can also be instantiated
+into one or several *shapes*, each with its own attributes (e.g. position).
+Since the *scene* geometry is stored once even though it is instantiated
+several times, this feature can be used to create extremely complex environment
+with a low memory footprint.
+
+Star-3D is currently used in several softwares dealing with complex arbitrary
+3D contents, ranging from graphics applications and thermal simulations to
+electromagnetism. Please refer to these projects for informations on their
+purpose.
+
+ * [Star-Display](https://gitlab.com/meso-star/star-display.git)
+ * [Star-Schiff](https://gitlab.com/meso-star/star-schiff.git)
+
+## Install
+
+### Pre-requisites
+
+Star-3D is compatible GNU/Linux as well as Microsoft Windows 7 and later, both
+in 64-bits. It was successfully built with the [GNU Compiler
+Collection](https://gcc.gnu.org) (versions 4.7 and later) as well as with
+Microsoft Visual Studio 2015. It relies on [CMake](http://www.cmake.org) and the
+[RCMake](https://gitlab.com/vaplv/rcmake/) package to build. It also depends on
+the [RSys](https://gitlab.com/vaplv/rsys/) and
[Embree](https://embree.github.io/) libraries.
-First ensure that CMake is installed on your system. Then install the RCMake
-package as well as the RSys and Embree libraries. Finally generate the project
-from the `cmake/CMakeLists.txt` file by appending to the `CMAKE_PREFIX_PATH`
-variable the `<RCMAKE_INSTALL_DIR>/lib/cmake`, `<RSYS_INSTALL_DIR>` and
-`<EMBREE_INSTALL_DIR>` directories, where `<RCMAKE_INSTALL_DIR>`,
-`<RSYS_INSTALL_DIR>` and `<EMBREE_INSTALL_DIR`> are the install directories of
-the RCMake package, the RSys and the Embree libraries, respectively. The
-generated project can be edited, built, tested and installed as any CMake
-project.
+### How to build
+
+First ensure that CMake and a C/C++ compiler is installed on your system. Then
+install the [RCMake](https://gitlab.com/vaplv/rcmake.git) package as well as
+the [RSys](https://gitlab.com/vaplv/rsys.git) and
+[Embree](https://embree.github.io) libraries. Finally generate the project from
+the `cmake/CMakeLists.txt` file by appending to the
+`CMAKE_PREFIX_PATH` variable the `<RCMAKE_INSTALL_DIR>/lib/cmake`,
+`<RSYS_INSTALL_DIR>` and `<EMBREE_INSTALL_DIR>` directories, where
+`<RCMAKE_INSTALL_DIR>`, `<RSYS_INSTALL_DIR>` and `<EMBREE_INSTALL_DIR`> are the
+install directories of the RCMake package, the RSys and the Embree libraries,
+respectively. The resulting project can be edited, built, tested and installed
+as any CMake project.
+
+Example on a GNU/Linux system:
+
+ ~ $ git clone https://gitlab.com/meso-star/star-3d.git
+ ~ $ mkdir star-3d/build && cd star-3d/build
+ ~/star-3d/build $ cmake -G "Unix Makefiles" -DCMAKE_PREFIX_PATH="<RCMAKE_INSTALL_DIR>/lib/cmake;<RSYS_INSTALL_DIR>;<EMBREE_INSTALL_DIR>" ../cmake
+ ~/star-3d/build $ make && make test
## License
-*Star-3D* is Copyright (C) |Meso|Star> 2015-2016 (<contact@meso-star.com>). It
+Star-3D is Copyright (C) |Meso|Star> 2015-2016 (<contact@meso-star.com>). It
is a free software released under the [OSI](http://opensource.org)-approved
CeCILL license. You are welcome to redistribute it under certain conditions;
refer to the COPYING files for details.
