Skip to content
README.md 2.74 KiB
Newer Older
Mark Meredith's avatar
Mark Meredith committed
# CSG-EB
Mark Meredith's avatar
Mark Meredith committed

Mark Meredith's avatar
Mark Meredith committed
This library is for parsing [Constructive Solid Geometry
(CSG)](https://github.com/openscad/openscad/wiki/CSG-File-Format) for use in
[AMReX Embedded Boundaries
Mark Meredith's avatar
Mark Meredith committed
(EB)](https://amrex-codes.github.io/amrex/docs_html/EB.html).
Mark Meredith's avatar
Mark Meredith committed
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.
Mark Meredith's avatar
Mark Meredith committed
Dependencies:
Mark Meredith's avatar
Mark Meredith committed
 - [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
Mark Meredith's avatar
Mark Meredith committed
## How to Build
Deepak Rangarajan's avatar
Deepak Rangarajan committed

Mark Meredith's avatar
Mark Meredith committed
### Build dependencies
Mark Meredith's avatar
Mark Meredith committed

Mark Meredith's avatar
Mark Meredith committed
 - C++17 compiler (GCC >=7.x, Clang >=5.x)
 - CMake >=3.14
Deepak Rangarajan's avatar
Deepak Rangarajan committed

Mark Meredith's avatar
Mark Meredith committed
```shell
> cmake -S . -B build -DCMAKE_BUILD_TYPE=Release
> cmake --build build
```
Mark Meredith's avatar
Mark Meredith committed

Mark Meredith's avatar
Mark Meredith committed
#### Run tests
Deepak Rangarajan's avatar
Deepak Rangarajan committed

Mark Meredith's avatar
Mark Meredith committed
```shell
> cd build
> ctest
```
Mark Meredith's avatar
Mark Meredith committed
## Using CSG-EB in your project
Deepak Rangarajan's avatar
Deepak Rangarajan committed

Mark Meredith's avatar
Mark Meredith committed
 - 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).
Deepak Rangarajan's avatar
Deepak Rangarajan committed

Mark Meredith's avatar
Mark Meredith committed
```cpp
#include <csg.hpp>
Mark Meredith's avatar
Mark Meredith committed

Mark Meredith's avatar
Mark Meredith committed
// for EB2::makeShop
#include <AMReX_EB2_GeometryShop.H>
Deepak Rangarajan's avatar
Deepak Rangarajan committed

Mark Meredith's avatar
Mark Meredith committed
...
Mark Meredith's avatar
Mark Meredith committed
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);

```
Mark Meredith's avatar
Mark Meredith committed

Deepak Rangarajan's avatar
Deepak Rangarajan committed

### Note on the return value
Mark Meredith's avatar
Mark Meredith committed

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**

Deepak Rangarajan's avatar
Deepak Rangarajan committed

### Add to the CMake build

Mark Meredith's avatar
Mark Meredith committed
* Add this repo as a CMake subdirectory in your `CMakeLists.txt`:

```cmake
add_subdirectory(/path/to/repo/csg-eb)
```
Mark Meredith's avatar
Mark Meredith committed

Mark Meredith's avatar
Mark Meredith committed
* Add the `csg` target to the CMake target that uses code like in the the above example:
Deepak Rangarajan's avatar
Deepak Rangarajan committed

Mark Meredith's avatar
Mark Meredith committed
```cmake
target_link_libraries(<target> PRIVATE csg)
```
Mark Meredith's avatar
Mark Meredith committed

## Install with Spack

Another way to install csg-eb is with Spack.  See the [Spack documentation](https://spack.readthedocs.io) for instructions on how to install Spack.


Then define a recipe for csg-eb:
``` shell
spack repo add .spack/repo  # add repo with csg-eb recipe
spack spec csg-eb           # preview install
spack install csg-eb        # install csg-eb (with CGAL support)
spack install csg-eb ~cgal  # install csg-eb (without CGAL support)
spack load csg-eb           # Adds directory with libcsg-eb.a  to LD_LIBRARY_PATH
```