{"id":15396059,"url":"https://github.com/costava/heightmap-ray-marcher","last_synced_at":"2026-03-03T12:44:18.244Z","repository":{"id":91581687,"uuid":"176662749","full_name":"Costava/heightmap-ray-marcher","owner":"Costava","description":"A ray marcher for heightmap images or any images with a real time freely moving camera.","archived":false,"fork":false,"pushed_at":"2021-10-21T23:30:41.000Z","size":952,"stargazers_count":4,"open_issues_count":2,"forks_count":1,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-04-16T00:18:18.453Z","etag":null,"topics":["aabb","cast","casting","cpp","glm","marcher","marching","orthographic","perspective","projection","ray","sdl2"],"latest_commit_sha":null,"homepage":"","language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Costava.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2019-03-20T05:43:23.000Z","updated_at":"2024-04-07T18:20:13.000Z","dependencies_parsed_at":null,"dependency_job_id":"8bdc3d2d-e1df-44a4-a571-06a3b4e07d70","html_url":"https://github.com/Costava/heightmap-ray-marcher","commit_stats":null,"previous_names":[],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Costava%2Fheightmap-ray-marcher","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Costava%2Fheightmap-ray-marcher/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Costava%2Fheightmap-ray-marcher/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Costava%2Fheightmap-ray-marcher/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Costava","download_url":"https://codeload.github.com/Costava/heightmap-ray-marcher/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":249173313,"owners_count":21224519,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["aabb","cast","casting","cpp","glm","marcher","marching","orthographic","perspective","projection","ray","sdl2"],"created_at":"2024-10-01T15:30:43.231Z","updated_at":"2026-03-03T12:44:18.208Z","avatar_url":"https://github.com/Costava.png","language":"C++","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Heightmap Ray Marcher\r\n\r\nA ray marcher for heightmap images (or any images) with a real time freely moving camera.\r\n\r\nMove the camera with WASD and the mouse. Hold space to raise the camera and hold Q to lower it.  \r\nSwitch the projection mode with the number keys:\r\n\r\n1. Perspective\r\n2. Spherical\r\n3. Orthographic\r\n\r\nAlso:\r\n\r\n- Ctrl+Q to exit.\r\n- Zoom in/out with scroll wheel.\r\n- Press F1 to toggle showing the frames per second.\r\n- Press F11 to toggle fullscreen.\r\n- Press F12 to save a screenshot in `screenshots` directory.\r\n- Press backtick (left of `1`) to toggle the console for changing configuration at runtime.\r\n- Parsing the console input is the same as the parsing for the config file.\r\n- Press Ctrl+Shift+R to begin recording (saving frames out to image files) or to stop recording early (otherwise recording will stop after `recording_frame_count` number of frames).\r\n- You can freely resize the window.\r\n\r\nFor each pixel, a ray is cast and intersection is checked with an axis aligned bounding box (AABB) around the heightmap.\r\nIf the ray collides with the AABB, then ray marching begins at the collision point.\r\n\r\nFeel free to ask a question by opening an issue.\r\n\r\n## What it can do\r\n\r\nThese three images were created with the same camera position and direction, but different projection modes.\r\n\r\nPerspective:  \r\n![Man (perspective)](https://i.imgur.com/hOn8tdS.png)\r\n\r\nSpherical:  \r\n![Man (spherical)](https://i.imgur.com/QJzDTO5.png)\r\n\r\nOrthographic:  \r\n![Man (orthographic)](https://i.imgur.com/cHbKgmL.png)  \r\n[Original image](https://unsplash.com/photos/rpF3p_RrE9g)\r\n\r\n---\r\n\r\n![White tiger](https://i.imgur.com/EP4EnZ9.png)  \r\n[Original image](https://unsplash.com/photos/dGMcpbzcq1I)\r\n\r\n---\r\n\r\n![Face (close)](https://i.imgur.com/dxoOZgR.png)  \r\n![Face (overview)](https://i.imgur.com/YJSp7cq.png)  \r\n[Original image](https://unsplash.com/photos/sibVwORYqs0)\r\n\r\n---\r\n\r\n![Face in leaves (close)](https://i.imgur.com/MQwqKdL.png)  \r\n![Face in leaves (overview)](https://i.imgur.com/voGVGgZ.png)  \r\n[Original image](https://unsplash.com/photos/svnH68VDN4Q)\r\n\r\n## Configuration file\r\n- The program is launched from the command line with a configuration file argument: `./hmap path/to/config.txt`\r\n- The config file is a sequence of whitespace-separated values.\r\n- Consider starting each line in the config with an identifier, followed by its appropriate arguments.\r\n- Options can be specified in any order.\r\n- All config file options are optional except `heightmap` and `colormap`\r\n- Input to many options is not validated and handling parsing is not robust.\r\n- Do NOT use file paths that include spaces.\r\n\r\nSee `sample_config.txt` for an example.\r\n\r\n### Options\r\n\r\n| Identifier | Parameter(s) | Description |\r\n| ---------- | ------------ | ----------- |\r\n| heightmap | path/to/img.png | A path to an image. The image does NOT have to be greyscale. The luminance of the image's pixels determines the heights. The image can be any format supported by `stb_image.h`: JPEG, PNG, TGA, BMP, PSD, GIF, HDR, PIC, PNM. See `vendor/stb_image.h` for details and exceptions. The image must have the same resolution as the image for `colormap`. **This option must be specified.** |\r\n| colormap | path/to/img.png | Similar to `heightmap` but for determining colors. The easiest choice will be the same image as for `heightmap`. The specified image must have the same resolution as the image for `heightmap`. **This option must be specified.** |\r\n| print | [No parameters] | Print current values of all options. |\r\n| resolution | \\\u003cint x\u003e \\\u003cint y\u003e | The x and y dimensions (in pixels) of the window content. |\r\n| hfov | \\\u003cdouble degrees\u003e | Set the horizontal field of view (in degrees). You will likely experience issues if this is not in the range (0, 180). |\r\n| hang | \\\u003cdouble degrees\u003e | Horizontal angle of camera. 0 is looking in direction of positive x axis. 90 is looking in direction of positive y axis, |\r\n| vang | \\\u003cdouble degrees\u003e | Vertical angle of camera. 0 is looking straight up (with positive z axis). 90 is looking parallel to xy plane. |\r\n| pos | \\\u003cdouble x\u003e \\\u003cdouble y\u003e \\\u003cdouble z\u003e | Set position of camera. |\r\n| pos_x | \\\u003cdouble x\u003e | Set x coordinate of camera. |\r\n| pos_y | \\\u003cdouble y\u003e | Set y coordinate of camera. |\r\n| pos_z | \\\u003cdouble z\u003e | Set z coordinate of camera. |\r\n| min_height | \\\u003cdouble z\u003e | The minimum world space height in the height map. Values are normalized between the min and max. |\r\n| max_height | \\\u003cdouble z\u003e | The maximum world space height in the height map. |\r\n| lum | \\\u003cdouble r\u003e \\\u003cdouble g\u003e \\\u003cdouble b\u003e | For each pixel in the heightmap image with components RGB, the pixel's heightmap value is (rR + gG + bB), clamped to range [0.0, 255.0], then scaled to range [min_height, max_height] |\r\n| lum_norm | \\\u003cdouble r\u003e \\\u003cdouble g\u003e \\\u003cdouble b\u003e | `lum` but the 3 components are normalized so that they sum to 1. |\r\n| lum_r | \\\u003cdouble r\u003e | `lum` but only setting R component. |\r\n| lum_g | \\\u003cdouble g\u003e | `lum` but only setting G component. |\r\n| lum_b | \\\u003cdouble b\u003e | `lum` but only setting B component. |\r\n| grid_width | \\\u003cdouble val\u003e | The world space grid square size of the heightmap. |\r\n| ortho_width | \\\u003cdouble val\u003e | The world space grid spacing of rays when using orthographic projection. |\r\n| step_dist | \\\u003cdouble val\u003e | How far in world space to step when ray marching. |\r\n| bg_color | \\\u003cint red\u003e \\\u003cint green\u003e \\\u003cint blue\u003e | The background color. Values should be in range [0, 255]. |\r\n| cycle | \\\u003cint num\u003e | A full image will be rendered across `num` frames. |\r\n| mouse_sens | \\\u003cdouble val\u003e | Horizontal and vertical mouse sensitivity for rotating camera. |\r\n| scroll_sens | \\\u003cdouble val\u003e | Sensitivity when zooming in/out with scroll wheel. |\r\n| move | \\\u003cdouble val\u003e | Movement speed multiplier. |\r\n| recording_frame_count | \\\u003cint count\u003e | The number of frames to render when recording (saving frames out to image files). |\r\n\r\n## Build and run on Linux\r\n\r\n1. Clone the repo\r\n2. Install the dependencies e.g. `pamac install sdl2 sdl2_ttf glm`\r\n- - [SDL](https://www.libsdl.org/) (tested with v2.0.16)\r\n- - [SDL_ttf](https://www.libsdl.org/projects/SDL_ttf/) (tested with v2.0.15)\r\n- - [OpenGL Mathematics](https://glm.g-truc.net/) (tested with v0.9.9.8)\r\n3. `make build`\r\n4. Run with `./hmap path/to/config.txt`\r\n\r\nBuilding for other platforms will follow a similar approach.\r\n\r\n## License\r\n\r\nFiles original to this repo are under the BSD 2-Clause License.\r\nSee file `LICENSE.txt`.\r\n\r\nFiles under `vendor` and `fonts` have their own licenses.\r\nSee those directories for details.\r\n\r\n## Contributing\r\n\r\nNot currently accepting contributions. Feel free to create an issue.\r\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcostava%2Fheightmap-ray-marcher","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcostava%2Fheightmap-ray-marcher","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcostava%2Fheightmap-ray-marcher/lists"}