The most adaptable generator for ergonomic mechanical keyboards there is.
Cosmos is released under an open-core model. 95% of the generator is free and open-source. Pro features (rounded edges, the stilts model, and wrist rests) are not.
Everything from here on is fairly technical. If you can't program but know CAD, read this tutorial to learn how you can help improve (or reference) the generator's models.
Most generator code lives at src/lib andsrc/routes/beta. Some files used for pre-generating STEP & GLB files used in the generator are located at src/model_gen.
To run the generator locally, you have two options:
-
Manual Setup:
- Clone the repository and install Bun.
The rationale is that Bun has built-in TypeScript and path mapping support. Alternatively, you can use Node.js v21 or later (nvm recommended for Linux users). When using Node.js, Cosmos uses a custom ESM loader, which is more difficult to debug when things ultimately go wrong.
- Run
make quickstartto compile and build the necessary files. - Read the dev documentation if you wish to compile the docs or create a production build.
- Finally, run
make devto start a dev server and visithttp://localhost:5173/beta.
- Clone the repository and install Bun.
-
Docker Setup (Recommended for Windows†):
- Clone the repository and install Docker and Docker compose.
- Run
docker compose upin the project root directory.- To avoid running the make scripts when rebuilding, set
SKIP_MAKE_FILES=truein your .env file. This reduces build time if all target files and docs have already been created.
- To avoid running the make scripts when rebuilding, set
† Docker is recommended on Windows since you'll need make and a ideally Linux shell. You can alternatively use make in Cygwin, install make, or piece together what you need to run from the Makefile :)
I recommend you first follow the steps above to run the generator locally so that you can test your changes. If you're interested in:
- Adding support for new parts (such as a display or trackball)
- Adding a new microcontroller to the generator
Then follow the instructions in the documentation (source is in docs/docs) for complete guide on how to do this.
Otherwise if you're looking to change how the generated keyboards look, the three files you'll be interested in are:
Rendering in Cosmos is split into two parts: geometrical calculations (which determines where parts go), and modeling operations (building the 3d model in OpenCascade). The files geometry.ts and cachedGeometry.ts perform those geometrical calculations (with the latter acting as a higher-level wrapper over functions in the former), and model.ts is responsible for all 3d modeling operations.
All code is licensed under the AGPL-3.0 license. All STEP models under the src/assets folder are licensed under the CC0 License. All other assets and images are copyrighted and may not be reused without permission.
The code is at src/routes/scan. Most of the processing happens in lib/hand.ts.
Please feel free to use either GitHub or Discord for submitting issues.
I'm planning on building out an API to make it easy for users to share their scanned hand data with other keyboard-related websites. If you maintain a keyboard-related site and are interested in adding a way for visitors to quickly see how your keyboard fits their hand, send me an email to ryan at ryanis .cool. You can of course use this code to build out your own hand scanning solution, provided you abide by the terms of the AGPL-3.0 license.