Command of the Week - File Paths (Week 10)

MonsenMonsen Administrator 🖼️ 46 images Cartographer

Index

  1. List (Basic)
  2. Symbols Along (Intermediate)
  3. Fractalise (Intermediate)
  4. Edit Text (Basic)
  5. Link with Map/File (Intermediate)
  6. Offset (Intermediate)
  7. Measuring Tools (Basic)
  8. Change like draw tool (Basic)
  9. Modifiers (Intermediate)
  10. File Paths (Intermediate)
  11. Complex Shapes [Combine Path] (Intermediate)
  12. Complex Shapes [Multipoly] (Intermediate)
  13. Break (Intermediate)
  14. Map Notes (Basic)
  15. Coordinates (Intermediate)
  16. Macros (Advanced)
  17. Search Files for Text (Basic)
  18. Text Justification (Basic)
  19. Mirrored Polygons (Intermediate)
  20. Managing Drawing Tools (Intermediate)
  21. Named Views (Basic)
  22. Symbol Lookup Sheets (Intermediate)
  23. Symbol Catalog Settings (Advanced)
  24. Symbol Catalog Filters (Advanced)
  25. Symbol Control Points (Advanced)
  26. Define Symbol (Intermediate)
  27. Curves (Basic)
  28. Selections (Intermediate)
  29. Sort Symbols in Map (Basic)
  30. Extract Properties (Basic)
  31. Convert File (Basic)
  32. Get Extents (Advanced)
  33. Quick Move (Basic)
  34. Menu Editing (Advanced)
  35. Trace (Basic)
  36. Array Copy (Intermediate)
  37. Explode (Basic)
  38. Clipboard Copy (Basic)
  39. Rename & Reorder (Intermediate)
  40. Drawtools Edit (Basic)
  41. Trims (Basic)
  42. Symbol Attributes (Intermediate)
  43. Fill Style Selection Mask (Basic)
  44. Browse Files (Basic)
  45. Node Editing (Intermediate)
  46. Automatic Sheet Selection (Basic)
  47. Scale (Basic)
  48. Text along a Curve (Basic)
  49. Shaded Polygons (Intermediate)
  50. Fill with Symbols (Intermediate)
  51. Global Sun (Basic)
  52. Symbols in Area (Intermediate)
CC3+ contains a huge amount of various commands and features. This series highlights a number of these. There won't be any special progression to this series, and the command will be selected from the entire range, from the simple basic commands, to more advanced features intended for the more advanced users. Feel free to use this topic to discuss the command presented.
This series is called the command of the week, but it could also explain a feature. The explanations will tend to explain the technical parts of the command, and is intended to highlight the basics (and complexities) of the command, and information about how to use it, but won't be a detailed tutorial. It is up to you to use it creatively in your maps.

Week 10 - File Paths

For basic maps, you don't really need to know where the various files your map needs are stored, since references in the official ProFantasy symbol catalogs and templates are already set up correctly. But once you start adding additional resources to a map, for example using custom symbols, importing fill style from other styles, or inserting images into your map, file paths become very important. It is these file paths that tells CC3+ where to find the resources needed in your map. If you don't do this correctly, everything will work fine right now, but you will soon get into problems when you try to open the map on another computer or share it with someone else if this isn't handled correctly.
For example, say you insert an image into you map from your documents folder, called image.png. The path to this file on my computer would be C:\Users\monsen\Documents\image.png. If I used this path for the image in CC3+, and then gave the map (and the image) to someone else, for it to work, they would actually have to make the C:\Users\monsen\Documents\ path on their computer, even if their username isn't monsen, because that is where the map tells CC3+ to find the resource. Some people may also keep their images on the D :-drive, while others have the D-drive as their DVD-Rom drive, where they definitely can't simply copy in some files for use with the map. You could also experience the same problems yourself if you switched to a new computer with a different setup.
To avoid problems like this, we need to be aware of how to use file paths when we use external images in CC3+. Typical external resources includes fill styles and inserted images, as well as images used as part of effects. With regards to symbols, their path is set in the symbol catalog that contains them, so this is very important when creating a symbol catalog, but you don't need to think about this when using symbols (assuming the symbol catalog was correctly created int he first place

Absolute Path

An absolute path is a path that points to a specific location on your disk, such as C:\ProgramData\Profantasy\CC3Plus\Bitmaps\Tiles\Dungeon\Mike Schley\Brick Grey.PNG or d:\mysymbols\dungeons\rock.png
These kind of paths are generally very bad for the portability of the map, since the recipient must have the files in those exact locations. For example, if the user of that computer chose to put his CC3+ data directory on d:\CC3Plus instead of the more common c:\ProgramData\ProFantasy\CC3Plus, those resources wouldn't work on that computer, and the symbols/fills would show up as red X'es, even if he had the correct add-on installed. Suffice to say, these kinds of paths should always be avoided

Relative Paths

A relative path is a path that is relative to something else. For example, a you can indicate that the fill bitmap is located in the same folder as the map itself, meaning that the recipient can put the map you shared with him wherever he want, as long as he put the fill bitmap in the same location. It is also possible to put files relative to the CC3+ installation directory and the CC3+ data directory. The latter is used in all ProFantasy template and symbol catalogs to ensure that everything works fine no matter where the users chooses to install CC3+.

There are three types of relative paths:

Relative to data directory

Paths relative to the data directory always starts with the @-symbol. CC3+ knows that this symbol refers to the location of your CC3+ data directory, no matter where that may be. For example, if you start a new map in the CC3 Standard Overland style, and click the fill style indicator, and activate the bitmap files tab, you can see that the path for all the fill styles here start with @Bitmaps\Tiles\Overland. The @-symbol at the beginning tells CC3+ to go look in the CC3+ data directory, no matter where that may be. The rest of the path just refers to the directory structure inside the data directory. So, if your data directory is the standard c:\ProgramData\ProFantasy\CC3Plus, CC3+ will translate that path to c:\ProgramData\ProFantasy\CC3Plus\Bitmaps\Tiles\Overland. On someone elses computer, CC3+ might be installed to e:\mappingSoftware\CC3P, and in that case, CC3+ would translate the path to e:\mappingSoftware\CC3P\Bitmaps\Tiles\Overland
So, no matter where CC3+ is actually installed, the @-symbol will refer to the data directory.

Relative to installation directory

For those of you who have used version of CC prior to CC3+, you may remember that it didn't have a separate data directory, everything was stored in the installation directory instead. The reference for something relative to the installation directory is the #-symbol. Except for a different symbol, it behaves exactly as the @-symbol above, only that it points to the installation directory instead.
For CC3+ you should NEVER use this, as there is nothing of interest in the installation directory anymore, all resources was moved to the data directory. However, you may find this reference in older documentation. Usually, you can just straight swap it out with the @-symbol when applying these older instructions to CC3+.
Also note that for compatibility reasons, if CC3+ sees the #-reference, and the file it points to is not found in the installation directory, it will look for it in the data directory instead. This ensures that old CC3 maps works with CC3+. However, when this fallback occurs in CC3+, it won't be able to reference the four different resolutions of each image, but only the specific one the reference points to (resulting in slow redraw if it points to the VH one, or poor textures if it points to the VL one), so unless you need to keep map compatibility with CC3, DO NOT use this reference in CC3+, and always replace it as you encounter it.
Note that the FFIX command can be used to replace all the # references in a map.

Relative to the map

Generally, resources are used by many maps, so it makes more sense to keep them in your CC3+ data directory, but for easier distribution and sharing, you can also keep resources along with the map.
To do this, use the $-symbol. This behaves in the same manner as the above path references, except that it always refer to the directory the current map is in. So, if an image reference in a map is $images\tree.png it means that the image is in a subfolder called images, which is located in the same folder as the current map. This is a good way of handling resources if you intend to distribute a collection of maps, you can simply have a subfolder with all the resources in.

Where to I see/set these paths?

There are multiple elements in CC3+ that uses paths, let us look at them

Fill Styles

If you click the fill style indicator in the top left, and go to the bitmap files tab, you should see something similar to this screenshot. The left dialog correctly uses a relative path (relative to the CC3+ data directory), the right dialog shows an absolute path, which means that this will will not work for anyone having installed CC3+ to a different lcoation than the default. Note that CC3+ will not make the path relative by default when you use the find button to browse for the texture, you MUST fix this yourself.

Inserting Images

When you go to Draw -> Insert image, there is a Bitmap Options button. Always click it, and make sure to set the option to make the path relative to either the drawing or the CC3 path (for CC3+, this refers to the data directory, not the installation directory), depending on where you keep the image. Note that CC3+ will only be successful if it is possible to refer to the image using a relative path. For example, you can't make it relative to the CC3+ data directory unless the image is actually located inside that directory somewhere. It is therefore very important to store your images and other resources in proper locations.

Hotspots

If you want to link your maps together in an interactive atlas, or link to external files like map notes and such, you should always keep these resources along with your map, so that you can use the $-reference. Feel free to use subdirectories. Keeping a directory structure and using $-references ensures that the links work fine no matter where you move your atlas.
Note that when you make hyperlinks using the Link with map feature, CC3+ will try to make it relative, but it doesn't always find a relative path, so sometimes you need to edit the hotspot with numeric edit and change the path yourself.
The image below shows three hyperlinks in the Ezrute map. The first one is a link to another map in the same directory, the second one shows a relative link that moves out of the current directory (the .. symbol), and then into another directory to access a map there. The third one is an absolute path. The first two will work wherever you move the root folder as long as you keep the internal directory structure intact, while the last one will fail once you move anything.

Importing Symbols

When you are creating symbol catalogs, and go to Symbols -> import pngs, the dialog will have an option like the one described for inserting images above. So even if the path shown in the dialog is an absolute path, CC3+ will convert it, assuming the correct option is set and the images are stored in an appropriate location. You should ALWAYS keep the images for your symbols somewhere inside the CC3+ data directory, such as @Symbols\User\MySymbols\Buildings

Importing fill styles

The same rules applies to importing fill styles (Draw -> Import bitmap fill styles) as for importing symbols above. Fills styles should generally be put in a folder under @Bitmaps\Tiles

Where should I keep my files?

Because of the huge advantages using relative paths gives you, you should usually always keep files intended for use with more than one map inside your CC3+ data directory. Don't be afraid to make your own subfolders. Some people like to keep their images in different locations, such as a network drive for easy backup and so on, but if you do, consider that a backup, always keep the copy you actually use inside your CC3+ data directory, never reference files in other locations from your maps. This can save lot a lot of trouble when you share your maps or change to a new computer.
If you have files that are only used by a single map, such as a special background image or similar, keep it in the same folder as the map, and use the $-reference in the path.

Comments

  • Something like collect (or package) from Adobe InDesign could be of great help here, imho.
  • LoopysueLoopysue ProFantasy 🖼️ 39 images Cartographer
    Its very easy to just dump all the textures you make in a folder called USER within the Bitmap folder in CC3, or another one called USER in the SYMBOLS folder, and then use relative paths from then on. All you have to do to share your collections with anyone else is send them a zipped up USER folder and tell them to unzip it directly into the Bitmap or SYMBOLS folder on their own machine. It won't matter, then, where they save their copy of your map file (the FCW) because it will always find the textures and symbols you made for it.

    Thanks for clarifying these issues Remy. Your weekly tips are excellent support. I've bookmarked all of them :D
  • JoeyD473JoeyD473 Betatester 🖼️ 2 images Traveler
    I agree keeping in a users folder. But I personally make sub folders for sorting of symbols and textures so its easier for me to know what is what
  • LoopysueLoopysue ProFantasy 🖼️ 39 images Cartographer
    I have a whole infrastructure of folders within both my USER folders. They're useful in the Symbols User folder, but critical in the Bitmap folder, or you end up loading about 50 bitmap fills you don't want or need in that particular map along with the 5 that you do ;)
    moskthescribe
Sign In or Register to comment.