|
| 1 | +# Bandplan Plotter |
| 2 | + |
| 3 | +A collection of R based scripts that take a set of CSV and markdown data files and turn them |
| 4 | +into a frequency bandplan diagram. |
| 5 | + |
| 6 | +The primary intention was to generate a bandplan diagram for |
| 7 | +[RSGB bandplans](https://rsgb.org/main/operating/band-plans/) for my desk(shack). As the scripts are |
| 8 | +data driven it should be fairly trivial to use to generate other bandplans by adding additional |
| 9 | +data sets. |
| 10 | + |
| 11 | + |
| 12 | + |
| 13 | +> Note: If you want to get prebuilt jpg's and pdf's then look at the [Releases](FIXME) page. |
| 14 | +
|
| 15 | +## Overview |
| 16 | + |
| 17 | +The scripts are written primarily in [`R`](https://www.r-project.org/about.html), mostly as I |
| 18 | +already knew `R` somewhat, and it has a reasonably nice and adaptable graphing library - |
| 19 | +[`ggplot`](https://ggplot2.tidyverse.org/index.html). |
| 20 | + |
| 21 | +Although it may have been fairly easy to draw out a bandplan in a diagramming package, like |
| 22 | +LibreOffice or similar, I really wanted to make this data driven code for a couple of reasons: |
| 23 | + |
| 24 | +- There will be mistakes, and mofidying the data and re-running the scripts is easier than editing |
| 25 | + an image in a gui tool |
| 26 | +- It makes it fairly trivial to add more bandplan datasets |
| 27 | + |
| 28 | +## Building |
| 29 | + |
| 30 | +The build system is based on running `R` under [Docker](https://www.docker.com/). This is simply |
| 31 | +as it is easier for me to put together a local docker image that contains all the R bits needed |
| 32 | +rather than trying to get them all installed natively on my machine. |
| 33 | + |
| 34 | +If you don't have or use docker, but do use R, then it should not be too hard to work out how |
| 35 | +to run the scripts under R directly. It may be worth looking at the [Dockerfile](dockerfile/Dockerfile) |
| 36 | +to see what R packages are used. |
| 37 | + |
| 38 | +### Build the docker image |
| 39 | + |
| 40 | +First, you need to build the docker image: |
| 41 | + |
| 42 | +```bash |
| 43 | +$ ./dockerbuild.sh |
| 44 | +``` |
| 45 | + |
| 46 | +This takes a short while whilst it collects up all the relevant R parts into the image. Some are |
| 47 | +compiled from source. |
| 48 | + |
| 49 | +Once completed your local docker image store should contain an image called `bandplan_plotter` |
| 50 | + |
| 51 | +### Doing a build |
| 52 | + |
| 53 | +To do a 'build' of the default datasets, run the script that runs the docker image: |
| 54 | + |
| 55 | +```bash |
| 56 | +$ ./dockerrun.sh |
| 57 | +``` |
| 58 | + |
| 59 | +This should produce some jpg files in your local directory, such as |
| 60 | +`rsgb_hf.jpg` and `rsgb_uvhf.jpg`. These files should be useable directly, or you can combine |
| 61 | +them into a single pdf by following the next step. |
| 62 | + |
| 63 | +### Building a pdf |
| 64 | + |
| 65 | +The jpg files can be combined into a single pdf file for convinience by running the simple script: |
| 66 | + |
| 67 | +```bash |
| 68 | +$ ./makepdf.sh |
| 69 | +``` |
| 70 | + |
| 71 | +This should produce the `allbands.pdf` file. |
| 72 | + |
| 73 | +## Releases |
| 74 | + |
| 75 | +Pre-built files can be found in the [Releases](FIXME) section. |
| 76 | + |
| 77 | +## Adding more datasets |
| 78 | + |
| 79 | +The general idea is that it should be easy to add new datasets to generate new bandplans to this |
| 80 | +project. Each bandplan dataset lives in its own subdirectory. |
| 81 | + |
| 82 | +If you want to generate a new bandplan then I'd generally recommend copying an existing bandplan |
| 83 | +dataset subdirectory, and then modifying it. Each dataset contains the following files: |
| 84 | + |
| 85 | +#### `bands.csv` |
| 86 | + |
| 87 | +The `bands.csv` file defines the frequency ranges the bandplan is going to cover. The only |
| 88 | +non-mandatory field is the `notes` field. If you add a notes field entry then it will be added |
| 89 | +to the bandplan `name` field as part of the y-axis label. |
| 90 | + |
| 91 | +#### `zones.csv` |
| 92 | + |
| 93 | +The `zones.csv` file consists of definitions for each 'sub section' of each band. It is effectively |
| 94 | +a collection of sets of data, one per band as defined in the `bands.csv` file. |
| 95 | + |
| 96 | +If an entry in the `zones.csv` file has a frequency that falls within one of the `bands.csv` file |
| 97 | +entries then it will be included and drawn within that band. |
| 98 | + |
| 99 | +The `type` field in the zones is used to both annotate the zone on the bandplan as well as locate |
| 100 | +which colour to draw the zone in - see the next section. |
| 101 | + |
| 102 | +#### `colours.csv` |
| 103 | + |
| 104 | +The `colours.csv` file defines which colour to draw each zone entry in. It is fairly mandatory to |
| 105 | +have one colour entry to match each type of zone. If you don't then the zone will be drawn in some |
| 106 | +default colour (probably grey). |
| 107 | + |
| 108 | +> Note: One day I'll probably 'rotate' the colours.csv file so it is just two columns, rather than the |
| 109 | +current two rows, purely as editing the long rows as it stands is a bit of a pain. |
| 110 | + |
| 111 | +#### `tags.csv` |
| 112 | + |
| 113 | +The `tags.csv` contains a list of items to be 'annotated' onto the bandplans. This can be a useful |
| 114 | +feature to highlight specific frequencies. |
| 115 | + |
| 116 | +At present only the `start_freq` field defines where the tag is placed. Later support could be added |
| 117 | +to tag 'ranges', at which point we'd figure out how to draw them nicely on the bandplan. |
| 118 | + |
| 119 | +#### `title.md` |
| 120 | + |
| 121 | +The `title.md` file contains [markdown](https://en.wikipedia.org/wiki/Markdown) text to be drawn |
| 122 | +at the top of the bandplan plot. It is rendered using a |
| 123 | +[`geom_richtext`](https://cran.r-project.org/web/packages/ggtext/vignettes/plotting_text.html) |
| 124 | +library. Be aware that not all markdown or html types may be supported and rendered, and changing |
| 125 | +the rendering of the title text may affect the size and position of the other text in the titlebar. |
| 126 | + |
| 127 | +#### `README.md` |
| 128 | + |
| 129 | +Please do update the `README.md` file for each data subdirectory to describe what the bandplan |
| 130 | +data is trying to describe. |
| 131 | + |
| 132 | +## Debug and development |
| 133 | + |
| 134 | +If you want to modify the `plot.R` code and experiment etc. then the `dockershell.sh` utility |
| 135 | +script can be used to enter into a running docker image that is then useful for `R` development |
| 136 | +and debugging. The basic use case is something like: |
| 137 | + |
| 138 | +```bash |
| 139 | +$ ./dockershell.sh |
| 140 | +# R |
| 141 | +> source('/data/plot.R') |
| 142 | +^D |
| 143 | +exit |
| 144 | +``` |
| 145 | + |
| 146 | +To build a specific dataset, at the R prompt set the `inputdir` variable to the name of the |
| 147 | +relevant directory: |
| 148 | + |
| 149 | +```R |
| 150 | +> inputdir="rsgb_uvhf" |
| 151 | +> source('/data/plot.R') |
| 152 | +``` |
| 153 | + |
| 154 | +## Contributing |
| 155 | + |
| 156 | +If you want to contribute by sending bug reports, addtions, fixes or new datasets then the best |
| 157 | +way is by using the github Issues or pull request methods. If you are flummoxed by that then feel |
| 158 | +free to try emailing me. |
| 159 | + |
| 160 | +## Re-using |
| 161 | + |
| 162 | +This code base is under the Creative Commons [CC-BY](https://creativecommons.org/licenses/by/4.0/) |
| 163 | +license. Basically, you can use it as you wish, but please do attribute where you got the original |
| 164 | +code from. Thanks. |
| 165 | + |
| 166 | +## Credits |
| 167 | + |
| 168 | +In part the idea to render a bandplan was driven by my personal need, but inspired by a couple of |
| 169 | +existing bandplan charts: |
| 170 | + |
| 171 | +- [FISTS](https://fists.co.uk/) supply a [bandplan](https://fists.co.uk/frequencies.html) giving |
| 172 | + both their and the general QRP CW frequencies annotated on a chart. I have this on my desk, it's |
| 173 | + great - but, sometimes I want to wander up the band into the SSB area to check activity and |
| 174 | + propogation, but the FISTS chart only covers the CW sections. Thus, I wanted an 'expanded' chart. |
| 175 | +- [S56G](https://www.s56g.net/) supplies some really nice |
| 176 | + [bandplans](https://www.s56g.net/index.php/s5-bandplans/) covering IARU Region 1, but they don't |
| 177 | + really represent the UK RSGB plans, so I pretty much wanted to re-create something similar but |
| 178 | + more appropriate to me. |
| 179 | + |
0 commit comments