Skip to content
Snippets Groups Projects
Commit 81ff93fc authored by Mark Meredith's avatar Mark Meredith
Browse files

Update readme

parent adb4d2cb
No related branches found
No related tags found
1 merge request!55Update readme
Pipeline #22452 passed
# csg-eb
# CSG-EB
Library for parsing [Constructive Solid Geometry (CSG)
files](https://github.com/openscad/openscad/wiki/CSG-File-Format) into an
implicit function that can be used to define [Embedded Boundaries
This library is for parsing [Constructive Solid Geometry
(CSG)](https://github.com/openscad/openscad/wiki/CSG-File-Format) for use in
[AMReX Embedded Boundaries
(EB)](https://amrex-codes.github.io/amrex/docs_html/EB.html).
Uses PEGTL for parsing and Catch2 for tests.
CSG is a file format used by the open source CAD modelling tool
[OpenSCAD](https://www.openscad.org). CSG is a subset of the SCAD language,
equivalent in the kinds of geometries that can be expressed, but with fewer
primitives (OpenSCAD can export `.scad` files to `.csg`). SCAD code is easier to
read and write by humans; CSG files are easier to parse and process by software.
Dependencies:
## Build
- [PEGTL](https://github.com/taocpp/PEGTL) for parsing
- [Catch2](https://github.com/catchorg/Catch2) for testing framework
- [CGAL](https://www.cgal.org) for geometry computation
> :warning: **Requires C++17, such as GCC 7.x or later, or Clang 5.x or later**.
### CMake
#### Installing conan for the first time
## How to Build
python3 -m pip install conan
### Build dependencies
#### Building using CMake
- C++17 compiler (GCC >=7.x, Clang >=5.x)
- CMake >=3.14
- Conan (CMake will try to install Conan if `conan` is not in `PATH`)
cmake -S . -B build -DCMAKE_BUILD_TYPE=Release
cmake --build build --target unit_tests_csg
cd build
make -j
CMake will try to install [Conan](https://conan.io) if `conan` is not in `PATH`.
However, installing Conan (`pip install conan`) is recommended for faster builds.
#### Running unit tests
#### Build
ctest
```shell
> cmake -S . -B build -DCMAKE_BUILD_TYPE=Release
> cmake --build build
```
#### Run tests
## Using the library in other projects
```shell
> cd build
> ctest
```
### Include in the code
* Include the header file
#include "csg.hpp"
## Using CSG-EB in your project
* Create a function object
- Include the header file `csg.hpp`
- Call `csg::get_csgif` with the path to a CSG file to create an [Implicit Function object](https://amrex-codes.github.io/amrex/docs_html/EB.html#implicit-function).
auto csg_if = csg::get_csgif(<path_to_file_with_csg_extension>, is_internal_flow);
```cpp
#include <csg.hpp>
* Above returns an implicit function which can be operated on a 3D point coordinate (x, y, z) as
// for EB2::makeShop
#include <AMReX_EB2_GeometryShop.H>
csg_if(x, y, z)
...
* Can be passed to amrex EB2::makeShop
auto gshop = EB2::makeShop(*csg_if);
auto csg_file = "~/my_geometry.csg";
auto is_internal_flow = true;
auto csg_if = csg::get_csgif(csg_file, is_internal_flow);
auto gshop = EB2::makeShop(*csg_if);
```
### Note on the return value
* If `internal_flow` is set to `true`
- **csg_if(x, y, z)** returns a number `less than 0`, if (x, y, z) lies `inside` the CSG object (a hollow)
- **csg_if(x, y, z)** returns a number `greater than 0`, if (x, y, z) lies `outside` the CSG object (a hollow)
* If `internal_flow` is set to `false`
- **csg_if(x, y, z)** returns a number `greater than 0`, if (x, y, z) lies `inside` the CSG object (a solid)
- **csg_if(x, y, z)** returns a number `less than 0`, if (x, y, z) lies `outside` the CSG object (a solid)
If `is_internal_flow==true`, the CSG geometry defines a hollow space for the domain:
- csg_if(x, y, z) < 0 ⇒ (x, y, z) is **INSIDE**
- csg_if(x, y, z) > 0 ⇒ (x, y, z) is **OUTSIDE**
If `is_internal_flow==false`, the CSG geometry defines a solid boundary to the domain:
- csg_if(x, y, z) < 0 ⇒ (x, y, z) is **OUTSIDE**
- csg_if(x, y, z) > 0 ⇒ (x, y, z) is **INSIDE**
### Add to the CMake build
* Add this repo as a git submodule
* Build by adding as subdirectory in appropriate CMake file
add_subdirectory(<path-to-submodule>)
* Add this repo as a CMake subdirectory in your `CMakeLists.txt`:
```cmake
add_subdirectory(/path/to/repo/csg-eb)
```
* Link by setting the dependency in appropriate CMake file
* Add the `csg` target to the CMake target that uses code like in the the above example:
target_link_libraries(<target> PRIVATE csg)
```cmake
target_link_libraries(<target> PRIVATE csg)
```
0% Loading or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment