Skip to content

setup.md

Latest commit

 

History

History
180 lines (139 loc) · 7.84 KB

setup.md

File metadata and controls

180 lines (139 loc) · 7.84 KB
Raw

Setup Guide

How to install PicoGK and run your first model on Windows or macOS.

Prerequisites

Requirement Version Notes
.NET SDK 9.0 or later The example project targets net9.0
Operating System Windows x64 or macOS arm64 Native runtime is bundled in the NuGet package for these platforms
Disk space ~500 MB For .NET SDK, NuGet cache, and PicoGK runtime

This fork commits the native binaries for win-x64 and osx-arm64 under runtime/native/, so there is no separate runtime install on those two platforms. (Upstream PicoGK ships them through the PicoGK NuGet package instead.) For Linux or other architectures you must build the PicoGKRuntime C++ library yourself and point src/PicoGK__Config.cs at it.

Install .NET 9 SDK

Windows (PowerShell):

winget install Microsoft.DotNet.SDK.9

macOS (Homebrew):

brew install --cask dotnet-sdk

Verify:

dotnet --version

Quick Start

Clone or open this repo, then from the repo root:

dotnet run --project examples\PicoGKExamples.csproj

The examples project builds against the local kernel source in src/ and loads the native runtime committed under runtime/native/, so no NuGet download of PicoGK is involved. The viewer window opens and runs whichever task is wired up in examples/Program.cs, currently GyroidCylinder.Task (a gyroid TPMS infill inside a loaded cylinder, voxel size 0.3 mm). An STL file is written to your log folder, by default C:\Users\<you>\ on Windows or ~/Documents/ on macOS and Linux. The PicoGK log file lands in the same folder.

Close the viewer window to exit.

Project Structure

PicoGK/
├── README.md
├── LICENSE                           Apache-2.0, unmodified
├── NOTICE                            Fork disclosure + third-party binary attribution
├── CHANGELOG.md                      How this fork diverges from upstream
├── .gitmodules                       Submodule manifest (vendor/ entries)
├── src/                              Kernel C# source
│   ├── PicoGK.csproj                 NuGet package source
│   ├── PicoGK_*.cs                   Public API (one file per topic area)
│   ├── PicoGK__Interop.cs            P/Invoke bindings to native runtime
│   └── PicoGK__Config.cs             Native library name / path
├── runtime/                          Bundled native binaries + viewer env
│   ├── native/win-x64/               .dll for Windows
│   ├── native/osx-arm64/             .dylib for macOS
│   └── ViewerEnvironment/            HDR environments (Default, SkyBlue, etc.)
├── examples/                         Your local examples project
│   ├── Program.cs                    Entry point, picks which Task() to run
│   ├── PicoGKExamples.csproj
│   ├── PicoGK_Examples.sln
│   └── 01_GettingStarted/
├── projects/                         Your own build projects go here
├── vendor/                           Submodules, every leap71 repo (see docs/vendor.md)
│   ├── PicoGKRuntime/                C++ native runtime source
│   ├── PicoGKInstaller/              Non-NuGet install scripts
│   ├── PicoGK_Examples/              Upstream reference examples
│   ├── PicoGKUnitTests/              Regression tests
│   ├── PicoGK_SimulationExample/     Simulation coupling example
│   ├── LEAP71_ShapeKernel/           Higher-level primitives + lofts + airfoils
│   ├── LEAP71_LatticeLibrary/        TPMS / gyroid / strut lattices
│   ├── LEAP71_HelixHeatX/            Helical heat exchanger reference
│   ├── LEAP71_RoverWheel/            Rover wheel reference
│   └── LEAP71_QuasiCrystals/         Quasicrystal lattice generator
└── docs/                             This documentation

After cloning, populate the submodules:

git submodule update --init --recursive

Or clone with --recursive from the start:

git clone --recursive https://github.com/<your-fork>/PicoGK.git

Your First Model

Create a new file under examples/01_GettingStarted/MyFirstModel.cs:

using PicoGK;
using System.Numerics;

namespace PicoGKExamples
{
    class MyFirstModel
    {
        public static void Task()
        {
            Voxels body = Voxels.voxSphere(Vector3.Zero, 30f);
            Voxels hole = Voxels.voxSphere(Vector3.Zero, 25f);
            Voxels shell = body - hole;

            Library.oViewer().Add(shell);

            Mesh msh = new Mesh(shell);
            msh.SaveToStlFile(Path.Combine(Library.strLogFolder, "MyFirstModel.stl"));
        }
    }
}

Edit examples/Program.cs to point at your task:

Library.Go(0.5f, MyFirstModel.Task);

Run it:

dotnet run --project examples\PicoGKExamples.csproj

Library.Go: the entry point

Every PicoGK program calls Library.Go(voxelSize, taskFn) exactly once. It:

  1. Loads the native runtime
  2. Initializes log file in strLogFolder
  3. Creates the singleton viewer
  4. Spawns a worker thread and runs your Task() inside it
  5. Pumps the viewer's main loop on the original thread
  6. Exits when you close the viewer

Voxel size is in millimetres and is global. Smaller = finer detail + more memory. Typical values:

  • 1.0f: fast, low-resolution previews
  • 0.5f: default for most parts
  • 0.3f: printable detail at typical FDM nozzle scale
  • 0.1f: very high resolution, expect minutes per operation on large parts

Building against the local source

examples/PicoGKExamples.csproj already references the kernel by project, not by NuGet package:

<ItemGroup>
  <ProjectReference Include="..\src\PicoGK.csproj" />
</ItemGroup>

That is deliberate in this fork: it is what lets a local edit to the C# kernel source rebuild straight into your examples, and it is how ANVIL consumes this repository from a sibling checkout. The native runtime loads from runtime/native/ via the library name in src/PicoGK__Config.cs.

To use the official upstream package instead, swap the <ProjectReference> for <PackageReference Include="PicoGK" Version="..." />. Note that the upstream package is on the 2.x line while this fork sits on 1.7.7.5, so the APIs may not match.

Troubleshooting

Symptom Cause Fix
DllNotFoundException: picogk.1.7 Native runtime missing On Linux: build PicoGKRuntime. On Win/macOS: re-restore NuGet packages.
Viewer opens, immediately closes Task() threw an exception Check console / log file in Documents\PicoGK\Logs\
Out of memory on new Mesh(vox) Voxel size too small for part Increase voxel size, or trim the bounding box first
"Could not load file or assembly" on macOS Wrong architecture (x86_64 vs arm64) Confirm you're on Apple Silicon; Intel Macs are not supported by the bundled runtime
Can't find the STL output Default Library.strLogFolder is user home on Windows (C:\Users\<you>), ~/Documents on Unix Pass an explicit strLogFolder to Library.Go(...) if you want a specific folder

Next steps