The fabled tutorial thread on ViewingDale

I know I promised this tutorial about a year or two ago but now that we had the Jan 2010 challenge and three extra copies went as prizes out I feel compelled to start one now so that the winners can have a go at doing something with it.

ViewingDale is my app and it can be classed as a map making tool, a VTT and a campaign organizer. It is all three tho there are better map maker applications out there, more popular VTTs and other campaign organizers and yet I still feel that it sits apart from anything else so this tutorial is going to cover all three and why I believe that statement to be true.

The app is for windows 2000, and beyond. It is checked on Win2K, XP, XPx64 and I have seen it running well on Vista and Win7 as well as Ubuntu under VirtualBox. The app makes extensive use of the graphics card so it requires one suited to games. NVidia and ATI both being well suited as well as some higher end Intel chip cards & 3DLabs cards too. The app can run without using the graphics card tho its *very* slow. Theres a test program made which is a free download so that you can tell whether your card is suitable and set up correctly for the app.

Little bit of history. I started writing an app around 1991 on the Amiga and it was a vector based line map program. What I wanted was a way to create hierarchies. You make a tree shape and then put several trees together to make a copse, several of them to make a wood, several of them to make a forest. The idea worked but the Amiga being a bit gutless died trying. The problem with that was you have to make every single little shape. By about 2002 I tried again and used images as the tokens instead with OpenGL on the graphics card cos it can shift images about much faster than the CPU.

Lastly in this anecdotal intro, the app is designed to share maps and campaign notes. The whole point of the app is to bring all of your maps together into one giant set and to bring in lots of other DMs maps and put them into one giant repository like the web is for information. I wanted to go anywhere and have it mapped by someone. So given that all the maps drawn by different people would be at different scales the app does not work at any one fixed scale. You never ever need to know the feet per pixel rating of any map or image set for it. Also, there is no complexity limit for the world being mapped and in fact every map is one layer in an infinite set even if that map is the whole world. So one of the design aims of the program is that it can take bits of mapped areas and allow people to connect in and transfer missing bits on their machine from the one who has them. To do this it uses a very efficient method to store the maps. It turned out to be so efficient that you can make changes to the map and connected clients got real time updates and it became a VTT at the same time.

So assuming that you have a boxed disk in front of you ill start with installation and set up.

If you get a download or a boxed disk then you will get an installer which is a standard windows exe installer app. You can install the app anywhere on the PC but I would recommend putting it into a place that has several gigs of free space on it for all of the accumulated art. ViewingDale stores its art in files under the apps main directory. You can divert this to a different place by editing the configuration file but thats not usual.

Before you install its a very good idea to uninstall the trial version that you might have downloaded. The two are not compatible.

When it is installed it will normally put a launch icon on the desktop and a shortcut in the start menu. When you run the app it will load the last map you were looking at or the index page for the first time run. The index page is blue with some circles and text on it.

http://www.viewing.ltd.uk/Temp/CG/VD...dexPage_TN.png

The circles are links and they will take you to other maps such as the island map that it comes with or the help pages which are all in ViewingDale format. When you see this page its quite possible that your circles are not circular but elliptical and it all looks a bit squashed. This would be true particularly on wide screen monitors. We need to fix this.

ViewingDale works is real world scaling. To get that you must calibrate it to your monitor and this is done by measuring accurately your monitors drawable area in mm. Thats right to the edge of the screen not the window its running in. If you do this and have the width and height then you can use the "Start" button and hit the System Settings button and then the "Screen Width in mm" and "Screen Height in mm" and enter the values in. When finished the page should have exactly circular jump icons on the index page.

http://www.viewing.ltd.uk/Temp/CG/VD...ttings1_TN.png

If you happen to be using a large screen or a small screen such as either a projector or a micro tablet PC then it might be a good idea to enter the widths or heights in stages as it will change the screen progressively each time and it might be too squished if you go in one giant step. If you really get stuck then you can close it, edit the configuration file and restart the app. If you are using a projector down onto a table with miniatures then its an especially good idea to enter correct values as then all the maps will always be the correct scale for your miniatures with no more scaling - ever.

If your running a single desktop over multiple monitors then put in the value for the multiple monitors. The app copes well with spanning over multiple monitors providing your using one graphics card driving them or hardware connected cards in SLI mode or whatever fancy setup nVidia has come up with this year.

You should also check your graphics card specs and enter in the amount of RAM it has on it into the system settings menu item for it too. The more RAM your graphics card has the better it will run. I would say 8Mb is absolute minimum, 32 Mb or more is recommended but having 64 or 256 is better. There's a diminishing advantage beyond about 256Mb.

Thats the setting up done. Ill cover patching up next so we can get that out of the way.

