Initial Release

leap71 · Oct 17, 2023 · 354a34b · 354a34b
commit 354a34b
Show file tree

Hide file tree

Showing 57 changed files with 8,829 additions and 0 deletions.
diff --git a/.gitignore b/.gitignore
diff --git a/Documentation/Compiling_PicoGKRuntime.md b/Documentation/Compiling_PicoGKRuntime.md
@@ -0,0 +1,68 @@
+# Compiling the PicoGK Runtime
+
+We compiled and tested PicoGKRuntime on Windows 64 bit and MacOS 14 Sonoma. Since Mac is our primary work environnment, we have tested it on Mac significantly more than on Windows. There is, however, nothing fundamentally platform-specific about PicoGK. The main platform dependencies are well-established libraries like OpenVDB. Our code is very straightforward and mostly header-only C++ code.
+
+## What you need
+
+On Windows, you need **Visual Studio 2022 Community Edition** (or higher) with C++ support installed (bare bones C++ is enough).
+
+On Mac, you need the latest version of **XCode** with C++ support, and the XCode command line tools.
+
+In addition you need a current version of **CMake** (Download at https://cmake.org/) 
+
+## Installing dependent libraries
+
+First clone the **PicoGKRuntime** repository to your machine. 
+
+Make sure to initialize the submodules (**git submodule update --init --recursive**), so that the OpenVDB submodule is properly initialized.
+
+PicoGKRuntime has no dependencies besides **OpenVDB** and **GLFW** (which is fetched automatically), but those libraries have plenty of dependencies (boost, blosc, etc).
+
+To facilitate the installation of these dependencies, we have provided you with two scripts that download and install everything needed.
+
+On Mac, please run **PicoGKRuntime/Install_Dependencies/Mac.sh**
+
+On Windows, please run **PicoGKRuntime/Install_Dependencies/Win.bat** 
+Note: you may have to run Win.bat twice, due to a bug we haven't found yet. It works after the second time.
+
+The installation of the dependencies may take a while, especially on Windows.
+
+After you have done this, you can move onto compiling the PicoGK Runtime.
+
+## Preparing the PicoGK Runtime Build Environment
+
+Start the CMake GUI client and specify the path to the PicoGKRuntime repository in **"Where is the source code"**.
+
+Specify the Build subfolder under **"Where to build the libraries"**. It should like this
+
+<img src="images/image-20231017134154856.png" alt="image-20231017134154856" style="zoom:50%;" />
+
+Hit **Configure** and accept all defaults. After Configure has run without errors, click **Generate**.
+
+Note: On Mac, we advise to use "Unix Makefiles" as target. If you target XCode, you will get an error in the OpenVDB CMake setup. We have reached out to the OpenVDB team why this happens. You can safely comment out the offending lines in the OpenVDB CMake files, but this should not happen and it seems like an issue on their side.
+
+Now you can compile PicoGKRuntime on your system.
+
+## Compiling
+
+On Mac, go to the **Build** subdirectory in **Terminal** and type **make** [enter] to run the make tool. The build process should start and you will get the compiled picogk.1.0.dylib in the Dist subfolder of PicoGKRuntime.
+
+On Windows, open the resulting project in Visual Studio and compile (use the release version).
+
+## Using the compiled Runtime
+
+You either copy the resulting library to /usr/local/lib on Mac or the System32 folder on Windows (or any other folder that is in your system path).
+
+A cleaner way, when you are still testing is to modify the path in the PicoGK C# library. You do this by opening PicoGK__Config.cs and pointing the path to your compiled library:
+
+<img src="images/image-20231014185209784.png" alt="image-20231017164620416" style="zoom:50%;" />
+
+One last thing — on Mac, you may have to sign the library using the **codesign** tool. Otherwise the library may not load. 
+
+## Code signing on the Mac
+
+The necessary command line is **codesign -s LEAP71 picogk.1.0.dylib** — you need to have a valid code signing certificate for this (we used one we named LEAP71 — you can self issue this certificate, but it's a few steps).
+
+Here is a relevant Apple article how to create self-signed certificates: https://support.apple.com/en-ae/guide/keychain-access/kyca8916/mac
+
+[You may have to adjust your security settings as described here.](../Runtime/readme.md)
diff --git a/Documentation/README.md b/Documentation/README.md
@@ -0,0 +1,58 @@
+# PicoGK Documentation
+
+![PicoGKSketched](images/PicoGKSketched.jpg)
+
+## Getting Started
+
+**PicoGK is available and tested on MacOS X at this time. A Windows release will follow in the coming weeks.**
+
+As a Computational Engineer, you write code to create sophisticated geometry. If you don't know how to code, there are many good tutorials available online. 
+
+PicoGK uses the C# language, a modern, fast, expressive and strongly-typed language that allow you to build complex algorithms using a simple syntax. If you are new to coding, don't despair! We have tried to make it as simple as possible to get started.
+
+To install PicoGK, [follow this link](installation.md) for installation instructions.
+
+Now let's dive in.
+
+## Your first PicoGK App
+
+For experts, here are the quick steps: In your **Program.cs** you call **PicoGK.Library.Go** with the voxel size and the task you want to execute. There are many example tasks in the **Examples** subfolder of the PicoGK repository.
+
+**For detailed steps, read on.**
+
+We assume you have followed the [Installation Guide](installation.md) and have created an empty Console application in Visual Studio.
+
+Open your Visual Studio project. **Program.cs** should already be open.
+
+It should look something like this
+
+<img src="images/image-20231014161615187.png" alt="image-20231014161615187" style="zoom:50%;" />
+
+Replace the text there with the following:
+
+```c#
+PicoGK.Library.Go(  0.5f, 
+                  	PicoGKExamples.BooleanShowCase.Task);
+```
+
+<img src="images/image-20231014184822502.png" alt="image-20231014184822502" style="zoom:50%;" />
+
+And run it.
+
+![image-20231014184919894](images/image-20231014184919894.png)If everything is right, a window will open, showing you a few spheres that are combined using Boolean operations. You can click and drag in the viewer to rotate, scroll to zoom, and use the cursor keys to rotate by 15º. The viewer is basic but functional.
+
+If you are not seeing this window, you can check out the console window at the bottom of Visual Studio to see any error messages. These messages are also written to **PicoGK.log** in your Documents folder (you can change the location if you don't like that). One thing you may have to do on Mac is adjust the security settings, so PicoGK can load the pre-compiled PicoGKRuntime. [If you want to compile it yourself, here are the instructions](Compiling_PicoGKRuntime.md).
+
+[Drop us a note in the discussion section of this repository](https://github.com/leap71/PicoGK/discussions), if you have any issues, and we will do our best to help. The most common problem is that the PicoGK Runtime library cannot be found. Double check if you copied it to the right system folder.
+
+Congratulations, you can now code in PicoGK!
+
+Check out the other examples from the Examples subdirectory of PicoGK. A fun way to work your way through is by simply typing a dot behind the PicoGKExamples namespace ID, as below, and you will see all the options. Just don't forget to add "Task" at the end.
+
+If you dive into the code, you will see that it's super simple to create interesting things, even with the basic PicoGK functions.
+
+<img src="images/image-20231014185209784.png" alt="image-20231014185209784" style="zoom:50%;" />
+
+If you want to seriously dive in, [you should work using the LEAP 71 Shape Kernel.](https://github.com/leap71/ShapeKernel) and build your [Computational Engineering Models](https://leap71.com/computationalengineering/) on top.
+
+If you'd like to dive into the details of compiling and developing the [PicoGKRuntime, you will find a setup guide here](Compiling_PicoGKRuntime.md).
diff --git a/Documentation/images/9CF66413-8BA1-4E18-9BA7-F5254235B44A.jpeg b/Documentation/images/9CF66413-8BA1-4E18-9BA7-F5254235B44A.jpeg
diff --git a/Documentation/images/PicoGKSketched.jpg b/Documentation/images/PicoGKSketched.jpg
diff --git a/Documentation/images/image-20231014161615187.png b/Documentation/images/image-20231014161615187.png
diff --git a/Documentation/images/image-20231014182542392.png b/Documentation/images/image-20231014182542392.png
diff --git a/Documentation/images/image-20231014183009658.png b/Documentation/images/image-20231014183009658.png
diff --git a/Documentation/images/image-20231014183143914.png b/Documentation/images/image-20231014183143914.png
diff --git a/Documentation/images/image-20231014183312778.png b/Documentation/images/image-20231014183312778.png
diff --git a/Documentation/images/image-20231014184436833.png b/Documentation/images/image-20231014184436833.png
diff --git a/Documentation/images/image-20231014184822502.png b/Documentation/images/image-20231014184822502.png
diff --git a/Documentation/images/image-20231014184919894.png b/Documentation/images/image-20231014184919894.png
diff --git a/Documentation/images/image-20231014185209784.png b/Documentation/images/image-20231014185209784.png
diff --git a/Documentation/images/image-20231017134154856.png b/Documentation/images/image-20231017134154856.png
diff --git a/Documentation/images/image-20231017180157568.png b/Documentation/images/image-20231017180157568.png
diff --git a/Documentation/images/image-20231017180729775.png b/Documentation/images/image-20231017180729775.png
diff --git a/Documentation/installation.md b/Documentation/installation.md
@@ -0,0 +1,57 @@
+# PicoGK Installation
+
+## If you have used C# and Github before
+
+- Create a new **C# Console** application project using the latest version of Microsoft Visual Studio
+
+- Create a new repository for your project using **git**.
+
+- Add the **[PicoGK repository](https://github.com/leap71/PicoGK)** as a submodule and initialize it.
+- Go into the **PicoGK** submodule folder, and navigate to the subfolder **Runtime**
+- If you are on Mac, copy the **.dylib** file you see there to **/usr/local/lib**
+- If you are on Windows, copy the **.dll** file to **C:\SYSTEM32**
+- If you don't want to pollute these directories, you can change the path to the PicoGK Runtime in PicoGK__Config.c#
+
+Return to the [Getting Started](README.md) page to see how to run your first PicoGK app.
+
+## Beginner's Installation Guide
+
+PicoGK uses C#, a modern and elegant language, that can be learned quickly, but has powerful features. In order to use C#, you have to install Microsoft Visual Studio for either Mac or Windows. 
+
+- If you are on Mac, [you can download it here.](https://visualstudio.microsoft.com/vs/mac/)
+- If you are on Windows, [you can download it here.](https://visualstudio.microsoft.com/vs/community/)
+
+When installing, make sure you enable C# support and desktop app development. You don't need anything else.
+
+Open Visual Studio, and create a new "Console" application. 
+
+We are showing Mac screenshots, Windows looks similar.
+
+<img src="images/image-20231014182542392.png" alt="image-20231014182542392" style="zoom:50%;" />
+
+Click continue until you have to give your project a name.
+
+<img src="images/image-20231014183009658.png" alt="image-20231014183009658" style="zoom:50%;" />
+
+Click **Create**.
+
+Your screen should look like this or similar. Click on the run button to compile and run your program.
+
+<img src="images/image-20231014183143914.png" alt="image-20231014183143914" style="zoom:50%;" />
+
+You will see something like that in the console output at the bottom. Congratulations, you have run your first C# program.
+
+<img src="images/image-20231014183312778.png" alt="image-20231014183312778" style="zoom:50%;" />
+
+Now, let's install the PicoGK library.
+
+- Download [the ZIP from this link](https://github.com/leap71/PicoGK/archive/refs/heads/main.zip), which is the PicoGK library.
+- Copy the ZIP to the folder which contains Program.cs (in the project you just created)
+- Unzip it. Now your folder should contain Program.cs, and a subfolder named PicoGK
+- Go into the PicoGK folder, and navigate to the subfolder Runtime
+- If you are on Mac, copy the **.dylib** files you see there to /usr/local/lib
+- If you are on Windows, copy the **.dll** files to C:\SYSTEM32
+
+Now you are all set and can write your first PicoGK application. 
+
+Return to the [Getting Started](README.md#your-first-picogk-app) page to see how to run your first PicoGK app.
diff --git a/Examples/Ex_BooleanShowCase.cs b/Examples/Ex_BooleanShowCase.cs
@@ -0,0 +1,123 @@
+//
+// SPDX-License-Identifier: CC0-1.0
+//
+// This example code file is released to the public under Creative Commons CC0.
+// See https://creativecommons.org/publicdomain/zero/1.0/legalcode
+//
+// To the extent possible under law, LEAP 71 has waived all copyright and
+// related or neighboring rights to this PicoGK example code file.
+//
+// THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS
+// OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+// FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+// AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+// LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+// OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+// THE SOFTWARE.
+//
+
+using PicoGK;
+using System.Numerics;
+
+namespace PicoGKExamples
+{
+    ///////////////////////////////////////////////////////////////////////////
+    // Below is a static class that implements a single static function
+    // that can be called from Library::Go()
+
+    class BooleanShowCase
+    {
+        public class Sphere : IImplicit
+        {
+            public Sphere(  float fRadius,
+                            Vector3 vecCenter)
+            {
+                m_fRadius   = fRadius;
+                m_vecC      = vecCenter;
+                oBB = new BBox3(    vecCenter - new Vector3(fRadius),
+                                    vecCenter + new Vector3(fRadius));
+            }
+
+            public float fSignedDistance(in Vector3 vecSample)
+            {
+                Vector3 vecPt = vecSample - m_vecC;
+                // Move sample point to origin by subtracting center
+
+                return float.Sqrt(  vecPt.X * vecPt.X +
+                                    vecPt.Y * vecPt.Y +
+                                    vecPt.Z * vecPt.Z) - m_fRadius;
+            }
+
+            public readonly BBox3   oBB;
+            float   m_fRadius;
+            Vector3 m_vecC;
+        }
+
+        public static void Task()
+        {
+            try
+            {
+                Library.oViewer().SetGroupMaterial(0, "EE", 0f, 1f);
+
+                Library.oViewer().SetGroupMaterial(1, "FF000033", 0f, 1f);
+                // Transparent Red
+
+                Library.oViewer().SetGroupMaterial(2, "00FF0033", 0f, 1f);
+                // Transparent Green
+
+                Sphere oSphere1A = new Sphere(20f, new Vector3(-5f, 0, 0));
+                Sphere oSphere1B = new Sphere(20f, new Vector3(5f, 0, 0));
+
+                // Boolean Add showcase
+
+                Voxels vox1 = new Voxels(oSphere1A, oSphere1A.oBB);
+                vox1.BoolAdd(new Voxels(oSphere1B, oSphere1B.oBB));
+                Library.oViewer().Add(vox1);
+
+                Sphere oSphere2A = new Sphere(20f, new Vector3(-5f + 90, 0, 0));
+                Sphere oSphere2B = new Sphere(20f, new Vector3(5f + 90, 0, 0));
+
+                // Boolean Subtract showcase
+
+                Voxels vox2A    = new Voxels(oSphere2A, oSphere2A.oBB);
+                Voxels vox2B    = new Voxels(oSphere2B, oSphere2B.oBB);
+
+                vox2A.BoolSubtract(vox2B);
+
+                Library.oViewer().Add(vox2A);
+                Library.oViewer().Add(vox2B, 1);
+
+                // Boolean Intersect showcase
+
+                Sphere oSphere3A = new Sphere(20f, new Vector3(-5f + 180, 0, 0));
+                Sphere oSphere3B = new Sphere(20f, new Vector3(5f + 180, 0, 0));
+
+                Voxels vox3A    = new Voxels(oSphere3A, oSphere3A.oBB);
+                Voxels vox3B    = new Voxels(oSphere3B, oSphere3B.oBB);
+                Voxels vox3     = new Voxels(vox3A);
+
+                vox3.BoolIntersect(vox3B);
+
+                Library.oViewer().Add(vox3);
+                Library.oViewer().Add(vox3A, 2);
+                Library.oViewer().Add(vox3B, 2);
+
+                Voxels vox = new Voxels();
+
+                vox.BoolAdd(vox3);
+                vox.BoolAdd(vox2A);
+                vox.BoolAdd(vox1);
+
+                Mesh msh = new Mesh(vox);
+                msh.SaveToStlFile(  Path.Combine(Library.strLogFolder,
+                                    "Booleans.stl"));
+            }
+
+            catch (Exception e)
+            {
+                Library.Log($"Failed run example: \n{e.Message}"); ;
+            }
+        }
+    }
+}
+
diff --git a/Examples/Ex_BooleanTwoMeshCubes.cs b/Examples/Ex_BooleanTwoMeshCubes.cs
@@ -0,0 +1,74 @@
+//
+// SPDX-License-Identifier: CC0-1.0
+//
+// This example code file is released to the public under Creative Commons CC0.
+// See https://creativecommons.org/publicdomain/zero/1.0/legalcode
+//
+// To the extent possible under law, LEAP 71 has waived all copyright and
+// related or neighboring rights to this PicoGK example code file.
+//
+// THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS
+// OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+// FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+// AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+// LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+// OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+// THE SOFTWARE.
+//
+
+using PicoGK;
+using System.Diagnostics;
+using System.Numerics;
+
+namespace PicoGKExamples
+{
+    ///////////////////////////////////////////////////////////////////////////
+    // Below is a static class that implements a single static function
+    // that can be called from Library::Go()
+
+    class BooleanTwoMeshCubes
+    {
+        public static void Task()
+        {
+            try
+            {
+                // Create a 100mm cube at the origin
+                Mesh mshCube1 = Utils.mshCreateCube(new Vector3(100.0f));
+
+                // Create a 50mm cube offset 30mm diagonally
+                Mesh mshCube2 = Utils.mshCreateCube(    new Vector3(50.0f),
+                                                        new Vector3(30f));
+
+                // Render both objects into voxel fields
+                Voxels voxCube1 = new Voxels(mshCube1);
+                Voxels voxCube2 = new Voxels(mshCube2);
+
+                // Subtract (cut away), voxCube2 from voxCube1
+                voxCube1.BoolSubtract(voxCube2);
+
+                // Make a copy of the resulting object
+                Voxels voxShell = new(voxCube1);
+
+                // Offset by 2mm
+                voxShell.Offset(2f);
+
+                // Cut out voxCube1 to create a shell
+                voxShell.BoolSubtract(voxCube1);
+
+                // Subtract Cube2 again to expose the inside of the shell
+                voxShell.BoolSubtract(voxCube2); 
+
+                // Add result to viewer
+                Library.oViewer().Add(voxShell);
+
+                voxShell.mshAsMesh().SaveToStlFile(
+                    Path.Combine(Library.strLogFolder, "Shell.stl"));
+            }
+
+            catch (Exception e)
+            {
+                Library.Log($"Failed run example: \n{e.Message}"); ;
+            }
+        }
+    }
+}