{"id":26209986,"url":"https://github.com/bmmunga/terminal-screen","last_synced_at":"2025-07-24T01:37:41.205Z","repository":{"id":265467993,"uuid":"896055022","full_name":"bmmunga/terminal-screen","owner":"bmmunga","description":"Program reads a binary encoded stream of bytes supplied as input and generates a graphical representation of the bytes in a terminal window.","archived":false,"fork":false,"pushed_at":"2025-01-14T07:22:56.000Z","size":895,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-03-11T23:33:07.959Z","etag":null,"topics":["16-colors","256-colors","alcotest","ansi-colors","bresenham-line-drawing-algorithm","cli-app","fmt","functional-programming","monochrome","ocaml","terminal-based"],"latest_commit_sha":null,"homepage":"","language":"OCaml","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/bmmunga.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":"AUTHORS","dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-11-29T13:02:21.000Z","updated_at":"2025-02-13T11:55:31.000Z","dependencies_parsed_at":"2025-01-13T23:31:18.758Z","dependency_job_id":"aaf79371-23cf-4e61-bd83-1eff86e1fb80","html_url":"https://github.com/bmmunga/terminal-screen","commit_stats":null,"previous_names":["mungasoftwiz/terminal-screen","bmmunga/terminal-screen"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/bmmunga/terminal-screen","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bmmunga%2Fterminal-screen","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bmmunga%2Fterminal-screen/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bmmunga%2Fterminal-screen/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bmmunga%2Fterminal-screen/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/bmmunga","download_url":"https://codeload.github.com/bmmunga/terminal-screen/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bmmunga%2Fterminal-screen/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":266780323,"owners_count":23983034,"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","status":"online","status_checked_at":"2025-07-23T02:00:09.312Z","response_time":66,"last_error":null,"robots_txt_status":null,"robots_txt_updated_at":null,"robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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":["16-colors","256-colors","alcotest","ansi-colors","bresenham-line-drawing-algorithm","cli-app","fmt","functional-programming","monochrome","ocaml","terminal-based"],"created_at":"2025-03-12T07:18:41.431Z","updated_at":"2025-07-24T01:37:41.166Z","avatar_url":"https://github.com/bmmunga.png","language":"OCaml","readme":"# terminal-screen (A Terminal Screen Renderer)\n\n![GitHub Actions Workflow Status](https://img.shields.io/github/actions/workflow/status/MungaSoftwiz/terminal-screen/ci.yml)\n\nThis project implements a terminal screen renderer using OCaml. It parses a stream of binary-encoded commands and renders graphical characters/text in a terminal. This is achieved by interpreting the commands to setup a virtual screen, draw characters, lines, and text, manipulate the cursor, and clear the screen.\n\n# Glossary\n\n- [Project Presentation](#project-presentation)\n- [Proposal and UML Diagrams](#proposal-and-uml-diagrams)\n- [Program Overview](#program-overview)\n- [Features](#features)\n- [Getting Started](#getting-started)\n- [References](#references)\n\n# Project Presentation\n\nClick the link below to watch the project's presentation on YouTube.\n\n\u003ca href=\"https://www.youtube.com/watch?v=gGwpW5ToJHs\" target=\"blank\"\u003e\n\u003cp align=\"center\"\u003eWatch Project's Video Demo\u003c/p\u003e\n\u003cp align=\"center\"\u003e\u003c/p\u003e\n\u003c/a\u003e\n\n![an image of the project's demo on YouTube](assets/images/youtube-demo.png)\n\n---\n\n# Proposal and UML Diagrams\n\n- Below are the links to the proposal and corresponding UML Diagrams:\n\n### Project's proposal\n\nBelow is the project's proposal in PDF format.\n\n[Project Proposal (PDF)](./docs/Terminal-Screen-Initial-Proposal.pdf)\n\n### Use Case Diagram\n\nBelow is the use case diagram in PDF format:\n\n[Use Case Diagram (PDF)](./docs/Terminal-Screen-Use-Case-Diagram.pdf)\n\n### Sequence Diagram\n\nBelow is the sequence diagram in PDF format:\n\n[Sequence Diagram (PDF)](./docs/Terminal-Screen-Sequence-Diagram.pdf)\n\n### Flowchart Diagram\n\nBelow is a flowchart diagram in PDF format:\n\n[Flowchart Diagram (PDF)](./docs/Terminal-Screen-Flowchart-Diagram.pdf)\n\n### MVP: Making Progress\n\nThis section outlines the progress of the project as of 9/12/2024. Below is the document in PDF format:\n\n[MVP: Making Progress (PDF)](./docs/Terminal-Screen-MVP-Progress.pdf)\n\n---\n\n# Program Overview\n\nThis project leverages the power of OCaml's functional programming features to create a highly efficient and flexible terminal screen renderer. By utilising OCaml, the project benefits from strong type inference, immutability, and higher-order functions, ensuring robust and maintainable code.\n\n### Key Highlights\n\n- **Bresenham's Algorithm**: This project implements Bresenham's line algorithm to draw characters and lines accurately between coordinates. This algorithm is renowned for its efficiency in rendering lines on raster displays, making it ideal for text drawing in terminal screens. Efficiency is achieved using only integer addition, subtraction, and bit shifting to determine which points should be highlighted to form a close approximation to a straight line. Much faster than the floating-point arithmetic method.\n- **ANSI Colours**: To enhance the visual appeal, the project uses ANSI escape codes to handle text colouring and highlighting. This allows for a customisable and visually engaging terminal interface, capable of displaying a wide array of colours and styles.\n- **Functional Programming**: The use of OCaml's functional programming paradigms ensures that the code is concise, expressive, and easy to reason about. Functions are treated as first-class citizens, enabling powerful abstractions and code reusability. Check out this page if you want to learn more about [Ocaml's amazing features](https://www2.lib.uchicago.edu/keith/ocaml-class/why.html#:~:text=OCaml%20is%20basically%20as%20fast,static%20typing%20with%20type%20inference.).\n\n# Features\n\n- **Screen Setup**: Initialise a virtual terminal screen with customisable dimensions and colour modes.\n- **Draw Characters**: Place individual characters at specific coordinates.\n- **Draw Lines**: Render straight lines between two points with specified characters and colours.\n- **Render Text**: Display strings of text starting at a given position.\n- **Cursor Movement**: Move the cursor without rendering.\n- **Screen Clearing**: Reset the screen content.\n- **EOF Handling**: Terminate rendering upon receiving an end-of-file command.\n\n---\n\n### Binary Command Format\n\nThe program processes a binary input with the following structure:\n\n| **Command Byte** | **Length Byte** | **Data Bytes**         |\n| ---------------- | --------------- | ---------------------- |\n| 1 byte           | 1 byte          | Depends on the command |\n\n### Command Specifications\n\n| **Command**    | **Code** | **Description**                               | **Data Format**                                             |\n| -------------- | -------- | --------------------------------------------- | ----------------------------------------------------------- |\n| Setup Screen   | `0x1`    | Initialise screen dimensions and colour mode. | `Byte 0`: Width, `Byte 1`: Height, `Byte 2`: Colour Mode    |\n| Draw Character | `0x2`    | Draw a character at specific coordinates.     | `Byte 0`: x, `Byte 1`: y, `Byte 2`: Colour, `Byte 3`: ASCII |\n| Draw Line      | `0x3`    | Draw a line between two coordinates.          | `Byte 0-4`: Coordinates, `Byte 5`: Colour, `Byte 6`: ASCII  |\n| Render Text    | `0x4`    | Display text starting at a given position.    | `Byte 0-2`: Position \u0026 Colour, `Byte 3-n`: ASCII text       |\n| Cursor Move    | `0x5`    | Move cursor to a specific position.           | `Byte 0`: x, `Byte 1`: y                                    |\n| Draw at Cursor | `0x6`    | Draw at the current cursor position.          | `Byte 0`: ASCII, `Byte 1`: Colour                           |\n| Clear Screen   | `0x7`    | Reset the screen.                             | No data                                                     |\n| End of File    | `0xFF`   | End of the binary stream.                     | No data                                                     |\n\n---\n\n### Project Structure\n\n```\nterminal-screen/\n├── README.md\n├── bin/\n|   ├── main.ml\n├── lib/\n│   ├── *.ml\n│   ├── *.mli\n├── test/\n│   ├── test_module.ml\n├── .gitignore\n├── .ocamlformat\n├── dune-project\n├── library.opam\n├── AUTHORS\n└── Makefile\n```\n\n---\n\n# Getting Started\n\n### Installation\n\n1. Clone the repository:\n\n```bash\ngit clone https://github.com/yourusername/terminal-screen.git\ncd terminal-screen\n```\n\n2. Install opam package manager:\n\n```bash\nsudo apt-get install opam\n```\n\n3. Initialize OPAM:\n\n```bash\nopam init\n```\n\n4. Create a local switch (recommended for project isolation):\n\n```bash\nopam switch create . ocaml-base-compiler.5.2.0\n```\n\n5. Activate the local switch (environment):\n\n```bash\neval $(opam env)\n```\n\n6. Install dependencies:\n\n```bash\nopam install . --deps-only -y\n```\n\n### Build the Program\n\n- To build the program in an executable:\n\n```bash\nmake build\n```\n\n### Running the Program\n\n- To execute the program:\n\n```bash\nmake run\n```\n\n### Running Tests\n\n- Execute all unit tests:\n\n```bash\nmake test\n```\n\n# References\n\nThis project was developed with the help of the following resources:\n\n- [Official OCaml Documentation](https://ocaml.org/docs) for understanding the OCaml language and its standard library.\n- [ANSI Escape Codes Documentation](https://en.wikipedia.org/wiki/ANSI_escape_code) for managing terminal graphics.\n- [Github Gist of ANSI 256 colours](https://gist.github.com/HendrixString/ed994b8a57563a9934bb90ca1fae2de5) for a guide to ANSI 256 colour codes. Contains a link to Stack Overflow threads on the same.\n- [256 Colour Palette Explainer](https://abouris.github.io/color_explain/) webpage for the colour theory and ANSI colour visualisation.\n- [Bresenham's Line Drawing Algorithm](https://www.geeksforgeeks.org/bresenhams-line-generation-algorithm/) to efficiently draw straight lines between two points on a grid.\n\n# Authors\n\nMade with ❤️ by Boniface Munga - [Github](https://github.com/MungaSoftwiz) / [X](https://X.com/MungaSoftwiz)\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbmmunga%2Fterminal-screen","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbmmunga%2Fterminal-screen","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbmmunga%2Fterminal-screen/lists"}