diff --git a/Documentation/Install_Mac.md b/Documentation/Install_Mac.md index 5387a6f..b862b8b 100644 --- a/Documentation/Install_Mac.md +++ b/Documentation/Install_Mac.md @@ -18,22 +18,6 @@ Copy the PicoGK Example project from the disk image to your Documents folder (or Double click **on Install PicoGK.pkg** -You will get a warning that the installer package cannot be verified (our installers are not code-signed β€” yet). - -![](images/MacInstallerWarning.png) - -Go to System Settings and under **Privacy and Security** - -Make sure **App Store and identified developers** is enabled. Then click on **Open Anyway**. - - - -After entering your credentials, the following dialog pops up. - - - -Choose **Open** - The PicoGK Installer will open. diff --git a/Documentation/MacSecurity.md b/Documentation/MacSecurity.md deleted file mode 100644 index 5a5ac8a..0000000 --- a/Documentation/MacSecurity.md +++ /dev/null @@ -1,52 +0,0 @@ -# Mac Security Warnings - -Since we provide the installers as a convenience to this open source project, we have not signed them yet (we are working on this). - -As a result, you will be confronted with a number of security warnings. If you don't trust us, you can [always compile yourself.](Compiling_PicoGKRuntime.md) - -But if you **do** trust us, here is how to get it up an running on the Mac. - -There are two security warning scenarios: - -- Warning on first launch of a PicoGK project on your system -- [Warning when using the Installer package](#Warning-when-running-the-installer) - -## Warning at first launch - -When you run a PicoGK project for the first time, it may warn you that the developer of a number of libraries cannot be verified. These are dependencies of OpenVDB. The first library you will encounter is **liblzma.5.dylib** - - - -To trust this library, go to your **Privacy and Security** settings in System Preferences. - - - -Click on Allow Anyway and confirm with your credentials. When you restart, you may be asked if you really trust this library, and have to confirm again. - -PicoGK will then try to load the second library, so you will receive a message again, this time for **libzstd.1.dylib** - - - -Follow the same process, and you should be up and running. - -## Warning when running the installer - -You get a warning that the installer package cannot be verified (our installers are not code-signed). - - - -Go to System Settings and under **Privacy and Security** - -Make sure **App Store and identified developers** is enabled. Then click on **Open Anyway**. - - - - After entering your credentials, the following dialog pops up. - - - -Choose **Open** - -The PicoGK Installer will open. - - \ No newline at end of file diff --git a/Documentation/README.md b/Documentation/README.md index 3752933..0920b79 100644 --- a/Documentation/README.md +++ b/Documentation/README.md @@ -26,18 +26,18 @@ Generally speaking, your PicoGK projects will look like this: -/**PicoGK Example** (your project folder) +`/PicoGK Example` (your project folder) -- **Program.cs** (your main execution code) +- `Program.cs` (your main execution code) - ... other files (for example the Visual Studio project file) - - **/PicoGK** (contains the PicoGK submodule) - - **/ShapeKernel** (contains the LEAP71_ShapeKernel submodule) - - **/LatticeLibrary** (contains the LEAP71_Lattice submodule) + - `/PicoGK` (contains the PicoGK submodule) + - `/ShapeKernel` (contains the LEAP71_ShapeKernel submodule) + - `/LatticeLibrary` (contains the LEAP71_Lattice submodule) - ... other submodules -**Program.cs** contains the code that executes your program. The PicoGK subfolder contains the source code of the PicoGK library. Under the hood PicoGK's C# code calls the PicoGK C++ runtime library for the heavy lifting. As many functions as possible are implemented directly in C# code, to make it simple to understand what is actually going on. Feel free to step into all functions using the debugger. +`Program.cs` contains the code that executes your program. The PicoGK subfolder contains the source code of the PicoGK library. Under the hood PicoGK's C# code calls the PicoGK C++ runtime library for the heavy lifting. As many functions as possible are implemented directly in C# code, to make it simple to understand what is actually going on. Feel free to step into all functions using the debugger. -If you have installed PicoGK using the installer, it you already have an example project in your **Documents** folder named **PicoGK Example**, which is ready to run. +If you have installed PicoGK using the installer, it you already have an example project in your `Documents` folder named `PicoGK Example`, which is ready to run. ## Running your first PicoGK App @@ -46,7 +46,7 @@ Opening and running your first PicoGK app looks a bit different between VisualSt - Running PicoGK Example on [VisualStudio](VisualStudio_FirstTime.md#Running-the-PicoGK-Example-Project) - Running PicoGK Example on [VisualStudio Code](VisualStudioCode_FirstTime.md#Opening-and-running-the-PicoGK-test-project-in-Visual-Studio-Code) -Open **Program.cs** and you will see the following code. +Open `Program.cs` and you will see the following code. ```c# try @@ -61,7 +61,7 @@ catch (Exception e) } ``` -Inside the **try** block is the call to the PicoGK Library to run the task **PicoGKExamples.BooleanShowCase.Task** with a voxel size 0.5mm. +Inside the `try` block is the call to the PicoGK Library to run the task `PicoGKExamples.BooleanShowCase.Task` with a voxel size 0.5mm. If something goes wrong in this task, an exception (an error) is thrown. The error will then be printed to the console output, so you can understand what went wrong. @@ -75,22 +75,26 @@ The example showcases a few boolean operations. You can browse to the [PicoGK/Examples/Ex_BooleanShowCase.cs](https://github.com/leap71/PicoGK/blob/main/Examples/Ex_BooleanShowCase.cs) file and check out the code. -On Mac, you will get a few **security warnings** that are a tedious, because our libraries are unsigned. [Here is how to solve this](MacSecurity.md). - What you have on screen is the **PicoGK Viewer**. You can click and drag in the viewer to rotate, scroll to zoom, and use the cursor keys to rotate by 15ΒΊ. The viewer may seem basic but has many powerful functions, including the ability to show objects in multiple colors, animate the view, save screenshots and even create timelapse animations. If you like to test this out, check out the the [PicoGKExamples.TimeLapseAnimation.Task](https://github.com/leap71/PicoGK/blob/main/Examples/Ex_TimelapseAnimation.cs). We have animated entire gear trains and other moving objects in the viewer. ## Creating your own app -One of the easiest ways to get set up, is to simply copy the example to a new directory and rename the project file. Alternatively, If you know how to use Git/GitHub, here are the steps to create a new app: +One of the easiest ways to get set up, is to simply copy the example to a new directory and rename the project file. + +Alternatively, If you know how to use Git/GitHub, here are the steps to create a new app: - [Create a new **C# Console Project**](VisualStudio_CreateConsole.md) and add it to Git - **Add PicoGK as submodule** using Git, and initialize it - Add [LEAP71_ShapeKernel](https://github.com/leap71/LEAP71_ShapeKernel) and other [modules](https://github.com/leap71?tab=repositories) as needed. -- In your Program.cs, call **Library.Go()** with the appropriate parameters +- In your `Program.cs`, call `Library.Go()` with the appropriate parameters + +> [!TIP] +> +> If you are comfortable with command line tools, here are [all the command line steps you need to take to create a new PicoGK project](Setup_PicoGK_Project_CommandLine.md). ## What's next? -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. +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. @@ -104,17 +108,9 @@ If you'd like to jump into the details of compiling and developing the [PicoGKRu ## Troubleshooting -### Cannot install on Mac, because of security warnings - -At this time, both our installers and our libraries are not signed. So macOS will refuse to run the installer. [You can solve this by following these steps.](MacSecurity.md) - -### First time I run on Mac, I get multiple security warnings - -Same as above, this is because our runtime libraries and their dependencies are not signed (yet). [Here's how to fix this.](MacSecurity.md) - ### PicoGK.log -PicoGK writes a detailed log of what is going on into **PicoGK.log**, which, by default, is located in your **Documents** folder. If you don't want us to spam your Documents folder, simply provide the path as the third parameter like this: +PicoGK writes a detailed log of what is going on into `PicoGK.log`, which, by default, is located in your `Documents` folder. If you don't want us to spam your `Documents` folder, simply provide the path as the third parameter like this: ```c# PicoGK.Library.Go(0.5f, PicoGKExamples.BooleanShowCase.Task, "/Users/username/Documents/LogMeHere"); @@ -134,7 +130,7 @@ If you installed from the installers, this should not happen. If you compiled yo -If your viewer looks like this, then the PicoGK Viewer did not find the textures for the image-based lighting environment. The most likely case is that your folder structure is different from what we described in the first steps of this document. **PicoGK Viewer assumes that PicoGK is in a subfolder named PicoGK** directly in your main project directory. If this isn't the case, it cannot find the file **PicoGK/ViewerEnvironment/PicoGKDefaultEnv.zip** and the scene is unlit. The easiest way to solve this is to follow the folder structure we described. Alternatively, you can provide a path to the ViewerEnvironment in a parameter to Library.Go. +If your viewer looks like this, then the PicoGK Viewer did not find the textures for the image-based lighting environment. The most likely case is that your folder structure is different from what we described in the first steps of this document. **PicoGK Viewer assumes that PicoGK is in a subfolder named `PicoGK`** directly in your main project directory. If this isn't the case, it cannot find the file `PicoGK/ViewerEnvironment/PicoGKDefaultEnv.zip` and the scene is unlit. The easiest way to solve this is to follow the folder structure we described. Alternatively, you can provide a path to the ViewerEnvironment in a parameter to Library.Go. ### Where can I get help diff --git a/Documentation/Setup_PicoGK_Project_CommandLine.md b/Documentation/Setup_PicoGK_Project_CommandLine.md new file mode 100644 index 0000000..aef27df --- /dev/null +++ b/Documentation/Setup_PicoGK_Project_CommandLine.md @@ -0,0 +1,71 @@ +# Using the Command Line tools to quickly set up a new PicoGK project + +## Overview + +The command line is the quickest way to set up a new project and clone the relevant GitHub submodules. + +You have to have the .NET framework installed, as well as Github command line tools. + +## Create a new C# console app + +Open terminal and go to the location of you Github root (for example `/user/myuser/Github`). + +Create a new .NET Console Project by using the following commands: + +``` +dotnet new console -n YourProjectName +``` + +## Add your project to Github + +Create an empty README.md file in the root of your folder so that Github can track your project (Github doesn't track empty folders). Then add the newly created folder to Github + +``` +touch README.md +git init +git add . +``` + +> [!NOTE] +> +> Don't forget the dot after `git add` + +## Add PicoGK and other submodules + +Change into the newly-created directory (your project's root) and add PicoGK, ShapeKernel and other submodules you want. + +``` +git submodule add https://github.com/leap71/PicoGK PicoGK +git submodule add https://github.com/leap71/LEAP71_ShapeKernel ShapeKernel +git submodule add https://github.com/leap71/LEAP71_LatticeLibrary LatticeLibrary +``` + +Then initialize the submodules and update them. + +``` +git submodule init +git submodule update --init --recursive +``` + +## Summary + +Here is it all in one block of script. Assuming you are at the root at your Github folder, such as Documents/Github. + +``` +dotnet new console -n YourProjectName +cd YourProjectName +touch README.md +git init +git add . +git submodule add https://github.com/leap71/PicoGK PicoGK +git submodule add https://github.com/leap71/LEAP71_ShapeKernel ShapeKernel +git submodule add https://github.com/leap71/LEAP71_LatticeLibrary LatticeLibrary +git submodule init +git submodule update --init --recursive +``` + +## .gitignore + +The last step you should to before you start working is add a `.gitignore` file to your project, as otherwise you will track a lot of files that are temporary. + +A good starting point is the one we use in PicoGK. You can either copy it from the PicoGK subfolder in your project, [or download it from here](https://github.com/leap71/PicoGK/blob/main/.gitignore). \ No newline at end of file diff --git a/Documentation/VisualStudioCode_FirstTime.md b/Documentation/VisualStudioCode_FirstTime.md index 6ff01f9..71caf1d 100644 --- a/Documentation/VisualStudioCode_FirstTime.md +++ b/Documentation/VisualStudioCode_FirstTime.md @@ -2,7 +2,7 @@ **Note** we show Mac screenshots. Windows is similar. -On Windows you [might want to consider using Visual Studio 2022](VisualStudio_FirstTime.md) and not Visual Studio Code. Visual Studio 2022 is the more comfortable development environment. +On Windows you [might want to consider using Visual Studio 2022](VisualStudio_FirstTime.md) and not Visual Studio Code. We think Visual Studio 2022 is the easier development environment. ## Install the .NET SDK from Microsoft @@ -62,9 +62,9 @@ A security warning pops up (whose purpose only Microsoft understands, since we a Unfold the folders on the left side. This is where project is organized. -Click on **Program.cs** β€” this is the main source file for your app. +Click on `Program.cs` β€” this is the main source file for your app. -In the default app, it just writes "Hello World" to the console output. With **Program.cs** selected, press the **Run and Debug** icon in the left toolbar. +In the default app, it just writes "Hello World" to the console output. With `Program.cs` selected, press the **Run and Debug** icon in the left toolbar. @@ -92,7 +92,7 @@ Choose **File->Open Folder** -Browse to the **PicoGK Example** project folder and open it. +Browse to the `PicoGK Example` project folder and open it. You will receive the warning again, whether you want to trust the authors of this folder, it's **yes** again. diff --git a/Documentation/VisualStudio_FirstTime.md b/Documentation/VisualStudio_FirstTime.md index 146e200..02b9efd 100644 --- a/Documentation/VisualStudio_FirstTime.md +++ b/Documentation/VisualStudio_FirstTime.md @@ -34,13 +34,13 @@ After you launched VisualStudio, you the welcome screen is shown. **Choose Open -Browse to where you installed the PicoGK demo project (default is **Documents/PicoGK Example**) +Browse to where you installed the PicoGK demo project (default is `Documents/PicoGK Example`) -Choose **PicoGK Example.vcproj** +Choose `PicoGK Example.vcproj` -The example project will open in Visual Studio. On the right side, you see your project files. **Program.cs** contains the main source code of the example. +The example project will open in Visual Studio. On the right side, you see your project files. `Program.cs` contains the main source code of the example. Click on Program.cs to show the source code.