{"id":13775157,"url":"https://github.com/Ben1152000/sootty","last_synced_at":"2025-05-11T07:32:00.549Z","repository":{"id":36998871,"uuid":"393209187","full_name":"Ben1152000/sootty","owner":"Ben1152000","description":"A command-line tool for displaying vcd waveforms.","archived":false,"fork":false,"pushed_at":"2024-02-19T10:52:44.000Z","size":471,"stargazers_count":55,"open_issues_count":26,"forks_count":15,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-04-29T06:05:52.251Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-3-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Ben1152000.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":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2021-08-06T01:05:59.000Z","updated_at":"2025-04-25T11:48:59.000Z","dependencies_parsed_at":"2024-01-07T01:18:15.931Z","dependency_job_id":"86c52845-fdb7-4bf8-91bd-12b39f5d73fd","html_url":"https://github.com/Ben1152000/sootty","commit_stats":{"total_commits":141,"total_committers":6,"mean_commits":23.5,"dds":"0.46808510638297873","last_synced_commit":"2cdb762ee12bcb1d4ee82b465b0fba83bfcd49f4"},"previous_names":[],"tags_count":3,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Ben1152000%2Fsootty","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Ben1152000%2Fsootty/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Ben1152000%2Fsootty/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Ben1152000%2Fsootty/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Ben1152000","download_url":"https://codeload.github.com/Ben1152000/sootty/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253533771,"owners_count":21923514,"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":[],"created_at":"2024-08-03T17:01:34.628Z","updated_at":"2025-05-11T07:32:00.234Z","avatar_url":"https://github.com/Ben1152000.png","language":"Python","funding_links":[],"categories":["Waveform Viewers"],"sub_categories":[],"readme":"# Sootty\n\nSootty is a graphical command-line tool for visualizing waveforms from hardware simulations, as a substitute for waveform visualizers like Verdi and GTKWave. It is designed with a focus on being lightweight and easy to use, and takes advantage of modern terminals’ capabilities to provide a clean graphical display. Current features include:\n- Customizable display style\n- Search and highlight events using a simple query language\n\nAnd here's an example of how sootty can be used directly from the terminal:\n\n\u003cimg width=\"979\" alt=\"Screenshot of sootty in action\" src=\"https://raw.githubusercontent.com/Ben1152000/sootty/master/image/screenshot.png\"\u003e\n\n## Getting Started\n\n1. Install sootty using pip:\n\n```bash\npip install sootty\n```\n\n2. Display a waveform file to the terminal:\n\n```bash\nsootty \"waveform.vcd\" -o \u003e image.svg\n```\n\nOptional arguments include:\n- `-s | --start FORMULA` Specify the start of the window.\n- `-e | --end FORMULA` Specify the end of the window.\n- `-l | --length N` Specify the number of ticks in the window (mutually exclusive with `-e`).\n- `-o | --output` Print svg data to `stdout` rather than display on terminal.\n- `-w | --wires LIST` Comma-separated list of wires to include in the visualization (default to all wires).\n- `-b | --break FORMULA` Specify the formula for the points in time to be highlighted.\n- `-r | --radix N` Display values in radix N (default 10).\n- `-S | --save SAVENAME` Saves current query for future reuse.\n- `-R | --reload SAVENAME` Loads a saved query. Requires query name as string.\n- `--btable` Print the wire value table at breakpoints to `stdout` (`-b` is required).\n\n*Note: For more detailed information on the query language, check out [syntax.md](syntax.md)\n\n### Examples\n\nBelow are some more examples  that take advantage of some of the features sootty has to offer:\n\n- Display all wires starting at time 4 and ending at wire `clk`'s tenth tick:\n\n```bash\nsootty \"example/example3.vcd\" -s \"time 4\" -e \"acc clk == const 10\" -w \"clk,rst_n,pc,inst\"\n```\n\n- Display wires `Data` and `D1` for 8 units of time starting when `Data` is equal to 20:\n\n```bash\nsootty \"example/example1.vcd\" -l 8 -s \"Data == const 20\" -w \"D1,Data\"\n```\n\n- Saving a query for future use:\n\n```bash\nsootty \"example/example2.vcd\" -s \"rdata \u0026\u0026 wdata == const 22\" -l 10 -w \"rdata, wdata\" -S \"save.txt\"\n```\n\n- Reloading a saved query:\n\n```bash\nsootty -R \"save.txt\"\n```\n\n- Add breakpoints at time 9, 11, and 16 - 17 and print wire values at breakpoints:\n\n```bash\nsootty \"example/example5.evcd\" -b \"time 9 || time 11 || after time 15 \u0026\u0026 before time 18\" --btable\n```\n\n### Running with python\n\nSootty can also be run from within a python program:\n\n```python\nfrom sootty import WireTrace, Visualizer, Style\nfrom sootty.utils import evcd2vcd\n\n# Create wiretrace object from vcd file:\nwiretrace = WireTrace.from_vcd_file(\"example/example1.vcd\")\n\n# Convert wiretrace to svg:\nimage = Visualizer(Style.Dark).to_svg(wiretrace, start=0, length=8)\n\n# Display to stdout:\nimage.display()\n\n# Manually convert EVCD file to VCD file:\nwith open('myevcd.evcd', 'rb') as evcd_stream:\n    vcd_reader = evcd2vcd(evcd_stream)\n    with open('myvcd.vcd', 'wb') as vcd_stream:\n        vcd_stream.write(vcd_reader.read())\n```\n\n*Note: You can view and modify the save files for the queries in the `~/.config/sootty/save` directory.*\n\n## Dependencies\n\nAs of the current release, Sootty can only display images in certain terminals with builtin graphics support. This currently includes the following terminal replacements:\n\n- [iTerm2](https://iterm2.com/)\n- [kitty](https://sw.kovidgoyal.net/kitty/)\n\nThe following external dependencies are also needed to properly display images within the terminal:\n\n- [viu](https://github.com/atanunq/viu)\n\n  ```bash\n  # From source (rust package manager)\n  cargo install viu\n  # MacOS\n  brew install viu\n  # Arch Linux\n  pacman -S viu\n  ```\n- rsvg-convert\n  ```bash\n  # Ubuntu\n  apt install librsvg2-bin\n  # MacOS\n  brew install librsvg\n  ```\n\n## Contributing\n\nIf you are interested in contributing to this project, feel free to take a look at the existing issues and submit a PR. Beginners are encouraged to focus on issues with the \"good first issue\" label. This project has also been involved with Google Summer of Code through the [FOSSi Foundation](https://www.fossi-foundation.org/). Check out our project idea for GSoC '23: https://www.fossi-foundation.org/gsoc23-ideas#enhancing-the-sootty-terminal-based-graphical-waveform-viewer\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FBen1152000%2Fsootty","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FBen1152000%2Fsootty","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FBen1152000%2Fsootty/lists"}