Custom fontcolours xml files
From Fs_wiki
Contents |
fontcolours.xml
Most of the files in the symbols/ directory are sketches, and they are automatically loaded when you start the program. There are two files in the symbols directory that are not sketches. One is symbols.xml and the other is fontcolours.xml. The file fontcolours.xml describes sets of styles which can be used to render a sketch. This includes the typeface and size of font to use for each defined label style, and the sizes of each symbol type which can be used on a sketch. It is also possible to define subsets within each style group.
If you are experimenting or developing the fontcolours.xml files, you can click on Update | Reload Fontcolours from the menubar of the sketch window to see the effect on the areas and linewidths. Symbols will, of course, need to be updated.
Styles
A style defined in fontcolours.xml is applied to the sketch in order to render it. There are currently two styles defined in the file shipped with Tunnel, 'default' and 'base1000'. You will see these in the dropdown list labeled 'subset style' in the sketch window. If you select 'default' then you will find the labels on your sketch and the symbols are rendered much smaller than if you select the 'base1000' style. There are also some symbols which are not included in the 'default' style, but which are available in the 'base1000' style. The purpose behind different styles is to suit surveys designed to be printed at different scales. A survey of a small cave might be designed to be printed on an A4 sheet of paper where 1cm on the page equals 1m in the cave. At this scale you want your symbols and labels to be quite small so they do not take up too much of the page. But with a large cave system survey you might have 1cm on the printed page equal to 10m in the cave (or the final survey would require an enormous sheet of paper to fit it all on). In this case you need to render the labels and symbols much larger, or they will be too small to make out on the printed survey.
Subsets
Each style can include one or more subsets. These are groups of settings which differ from the settings of the style. A common use of subsets is to give the areas of your survey a different background colour. You can define all the fonts and symbol sizes in the style, and then add several subsets which just set the background colour. You can then add different areas in your survey to different subsets to shade those parts of the cave with the different colours. Choose pale colours so that when one coloured passage crosses over another coloured passage, the details from the lower passage show through the colour of the upper passage.
|
Example of coloured subsets
Creating Your Own Subsets
If you find that the subsets supplied by Tunnel do not suit your survey, then you will want to create your own. You can do this either by adding them to the fontcolours.xml file in the symbols directory, making them available in all your Tunnel projects, or you can create additional project specific fontcolours files. Tunnel will load any subsets and styles from files found in your top level project directory, so if you create a new fontcolours file for your project you just need to put it into your project directory. I usually name my files using the cave name. So for my Riano cave survey I called my file fontcoloursRiano.xml.
Structure of fontcolours.xml files
If you open up the fontcolours.xml file you will see it contains a number of groups of subsets, each enclosed in <groupsubsetattr> tags. Only two of these are currently presented in the list of subsets you can select from in the Tunnel sketch window. The others are hidden because the groupsubsetselectable attribute is set to "no". These hidden settings groups can be used as the basis for other settings groups. You should see that the visible group 'base1000' is based on the hidden group 'base'. This is done using the <importgroupsubsetattr> tag. So to create our own customised subset group we need to create an XML file following this template:
<?xml version='1.0' encoding='us-ascii'?>
<tunnelxml>
<fontcolours fontstyle="PLAIN" fontname="Serif">
<groupsubsetattr groupsubsetname="My_Settings" groupsubsetselectable="yes">
<importgroupsubsetattr groupsubsetname="base1000"/>
</groupsubsetattr>
</fontcolours>
</tunnelxml>
Copy this text into a text editor and save the file as fontcoloursCustom.xml in your Tunnel project directory (where your survey project files are located). So far our custom settings file contains one new subset group named 'My_Settings', which is set to selectable using the groupsubsetselectable="yes" attribute. The group then imports from the existing subset group 'base1000' using the <importgroupsubsetattr groupsubsetname="base1000"/> element. This will make all the labels, symbols and subsets from the 'base1000' group available to us, so we do not need to redeclare them. We only need to over-ride any which we want to customise for our survey. Now we need to add some subset definitions to our new group, in empty lines inside the <groupsubsetattr> element above.
Initially we will add some subsets which do not change any of the symbols or label fonts, but which just change the background colour used to fill areas. Subsets are added using the <subsetattr> tag. This tag includes attributes for the subset name, the subset it should be placed under, and the area and label colours used to render the subset. A new subset element in the XML file looks like this:
<subsetattr name="mainactivelevels" uppersubset="basevisiblecave" areacolour="#550000ff" labelcolour="#ff0000ff"> </subsetattr>
Here we have defined a subset called "mainactivelevels" which will be placed under the existing subset "basevisiblecave". The subset "basevisiblecave" is an existing subset in the 'base1000' group which we have imported into our subset group, and already contains all the label and symbol definitions we will use on a cave survey sketch. By placing our new subset under this existing one we can use all the labels and symbols in our subset which exist in the subset "basevisiblecave". The only new things we have defined in our subset are the colours to be used for area fills and labels. These are defined using the 'areacolour' and 'labelcolour' attributes. The values of these attributes consist of an 8 character hexadecimal number. The first 2 characters specify how dark the colour will be rendered. The remaining 6 characters specify the shade of the colour, each pair of characters giving the red, green and blue components of the colour respectively. In our subset definition above the area fill will be a mid-shade of blue using the value #550000ff. 55 = a mid-shade, 00=red, 00=green, ff=blue. The label text will also be blue, but a dark shade of blue, using the value #ff0000ff. If you are not familiar with hexadecimal notation then you can just use the following values which work well in Tunnel:
Colour areacolour labelcolour Red #50ff0000 #ffff0000 Orange #80faa000 #fffaa000 Yellow #55ffff00 #ffe0e000 Green #5500ff00 #ff00c000 Cyan #5500ffff #ff30d0d0 Blue #550000ff #ff0000ff Purple #55a000f0 #ffa000f0
Labels will only be coloured using the subset label colour if the label style assigned to the label on our sketch is declared in the subset. So we need to declare all the label styles we are going to use on our sketch in the subset element. The following label styles are declared in the subset "basevisiblecave" of the 'base1000' group, so we need to redeclare them in our subset if we want them to render using the settings from our subset.
<subsetattr name="mainactivelevels" uppersubset="basevisiblecave" areacolour="#550000ff" labelcolour="#ff0000ff"> <labelfcol labelstylename="default"/> <labelfcol labelstylename="qm"/> <labelfcol labelstylename="step"/> <labelfcol labelstylename="passage"/> <labelfcol labelstylename="area"/> <labelfcol labelstylename="entrance"/> <labelfcol labelstylename="cave"/> </subsetattr>
Now we have a working customised fontcolors XML file. But to illustrate the use of coloured subsets we will add a second subset definition using a different colour. We will call the second subset "drylowerlevels" and colour it pale green. Our complete "fontcoloursCustom.xml" file should now look like this.
<?xml version='1.0' encoding='us-ascii'?>
<tunnelxml>
<fontcolours fontstyle="PLAIN" fontname="Serif">
<groupsubsetattr groupsubsetname="My_Settings" groupsubsetselectable="yes">
<importgroupsubsetattr groupsubsetname="base1000"/>
<subsetattr name="mainactivelevels" uppersubset="basevisiblecave" areacolour="#550000ff" labelcolour="#ff0000ff">
<labelfcol labelstylename="default"/>
<labelfcol labelstylename="qm"/>
<labelfcol labelstylename="step"/>
<labelfcol labelstylename="passage"/>
<labelfcol labelstylename="area"/>
<labelfcol labelstylename="entrance"/>
<labelfcol labelstylename="cave"/>
</subsetattr>
<subsetattr name="drylowerlevels" uppersubset="basevisiblecave" areacolour="#5500ff00" labelcolour="#ff00c000">
<labelfcol labelstylename="default"/>
<labelfcol labelstylename="qm"/>
<labelfcol labelstylename="step"/>
<labelfcol labelstylename="passage"/>
<labelfcol labelstylename="area"/>
<labelfcol labelstylename="entrance"/>
<labelfcol labelstylename="cave"/>
</subsetattr>
</groupsubsetattr>
</fontcolours>
</tunnelxml>
Save this file in the top level directory of your Tunnel project and restart Tunnel. When you open your project you should see a message in the log window like the following.
Loading font colours:fontcoloursCustom.xml creating My_Settings (selectable) shortname My_Settings
This shows that your file was found and your subset group was loaded. If you open a sketch in your project you should see the new subset group "My_Settings" is now included in the drop down list control of subset styles shown on the subsets tab. Select this subset style, and then double-click on the subset "basevisiblecave" in the subsets pane to open up this subset. You should now see your new subsets "mainactivelevels" and "drylowerlevels". Update areas on your sketch, and then select the new subset "mainactivelevels". Your entire sketch should be shown greyed out now, as we have not added any parts of it to this subset yet. Right+Shift click on an area to select it (the boundary of the area should turn pink). Now click on the "Add to subset" button. This should add all the selected lines in the sketch to this subset. Right-click anywhere on the sketch to deselect the area. Now update areas again, and your should see your area coloured blue because this is the fill colour we specified for the subset. Select a label and add this to the subset. The label should now be coloured blue when you render the sketch. Repeat this process with a different area and label after selecting the other new subset "drylowerlevels". This area and label should now be rendered green. Finally click the "Clear subset selection" button to show all subsets again. Now update everything to see the rendered sketch, which should show both green and blue areas and labels for the areas and labels in each subset.
Customising Label Fonts
Next we will customise the font style for some of our labels. Label customisations have to be declared in every subset where we want to use them, otherwise they will use the default style (this may be a bug?). So we need to repeat the customised label declaration in each of our subsets. To keep these examples simple, we are going to remove some of the label styles from the customised foncolours file and just show a few which we will use in our sketches. You can add as many customised label styles to your own fontcolours file as you want. We will start with the following subset definition in our custom fontcolours file.
<subsetattr name="mainactivelevels" uppersubset="basevisiblecave" areacolour="#550000ff" labelcolour="#ff0000ff">
<labelfcol labelstylename="default"/>
<labelfcol labelstylename="feature"/>
<labelfcol labelstylename="passage"/>
<labelfcol labelstylename="area"/>
<labelfcol labelstylename="entrance"/>
</subsetattr>
This gives us some label styles to use to label cave entrances, passage names, features in the cave, general areas of the cave and a default style. You will need to add some labels to your sketch which use these different label styles in order to see the customised font styles working. Make sure you add all the labels to the style subset "mainactivelevels". Initially all the labels will be rendered using the default font, because we have not specified any style attributes apart from the label colours in the subset. We can specify the font typeface and font size as follows.
<labelfcol labelstylename="area" fontname="Franklin Gothic Medium" size="36"/>
We want our cave entrances to be a little more visible on the survey than labels naming areas of the cave, so we will add an additional fontstyle attribute to these to make them bold.
<labelfcol labelstylename="entrance" fontname="Franklin Gothic Medium" fontstyle="BOLD" size="36"/>
We can define additional font styles of our own too. We will add a style to use for labelling pitch lengths.
<labelfcol labelstylename="pitch length" fontname="Franklin Gothic Medium" size="24"/>
Finally, we will set style attributes for the other font styles. Here is how the final subset definition should look.
<subsetattr name="mainactivelevels" uppersubset="basevisiblecave" areacolour="#550000ff" labelcolour="#ff0000ff"> <labelfcol labelstylename="default"/> <labelfcol labelstylename="description" fontname="Times New Roman" size="18"/> <labelfcol labelstylename="feature" fontname="Times New Roman" fontstyle="ITALIC" size="24"/> <labelfcol labelstylename="passage" fontname="Times New Roman" size="34"/> <labelfcol labelstylename="entrance" fontname="Franklin Gothic Medium" fontstyle="BOLD" size="36.0"/> <labelfcol labelstylename="area" fontname="Franklin Gothic Medium" size="36"/> <labelfcol labelstylename="pitch length" fontname="Franklin Gothic Medium" size="24"/> </subsetattr>
Remember to copy these font styles into all the other coloured subsets in your custom fontcolours file. You should now be able to create labels with these customised font styles in any of your coloured subsets.
Customising Symbol Styles
We can also customise the way that symbols are rendered using our custom fontstyles XML file. This is not about changing the symbols themselves (that is covered in the following tutorial on configurng the symbols.xml file). This is about changing the size of the symbols so that they show up best at the scale you plan to print your sketch.
If you look in the foncolours.xml file supplied with Tunnel, you will find that some symbols are declared in sets, while others are declared on their own. The purpose of sets of symbols is that you can specify properties for the set and these will be applied to all the symbols in the set. Here is an example of a symbol set declaration.
<set multiplicity="1" buttonaction="overwrite" position="endpath" scale="fixed"
orientation="alongaxis" area-interaction="allowed-outside">
<symbolaut dname="breeze" description="breeze symbol">
<asymbol name="breeze" picscale="2.8"/>
</symbolaut>
<symbolaut dname="slope" description="slope symbol">
<asymbol name="slope" picscale="1.5" drawstyle="filled"/>
</symbolaut>
<symbolaut dname="stream" description="stream symbol">
<asymbol name="stream" picscale="2.5"/>
</symbolaut>
</set>
This set contains 3 symbol declarations as found in the 'base1000' subset group. Any of the attributes declared in the 'set' element could alternatively be declared for a specific symbol in the 'asymbol' element. In this case the only attribute which is declared individually for each symbol is the 'picscale' value.
Unlike label styles, the symbol styles are inherited by any subset styles based on the style where the symbol style is declared. So we do not need to re-declare all the symbols in every subset in our custom fontcolours XML file. Instead we only need to over-ride the symbol styles in the 'basevisiblecave' subset, and we only need to declare symbols which we want to change from the style already declared in the 'base1000' subset group. For this example we will change the size of the stream symbol in our custom style group. We want to over-ride the declaration for this symbol in the 'basevisiblecave' subset, which is not currently declared in our custom fontcolours file. So first we need to create a subset declaration for this. We will put this at the top of our subset group declaration.
<subsetattr name="basevisiblecave"> <labelfcol labelstylename="default"/> <labelfcol labelstylename="description" fontname="Times New Roman" size="18"/> <labelfcol labelstylename="feature" fontname="Times New Roman" fontstyle="ITALIC" size="24"/> <labelfcol labelstylename="passage" fontname="Times New Roman" size="34"/> <labelfcol labelstylename="entrance" fontname="Franklin Gothic Medium" fontstyle="BOLD" size="36.0"/> <labelfcol labelstylename="area" fontname="Franklin Gothic Medium" size="36"/> <labelfcol labelstylename="pitch length" fontname="Franklin Gothic Medium" size="24"/> </subsetattr>
Note that we have had to include all our customised label styles because these do not propagate down the subsets tree. By declaring them at every level we can be sure they will render in the same style in every subset.
Next we want to add the declaration for the stream symbol. As this symbol is declared in a set in the 'base1000' subset group, we need to include the set declaration as well. We can copy this directly from the 'base1000' group on the original foncolours.xml file. All we want to change is the size this symbol is rendered on our survey, so we will change the 'picscale' value from 2.5 to 1.6
<set multiplicity="1" buttonaction="overwrite" position="endpath" scale="fixed"
orientation="alongaxis" area-interaction="allowed-outside">
<symbolaut dname="stream" description="stream symbol">
<asymbol name="stream" picscale="1.6"/>
</symbolaut>
</set>
Note that we do not need to include the other symbols in the set, as these will be inherited from the 'base1000' subset group which we have imported into our custom subset group already. If we wanted to change a value declared in the 'set' element then we do need to include all the symbols in the set. Otherwise the symbols we do not declare will still be rendered using the settings in the 'base1000' style. For this example we are going to reduce the spacing of the shading lines used to render puddles and sumps. Again we copy the symbol style declarations from the original 'base1000' style declaration, and then customise the 'picscale' value. Only this time the 'picscale' is declared in the 'set' element, so it will apply to all the symbols in the set. This set also includes the 'hexmud' symbol, so we have included that here, but notice there is another 'picscale' attribute declared in the symbol declaration, so this will over-ride the value specified in the set for this symbol only.
<set multiplicity="fill" position="latticef" area-interaction="trim" buttonaction="overwrite"
picscale="1.5" scale="fixed" orientation="fixed">
<symbolaut dname="puddle" description="water area">
<asymbol name="puddle"/>
</symbolaut>
<symbolaut dname="hexmud" picscale="2.5" description="fractured mud area">
<asymbol name="hexagons"/>
</symbolaut>
<symbolaut dname="sump" description="9x9sump">
<asymbol name="sump"/>
</symbolaut>
</set>
All we have changed here compared to the original declaration in 'base1000' are the picscale values for the set and the 'hexmud' symbol. Finally we might want to customise the way the different lines styles used in our sketch are rendered. We can just copy these from the 'base1000' subset group in fontcolours.xml and then customise the settings in our subset group.
<linestylecol linestyle="centreline" strokewidth="0.312" strokecolour="#ff800000"/> <linestylecol linestyle="wall" strokewidth="2.25"/> <linestylecol linestyle="estwall" strokewidth="2.25" spikegap="7.5" gapleng="3.75" spikeheight="0.0"/> <linestylecol linestyle="pitchbound" strokewidth="1.0" spikegap="6" gapleng="0.0" spikeheight="3"/> <linestylecol linestyle="ceilingbound" strokewidth="1.0" spikegap="6" gapleng="1.5" spikeheight="3.0"/> <linestylecol linestyle="detail" strokewidth="1.225"/> <linestylecol linestyle="filled" strokewidth="0.0" strokecolour="#ff000080"/>
Here we have reduced the line width and spacing of the 'pitchbound' and 'ceilingbound' linestyles to better suit our large cave survey. Here is what the final complete customised subset group declaration looks like.
<subsetattr name="basevisiblecave">
<labelfcol labelstylename="default"/>
<labelfcol labelstylename="description" fontname="Times New Roman" size="18"/>
<labelfcol labelstylename="feature" fontname="Times New Roman" fontstyle="ITALIC" size="24"/>
<labelfcol labelstylename="passage" fontname="Times New Roman" size="34"/>
<labelfcol labelstylename="entrance" fontname="Franklin Gothic Medium" fontstyle="BOLD" size="36.0"/>
<labelfcol labelstylename="area" fontname="Franklin Gothic Medium" size="36"/>
<labelfcol labelstylename="pitch length" fontname="Franklin Gothic Medium" size="24"/>
<linestylecol linestyle="centreline" strokewidth="0.312" strokecolour="#ff800000"/>
<linestylecol linestyle="wall" strokewidth="2.25"/>
<linestylecol linestyle="estwall" strokewidth="2.25" spikegap="7.5" gapleng="3.75" spikeheight="0.0"/>
<linestylecol linestyle="pitchbound" strokewidth="1.0" spikegap="6" gapleng="0.0" spikeheight="3"/>
<linestylecol linestyle="ceilingbound" strokewidth="1.0" spikegap="6" gapleng="1.5" spikeheight="3.0"/>
<linestylecol linestyle="detail" strokewidth="1.225"/>
<linestylecol linestyle="filled" strokewidth="0.0" strokecolour="#ff000080"/>
<set multiplicity="1" buttonaction="overwrite" position="endpath" scale="fixed"
orientation="alongaxis" area-interaction="allowed-outside">
<symbolaut dname="stream" description="stream symbol">
<asymbol name="stream" picscale="1.6"/>
</symbolaut>
</set>
<set multiplicity="fill" position="latticef" area-interaction="trim" buttonaction="overwrite"
picscale="1.5" scale="fixed" orientation="fixed">
<symbolaut dname="puddle" description="water area">
<asymbol name="puddle"/>
</symbolaut>
<symbolaut dname="hexmud" picscale="2.5" description="fractured mud area">
<asymbol name="hexagons"/>
</symbolaut>
<symbolaut dname="sump" description="9x9sump">
<asymbol name="sump"/>
</symbolaut>
</set>
</subsetattr>
Copy this subset declaration into the custom fontcolours XML file you are using for your project. It needs to go into the same subset group declaration that we have put all our custom coloured subsets into. Now when you start up your project in Tunnel and render your sketch using the 'My_Settings' subset style you should see all the changes we have added in your sketch. The stream symbols should be smaller than when using the 'base1000' subset style, and the shading for puddles and sumps should have closer spacing. You should see these changes in any of the subsets we defined with different colours which are based on the 'basevisiblecave' subset in the 'My_Settings' subset group.
