commit 0fa9ea5109151c0e813e2f10b592012ac6fd29da
parent db3853da225d5e881b2c6d371aec7b4b5d61b322
Author: Vincent Forest <vincent.forest@meso-star.com>
Date: Wed, 5 Jul 2023 12:25:12 +0200
Rewrite the README file to make it less bloated
Small rewrite of the preview section. Clean up the requirements section
and completely rewrite the installation section regarding using a POSIX
Makefile and no longer CMake as the first build system. Remove the
quickstart section which was actually useless.
Diffstat:
| M | README.md | | | 152 | ++++++++++++++++++------------------------------------------------------------- |
1 file changed, 34 insertions(+), 118 deletions(-)
diff --git a/README.md b/README.md
@@ -1,122 +1,36 @@
# Star 3D
-## Overview
-
-Star-3D is a C library that *manages surfacic geometries* and provides
-operators to access them efficiently by *uniform sampling*, *ray-tracing* or a
-*closest point query*. To ensure the efficiency of these operators, Star-3D
-internally relies on [Intel(R) Rendering
-Framework](https://software.intel.com/en-us/rendering-framework):
-[Embree](https://embree.github.io) that provides highly optimized acceleration
-structures as well as traversal kernels for a wide range of data workloads. The
-main targets of Star-3D are thus programmers that want to efficiently handle
-*complex and arbitrary 3D content.*
+Star-3D is a C library that manages *surface geometries* and implements operators
+to access them efficiently such as uniform sampling, ray tracing or a closest
+point query.
The main concept exposed in Star-3D is the *shape*. A shape represents a 3D
-object such as a *triangular mesh* or a *sphere*, whose data are user defined
-and can be updated at any time. A virtual environment is built by attaching one
-or several shapes to a *scene*. A scene can be *instantiated* into one or
-several shapes that can be then attached to a scene as any regular shapes. Each
-instance has its own position and orientation while the instantiated geometry
-is stored once even though it is instantiated several times. This feature can
-thus be used to create extremely complex environment with a low memory
-footprint.
-
-To query the scene data one has to create a *view* of the scene. On its
-creation, the view internally builds data structures required by the
-aforementioned access operators. These data structures are built from the scene
-geometry as defined at the moment of the view creation; a view is thus
-insensitive to scene updates following its creation. This means that several
-views can be used to register different states of the same scene, giving to the
-caller a great flexibility to manage the scene data.
-
-Star-3D is currently used in several projects 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.
-
- * [High-Tune: RenDeRer](https://gitlab.com/meso-star/htrdr.git)
- * [Stardis-Solver](https://gitlab.com/meso-star/stardis-solver.git)
- * [Solstice-Solver](https://gitlab.com/meso-star/solstice-solver.git)
- * [Star-4V/S](https://gitlab.com/meso-star/star-4v_s.git)
- * [Star-GebhartFactor](https://gitlab.com/meso-star/star-gf.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.9.2 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.
-
-### 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_DIR>`, `<RSYS_DIR>` and `<EMBREE_DIR>`
-directories, where `<RCMAKE_DIR>`, `<RSYS_DIR>` and `<EMBREE_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 (Refer to the [CMake
-documentation](https://cmake.org/documentation) for further informations on
-CMake).
-
-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_DIR>;<RSYS_DIR>;<EMBREE_DIR>" \
- > -DCMAKE_INSTALL_PREFIX=<STAR3D_INSTALL_DIR> \
- > ../cmake
- ~/star-3d/build $ make && make test
- ~/star-3d/build $ make install
-
-with `<STAR3D_INSTALL_DIR>` the directory in which Star-3D is going to be
-installed.
-
-## Quick Start
-
-Once installed, the Star-3D library and its associated headers are deployed,
-providing the whole environment required to develop C/C++ applications with
-Star-3D. The `<STAR3D_INSTALL_DIR>/include/star/s3d.h` header defines the
-Star-3D Application Programming Interface (API). Refer to this
-[file](https://gitlab.com/meso-star/star-3d/blob/master/src/s3d.h) for the API
-reference documentation.
-
-A Star-3D [CMake
-package](https://cmake.org/cmake/help/v3.5/manual/cmake-packages.7.html) is
-also installed to facilitate the use of Star-3D in projects relying on the
-CMake build system. For instance, the following `CMakeLists.txt` file uses the
-Star-3D package to build an executable relying on the Star-3D library.
-
- project(my_project C)
-
- # Use the Star-3D CMake package
- find_package(Star3D REQUIRED)
- include_directories(${Star3D_INCLUDE_DIR})
-
- # Define the program to build
- add_executable(my_program main.c)
-
- # Link the program against Star-3D
- target_link_libraries(my_program Star3D)
-
-This `CMakeLists.txt` is then used to generate the target project as, for
-instance, on a GNU/Linux system:
-
- cmake -G "Unix Makefiles" -DCMAKE_PREFIX_PATH="<STAR3D_INSTALL_DIR>" <MY_PROJECT_DIR>
-
-with `<STAR3D_INSTALL_DIR>` the install directory of Star-3D and
-`<MY_PROJECT_DIR>` the location of the `CMakeLists.txt` file.
+surfacic object such as a *triangular mesh* or a *sphere*. Shape data is
+user-defined and can be updated at any time. The shapes are then attached to a
+*scene* where they can be queried. We point out that a scene can be
+*instantiated* once or several times in a new shape which can be attached to
+another scene like any other shape. Each instantiated scene has its own
+position and orientation while its geometry is stored once even if the scene is
+instantiated multiple times. This feature can thus be used to create an
+extremely complex environment with a small memory footprint.
+
+To query scene data, you need to create a *view* of the scene. A view is
+actually a scene on which accelerating data structures are built to accelerate
+the aforementioned access operators such as ray tracing. These data structures
+are constructed from the scene geometry as defined at the time of view
+creation. A view is thus insensitive to updates of the scene following its
+creation. This means that multiple views can be used to save different states
+of the same scene, giving the caller great flexibility in managing scene data.
+
+## Requirements
+
+A C99 compiler, POSIX Make, and the RSys and Embree header files and libraries.
+
+## Installation
+
+Edit config.mk as needed, then run:
+
+ make clean install
## Release notes
@@ -235,7 +149,9 @@ argument. For closest point queries, this range is from 0 to query radius.
## License
-Copyright (C) 2015-2021, 2023 |Méso|Star> (<contact@meso-star.com>). Star-3D is
-released under the CeCILLv2.1 license. You are welcome to redistribute it under
-certain conditions; refer to the COPYING files for details.
+Copyright (C) 2015-2021, 2023 |Méso|Star> (contact@meso-star.com)
+
+Star-3D is released under the CeCILLv2.1 license. You are welcome to
+redistribute it under certain conditions; refer to the COPYING files for
+details.
