{"id":47157776,"url":"https://github.com/martonbognar/vcdvis","last_synced_at":"2026-03-13T02:35:00.292Z","repository":{"id":73158423,"uuid":"246808108","full_name":"martonbognar/vcdvis","owner":"martonbognar","description":"VCD visualizer: view your waveforms in ASCII format, or export them to TikZ figures.","archived":false,"fork":false,"pushed_at":"2025-11-02T19:50:54.000Z","size":83,"stargazers_count":31,"open_issues_count":0,"forks_count":6,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-11-02T21:20:19.482Z","etag":null,"topics":["latex","simulation","tikz","vcd","verilog","waveform","waveform-visualizer"],"latest_commit_sha":null,"homepage":"","language":"Python","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/martonbognar.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,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2020-03-12T10:38:18.000Z","updated_at":"2025-11-02T19:50:58.000Z","dependencies_parsed_at":null,"dependency_job_id":"5be00657-4707-4160-b0e4-7bcc66f9b083","html_url":"https://github.com/martonbognar/vcdvis","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/martonbognar/vcdvis","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/martonbognar%2Fvcdvis","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/martonbognar%2Fvcdvis/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/martonbognar%2Fvcdvis/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/martonbognar%2Fvcdvis/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/martonbognar","download_url":"https://codeload.github.com/martonbognar/vcdvis/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/martonbognar%2Fvcdvis/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30455959,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-13T02:22:12.178Z","status":"ssl_error","status_checked_at":"2026-03-13T02:06:49.475Z","response_time":60,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"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":["latex","simulation","tikz","vcd","verilog","waveform","waveform-visualizer"],"created_at":"2026-03-13T02:34:58.741Z","updated_at":"2026-03-13T02:35:00.264Z","avatar_url":"https://github.com/martonbognar.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# vcdvis\n\nConvert your value change dumps into TikZ figures or visualize them in ASCII.\nThe tool is clock cycle based, async signals will not work properly.\n\nvcdvis is still very much a work in progress, feel free to submit issues or pull requests!\n\n## Install\n\nInstall the package as a tool with your preferred method:\n\n```bash\n# Using uv (recommended)\nuv tool install git+https://github.com/martonbognar/vcdvis.git\n\n# Using pipx\npipx install git+https://github.com/martonbognar/vcdvis.git\n\n# Using pip\npip install --user git+https://github.com/martonbognar/vcdvis.git\n```\n\n## Usage\n\n```bash\n$ vcdvis -h\nusage: vcdvis.py [-h] (-cycles CYCLES | -start_tick START) [-end_tick END] [-c CONFIG] [-f FILE] {latex,ascii,both}\n\nVisualize a VCD waveform as ASCII or convert to a tikz figure.\n\npositional arguments:\n  {latex,ascii,both}  the output type\n\noptional arguments:\n  -h, --help          show this help message and exit\n  -cycles CYCLES      the number of clock cycles AT THE END of the simulation to include in the output\n  -start_tick START   the starting tick from the simulation to be included, e.g. 120ns\n  -end_tick END       the final tick from the simulation to be included, e.g. 180ns\n  -c CONFIG           configuration file (default: config.json)\n  -f FILE             the VCD file to parse (default: taken from the config file)\n```\n\nYou can specify the timeframe you want to visualize two different ways:\n1. By supplying the `-cycles N` argument. This will plot the final N clock cycles from the simulation.\nTip: if the simulation ends in the middle of a cycle (only one half of a cycle\nis included at the end), you can provide a decimal `cycles` argument to offset\nthis effect so that the visualization doesn't also start in the middle of a\ncycle, e.g. `57.5` if you want to visualize 57 cycles but a half extra cycle is\nincluded at the end of the VCD file.\n2. By supplying the `-start_tick TICK` and optionally the `-end_tick TICK` arguments.\nRunning `./vcdvis.py ascii -start_tick 131890ns -end_tick 132234ns` will visualize the selected signals\nbetween the two specified timestamps (you can get these timestamps from GTKWave for example).\n\n## Configuration\n\nThe cli uses a json configuration file that defaults to `./config.json`.\nThe following fields can be set:\n\n- `file_path`: the path to the VCD file (can be overwritten by the command line argument `-f`)\n- `clk_signal`: the name of the signal that should be considered the system clock\n- `delimiter`: if this signal is set and the output mode is `latex`, the TikZ figures will be split after this signal has been high for a full clock cycle\n- `signals`: the array of the signals that should be plotted (in addition to the clock and the delimiter signal). The signals can contain the following fields:\n    + `name`: the name of the signal in the VCD file. This can also be an array, in that case for each cycle the output value will be the maximum of the given signals. This can be useful if for example you want to track whether any of a number of flags have been triggered.\n    + `color`: a valid TikZ color, if the output is `latex`, this will be the color of the signal on the figure\n    + `label`: the pretty name of the signal in the output, defaults to the name[s] of the signal[s]\n    + `type`: type of the signal, possible values for now are `wire` (0/1), `hex`, and `ascii` (default is `wire`)\n\nFor a complete example, see the [config file](config.json.example) included in this repository.\n\n## Example\n\nGiven the following waveform file:\n\n![](https://i.imgur.com/qEUzd5q.png)\n\nWe can issue the following command:\n\n```bash\n$ vcdvis -cycles 20 latex -f /tmp/vcd/jmp_single.vcd \u003e output.tex\n```\n\nThis means that we want to plot the execution during last 20 clock cycles in the simulation.\nIn this case, the output will look like the following:\n\n![](https://i.imgur.com/8tz2juR.png)\n\nIf we omit the delimiter signal from the config file, we will get the following output (watch out, you might run off at the side of the page):\n\n![](https://i.imgur.com/V82va9C.png)\n\nAlternatively, if we want to plot the execution in ASCII to get a quick look, we can do:\n\n```bash\n$ vcdvis -cycles 20 ascii -f /tmp/vcd/jmp_single.vcd\nmclk                 █ █ █ █ █ █ █ █ █ █ █ █ █ █ █ █ █ █ █ █\ndata memory              ██  ██\nprogram memory       ████    ██████  ████    ████████████  █\nperipheral           ██                  ██  ██\ninstruction         SX…SXT \u0026EDE                MOV #N, r15\nexec_done            ██      ██      ██      ██  ██  ██  ███\n```\n\n## Contributing\n\nTo contribute with code, make sure you have [uv](https://docs.astral.sh/uv/getting-started/installation/) installed.\n\nAssuming your bugfix/feature request was previously discussed in an issue, a typical workflow may look like:\n\n1. Create a fork in github\n2. Checkout the repository locally and create a new branch\n3. Make your code changes and add tests if possible\n4. Run `make test`  and make sure it's green\n5. Push changes to your fork and open a PR\n\nThe `Makefile` contain other useful command as well which are used in CI.\nFor example, you can run `make build` and `make test-install` to test packging.\nIn general, `make test` should be enough for the automated tests.\n\nTo play around manually with the development source, you may install directly from your local checkout.\nE.g:\n\n```bash\nuv tool install -e $LOCAL_REPOSITORY_PATH\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmartonbognar%2Fvcdvis","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmartonbognar%2Fvcdvis","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmartonbognar%2Fvcdvis/lists"}