On the website there is a download under the support menu for "Versions and Patches". The download gets you a zip file and within is an installer. You can run the installer out of the zip if you want to. It will install a new directory under the main viewingdale install directory called VersionControl. It will probably have put an icon on the desktop which looks like a band aid sticky plaster.

Ensure the app is closed, run the plaster icon by clicking on it. Or go into the VersionControl dir and run the ViewingDalePatcher.exe.

It will analyze what you have and find suitable patches for it and move your app up versions until it gets to the latest. It stores the old set in a directory so you can revert back if need be. It may add extra applications for you too as and when they get developed.

Once finished you can run up the main app and hit the big Menu button and then "About ViewingDale" and it will tell you what version you are running.

Since version 1.03 there exists an x86 and an x64 version of the app. The x86 is the normal 32 bit standard version. The x64 looks and feels exactly the same but is complied for native 64 bit OS'es like XPx64, Vista64 and Windows7 64bit. My recommendation is if your not sure then use the normal 32 bit app but the 64 bit one on 64 bit machines is slightly better only in the increase in memory capability when saving huge bitmaps. Otherwise its exactly the same.

Moving the mouse you will see that most of the time its in the shape of a cross. If you click with the left button then it centers the page on that point. With the right button it grabs the page and slides it around changing the cursor to a hand shape. If you move the cursor over a hot spot circle then it will change to a pointer. When you click with the left button the type of hot spot does different things. Ones with an arrow in like those on the index page are jumps to new map pages. If you click inside the one for the introduction to basic features then it takes you to a new page. Also you will see that a new box appears in the top right corner. This is the jump stack and shows where you have come from.

You need to know how to move around using keys too. The cursor keys pan and the Page Up / Page Down buttons zoom. The Home key centers the page to fit. The backspace key jumps you back up the jump stack - i.e. taking you to the previous map shown. It puts you at the position and zoom that you were at when you jumped from that map.

http://www.viewing.ltd.uk/Temp/CG/VD...veKeys1_TN.png

With the boxed set you get a laminated card showing all the keys. Actually there are a few more than this now that its progressed a few more versions.

http://www.viewing.ltd.uk/Temp/CG/VD...llKeys1_TN.png

As stated on the image the mouse wheel does zoom too. Another tip is that clicking with the mouse inside the jump stack can take you back to any previous map instead of using the backspace button multiple times.

As you pan and zoom you will see the title bar change its position and scale. The position is in the current units which I will talk about later but it starts in meters. The scale is shown as though you are at 1:X i.e. when it says 60 thats 1:60 scale. Or say 1 inch on screen = 60 inches in map which is 1 inch = 5ft map scale. If you have calibrated your app to the monitor as discussed in the previous message then the scale is real. I.e. if it says 1:1 then what you see on the screen is actual size.

Theres a similar section in the help files within the app covering this but its probably a good thing to reiterate it as its so vital. Incidentally, all the help is in ViewingDale format as is all of the artwork used to make the laminated card, insert, and box cover.

As you recall from the intro what were after is a mechanism to have the whole world at your fingertips and we would like to be able to reuse those tree icons to make copses, woods and forests. What were building here is a hierarchy.

The main view looks at a map. Actually your looking at one layer in an infinite set. This layer is called an icon. An icon is just a bunch of a small set of parameters one of which is a reference to an image. The image is whats shown on the screen and its sized to extents which are parameters in the icon. So you can have two different icons with the same image. I.e. you can have a small chair and a giant chair. Two different icons using same image. Most of the time you have one icon per image because many of the icons are so unique but things like arrows, lines, circles and so on have many icons for the one image. The other thing that an icon has is a list of child icons attached to this one. I.e. for an icon of a village it might have a list of child icons, one for each hut in it. Those child icons are listed with their position, scale and rotations for each one.

So we can have a Forest which has 3 child icons each of type Wood and those have positions and rotations so that they are next to each other making up a little group.

Now if the Wood icon happens to have 6 children called Copse arranged in a little group also then when you view the Forest then it will show its icons image, 3 Wood images and 18 Copse images. And it goes on and on like that. If you add another Wood to the forest then the forest icon gains one more child but 6 more Copse images are also shown.

So the ViewingDale app has controls to edit the icon size, add and remove child icons and to position, rotate and scale the child icons on the main one.

So lets run that again one more time because understand this and its all plain sailing...

Here is a table, a plate, a bowl, a spoon, and some liquid for the bowl. These are images and lets say you have the icons for them that make them all the correct real world size. You put them all down on some surface in this case a white wonderland...

http://www.viewing.ltd.uk/Temp/CG/VD.../Stack1_TN.png

If you drag these icons over one another then they stack up in size order. You don't get to control the Z order. Small things always go on top of larger objects. Theres a good reason for that which I will show later. You can see also that these images include the transparent background which were all familiar on these forums. The icon size includes the transparent bit so if you really must then you can add more transparent edge to an icon to push it down but that doesn't happen all that often.

Ok so now we have white backdrop with 5 child icons on it whether in a line or stacked up.

If we change the situation so that we make the spoon a child of the plate and the liquid a child of the bowl and call these two new icons Plate_with_Spoon and Bowl_of_Liquid then we can make these two children of the table. Then the white backdrop can have one child of table like this.

http://www.viewing.ltd.uk/Temp/CG/VD.../Stack2_TN.png

Now if we edit the table icon and move, scale and rotate its Plate_with_Spoon then note that the spoon rotates with the plate, scales with it and moves with it. The spoon is now as though its part of the plate even though its a child of it. In other words the whole hierarchy under the edited icon takes on all the changes to it.

So we can pick up that Forest and move it and all the Woods and Copses move with it, scale with it and rotate with it.

And now you can see that if we make a general village with some huts in it all laid out nicely, then we can use that village in several maps with different rotations and scales and yet at the same time on each of them we could still go in and edit that village and move the individual huts about.

So grouping icons logically in a sensible hierarchy is vital. Putting a hut on a continent is not sensible. You need a set of layers that go from world down to battle map so that at some point there is a region, a village and then you put your hut on that. ViewingDale has various features to make that easy though you can ignore it all and make something unmanageable.

So as you can see were predominately concerned with editing icons and apart from the Normal View mode, there are three more to help out in this regard. These are the Edit Child Mode, the Origin Mode, and the Edit Size Mode which look a little like this:

http://www.viewing.ltd.uk/Temp/CG/VD...wModes1_TN.png

Origin first as its easy. This mode allows you to set the origin for the current icon. You click with the mouse and it puts the red origin marker down at that spot. This is the point where the icon rotates around or snaps to the grid so its handy to put this in a sensible position like middle of dragons body or hilt of sword or center of pot etc.

The Edit Size mode allows you to change the size of the current icon. The icons is laid out on a grid and you use the arrow keys to stretch it over the grid. The grid dynamically changes scales and the current size is shown on the title bar. In the image this is one big light blue square of 0.1m and 2.5 of the darker finer grid which is 0.02m so thats 0.15m x 0.1m. There are red corner markers showing the extents.

The Edit Child Icons mode allows you to add, remove, move, scale and rotate a child icon. You must keep all of your child icons within the extents of the main current icon. You can grab a child by clicking and holding down the left mouse button inside the red circle handle for each child. From there you can drag it around. If you click inside the green circle handle then moving the mouse will rotate the child towards the mouse. If you grab the child with either red or green and then press + or - key it will scale it off of its default size and if instead you had pressed 0 (zero key) then it snaps the size back to its default. Each child icon has a rectangle around it in red to show its extents including any clear parts to its image.

To add a child you can press 'C' and from the normal view mode it will take you to edit child mode and bring up a file selection box to pick one. If you grab a child and press the Delete key then it removes it. You can also press and hold the delete key down and then move your mouse over a handle and it will delete all in its path that fall under the cursor for more rapid clearance of areas.

Once you have a child grabbed by the red handle you can drag it about. If whilst doing so you press 'C' key then it clones it and drops a copy at the point you pressed it whilst dragging. So you can grab a goblin, and drop clones of them down where you need them. The clones take on the currently dragged goblin scale and rotation too. Once dropped you can go and rotate them or reposition them as you would any other child.

On newer versions you can grab a child and press 'X' or 'Y' to flip in X or Y. Flip is like all the other properties in that its replicated down through the hierarchy below it.

Ok thats icons done to death what about images ?

ViewingDale uses a custom image file format for a number of reasons but the main one is performance. The data is reformatted so that it can display them very fast. Its also adds some tags to the images not present in any of the file formats so that when the app is run it does not have to work these out each time. Anyway suffice it to say that you gotta get your image into VMI format. The app has a built in converter.

By pressing F2 you get the Icons and Images menu and on there is the Import Image option which gives a dialog like this:

http://www.viewing.ltd.uk/Temp/CG/VD...Import1_TN.png

You have to load in a color and a transparency image or you can load in a PNG file with both color and transparency. Either way, it will show the image seperated into its color on the left, transparency in the middle and combined on the right. You can import a BMP, JPG or PNG file. You can try a TIF file too and it might work. You can use any image from very small to very large tho if larger than 2048 square then it will resize it down. In fact it will usually resize the import anyway but its very generous and almost always upsamples it using a good algorithm so you don't notice. Anyway, once you have something correct on the right panel you can save that image. It asks you for a name and a directory to place it into. The directory will always be under the Images base directory. ViewingDale will not make icons out of images outside of its directory structure. Theres a good reason for that too... later.

So you should be able to save an image as a VMI file.

There is an app that ships with it which is the batch PNG file converter which will change over a whole directory and subdirectories of PNG files into VMI files. You still need to make icons for them all but at least half the work can be automated.

Thats about all there is to know about images.

There are several ways to create a new icon. The first and most obvious is to tell it which image to use. That can be found under the Menu / Images and Icons or by pressing F2. From there you will see an option "Create New Icon from an Image". With that you run through a sequence of dialog options where it asks you for the name of the new icon then asks where you want to save it then it brings up a similar file selection box where you select the image to use and then it creates that icon for you. Unfortunately it creates it with the origin in the middle and at 1mx1m which is not always the best. The idea is to then edit it and resize it up to be correct.

http://www.viewing.ltd.uk/Temp/CG/VD...sAndIcons1.png

But maybe you knew all along how big this icon was supposed to be. There is now a wizard where you set the name and image to be used and you set the width and height and whether the origin is in the middle or bottom left corner. Most people use this one now because even if you have to edit it your normally closer to where its supposed to be.

There is another option where you can create a new icon which is a clone of an existing icon. With that option you can, for example, take an icon of a chair and make a new one called giantchair and then point it at chair and it will make a new one with same image and same size and origin. Then you can edit it so as to make it much bigger. Then you have two icons sharing the same image but of different sizes. This is also useful when you need different child icons for the same main icon or image. Another good reason to use this option is when you have say an Inn and want to put it down on a city. If you place that Inn down directly then any modifications to that inn will be done across the world. If you clone it you can call it something specific like "TheGreenDragonInnInWaterdeep" or whatever and then it will be unique.

Lastly you can take a screen capture as the image and make a new icon. You supply the name but the size is taken from the screen scale so that its exactly correct to match up with the current view. This is especially useful when you have say a few huts on a regional map and you want to make a new village map and get those huts down onto their own map. You can take a screen shot covering the village, add the huts to that new icon lining them up with the backdrop image then replace the backdrop image with a clear image and put it back on the map. Delete the old huts and allow the new ones to show from the new icon.

There's one more special option. You can create a Contact Sheet of all the icons in a directory. It makes a new clear icon and add one of each icon you have in the selected directory and labels it for you. It names the icon _contactsheet so you will find it at the top of all icons in that directory.

On that menu there is the option to load an icon. Thats the 'L' key and just loads an icon from a file selecton of icon files.

There is no save. ViewingDale saves everything all the time. There is an undo for the child edit by pressing 'U' but normally all actions are done and saved instantly.

The refresh is rarely used as this is only useful if you externally edit a file like an icon text file using a text editor and then you can refresh the screen.

The images and icons are stored as files in directories under the main installation dir. If you pick these file up and move them then they will be badly referenced from child icons or icons will call up bad pathed images. So in order to move these files and fix up all the references to them there are two options to move an icon or move an image. You should use these if you really need to or else you could find yourself looking at text file references to fix !

You can change the current icons image with an option here which can be quite useful.

Set the icons size means to do what the Edit Size mode does only with numeric input. So you can specify that this battle map is exactly 100 yds by 200 yds for example.

Adding a child icon we mentioned earlier.

There are the special icons you can add. The main one is text. By pressing T you get an edit box where you can type in some text, select its color and it will appear as a child icon on the current icon. When editing it you will note that it does not have a green handle because text always rotates so that its horizontal. You must remember that all icons in ViewingDale may be used multiply and in different orientations and scales. The extents box for text is thus circular to depict where text might possible lie at any rotation.

Next on the Child Action types is a jump. You can put down the blue and yellow marker with the arrow on it and select another map to jump to. This is useful for going up stairs entering buildings or just having a list of maps to index.

You can add a link to a document too. That can be a text file, a doc, rich text or whatever. You can set the document reader so if all your docs are PDF say then thats ok too.

Theres picture links too of course. By default the app is tied to the ViewingDale Picture Viewer which is a super fast simple image display. Again tho, you have the option of opening with any image viewer that can take a command line parameter for the image to look at.

You can add a sound link as well which can add some atmosphere to your gameplay.

Next is a web link where you can link to any web page like this one !

Finally there is a general file link. Some caution here is that it will launch whatever file is behind the link. That might not be a good idea if you get the map from someone you dont trust. But there is the possibility that you can run your own program or something unusual.

You can check out some of the links in the demo download. In that mini map is a link to text, a picture, and a jump to another map.