Generate a 3D Skyline in OpenSCAD and STL from GitLab contributions
Table of Contents
- Clone this repository
git clone https://github.com/ikaruswill/gitlab-skyline.git
- Create and activate a virtual environment
cd gitlab-skyline && python -m venv env && source env/bin/activate
- Install this package as an 'editable' install
pip install -e .
gitlab-skyline <username> <year>
usage: gitlab-skyline [-h] [-t] [-o OUTPUT] [--stl] [--url URL] [--token TOKEN]
[--concurrency CONCURRENCY] [--cached] [--logo LOGO]
[--logo-scale LOGO_SCALE] [--logo-y LOGO_Y]
[--logo-margin LOGO_MARGIN] [--handle-x HANDLE_X]
[--engrave-depth ENGRAVE_DEPTH] [--cap-pct CAP_PCT]
[--loglevel LOGLEVEL]
username [year]
Create OpenSCAD [and STL] models from GitLab contributions
positional arguments:
username GitLab username (without @)
year Year of contributions to fetch (default: 2024)
options:
-h, --help show this help message and exit
-t, --truncate Truncate dates before first contribution (default: False)
-o OUTPUT, --output OUTPUT
Output path (default: .)
--stl Export an STL file as well (Requires openscad binary) (default:
False)
--url URL GitLab URL (default: https://gitlab.com)
--token TOKEN Personal access token (default: None)
--concurrency CONCURRENCY
Max concurrent requests to GitLab (default: 2)
--cached Force the use of expired cached data (if available) (default:
False)
--logo LOGO Path to SVG of logo to be engraved on the front face (default:
/Users/will.ho/Documents/Dev/Projects/gitlab-
skyline/src/gitlab_skyline/gitlab.svg)
--logo-scale LOGO_SCALE
Logo scale factor (default: 0.09)
--logo-y LOGO_Y Logo y-offset from bottom (mm) (default: 1.25)
--logo-margin LOGO_MARGIN
Logo and text x margin from sides (mm) (default: 10)
--handle-x HANDLE_X Username handle x offset from left (mm) (default: 35)
--engrave-depth ENGRAVE_DEPTH
Logo and text engrave depth (mm) (default: 0.4)
--cap-pct CAP_PCT Percentile of non-zero contributions to cap outliers to (%)
(default: 95)
--loglevel LOGLEVEL Log level (default: INFO)
The skyline model generated, when viewed from above, is identical to the contribution heatmap in the user's profile. Contributions on Sunday correspond to the row at the back and Saturday, to the row at the front, with the bars inbetween corresponding to the contributions on weekdays in order.
Previous implementations generated models with contribution bars that did not match the profile heatmap.
Outlier dates with extremely high contribution counts tend to compress the mean heights of the contribution bars. To handle outliers, by default, maximum contribution counts are capped at the 95th percentile contribution counts of non-zero contribution dates.
This means any days with contribution counts higher than 95% of dates with at least 1 contribution, will be set to the 95th percentile value. If the 95th percentile value does not exist, it will be linearly interpolated from existing values.
If you left the year argument blank or set the year to be the current year, the length of the model will be dynamically adjusted based on the number of columns of contribution bars up till the current week. This is because dates that fall in the future are skipped and do not generate contribution bars.
By default, the GitLab logo is engraved on the left of the front face of the base.
To provide a custom logo, supply the path to the SVG file in the --logo argument.
If your GitLab is self-hosted on a custom domain, you may specify the domain using the --domain argument.
If you are not getting any contributions for the target user despite the heatmap being visible in the user's profile page, the user most likely has a private contribution history that is hidden from the public API.
To access private contribution history, generate a Personal Access Token with the read_user scope, and supply it with the --token argument.
If you are generating a model for someone who just started contributing in your organization (e.g. interns), then it is perhaps important to encode the start date in the model implicitly by truncating all dates before the first contribution.
This feature can be enabled by setting the --truncate flag.
To enable STL export alongside SCAD export, supply the --stl argument.
Note: the
openscadbinary must be present on your machine.
Install OpenSCAD from https://www.openscad.org/downloads.html and ensure that the openscad binary is present and functional.
openscad --version
gitlab-skyline is distributed under the terms of the MIT license.
Based on the excellent work of @felixgomez