Update readme

# 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 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:

```cmake

target_link_libraries(<target> PRIVATE csg)

```