Filename: _Readme_th_CaveProject-SpanishParrot Conventions.txt [sample for Therion forum] --------------------------------------------------- (you may need to view this file with 'word wrap' on) Spanish Parrot is part of the Arthur dataset which was taken from a snapshot of J Ravens CSP model in Apr2013 (prior to Stormy Pot connection with Nettlebed. There has been no attempt at migrating Jonathans subsequent changes to this dataset. These are aspirational guidelines, some are followed in this dataset, others are written here as a suggestion for the direction we should be heading. They are open for discussion if you disagree. They start out describing general information, then specific information relevant to this project. Structure (Generic) ------------------- We aim to produce a somewhat self documenting file structure that contains self documented files. Hence plenty of (concise) commentary is encouraged within the data files. Each cave folder should be self contained, referring only to files within and below it, with two exceptions. 1. In order to maintain consistency of behaviour and appearance across the project we refer to standard Layouts in a folder, \StdFiles, at the top level of the project. This means that the typical project map appearance can be controlled by editing files in one location. 2. Terrain model(s) and surface images are stored in a folder, \Surface, at the top level of the project. The images should cover a larger area than the terrain model, as Therion clips the image to the size of the terrain model. Overland surface surveys are stored with the cave or regional folders in this project. What to store and what not (Generic) -------------------------- While Therion makes many assumptions about the default values (such as projections, survey grade, units, etc etc), we state them explicitly so that the intention is obvious to the user, and as protection against possible future changes in default behaviour. In general we want to store (and track with version control), All electronic data from data collection at source, to that which controls creation of the map outputs Plain text files and bitmap images (png, jpg preferred) at about 100dpi (surface images should be higher resolution to get best results. All metadata (personnel, dates of discovery, survey and authorship, instruments used, copyright, surface survey, entrances etc) that is readily available for each survey, scrap drawing and other Therion entity. We err on the side of entering as much metadata as Therion allows us to collect. This enables the potential for more useful visualisations’ of the cave as Therion's capabilities develop in the future. And AVOID, Non-text files such as MS Word, Excel, pdf etc (these cannot be tracked effectively by version control). Outputs (we have folders to hold them temporarily, but they are expendable and never tracked by version control) Temporary files generated by software Scans of survey notes and photographs related to the cave (while these might be nice to store with the survey data, they are not of primary importance to the map generation, and there is benefit to keeping the versioned dataset size to a minimum). Scans and photos are important however, and tend to be static data, so are better stored separate to our versioned data. Preferred folder structure (Generic) ------------------------- A flat structure is preferred over a deeply nested folder structure. However we will mimic the folder structure that Jonathan has set up for Arthur. Within the th_Arthur project folder we have a branch folder to facilitate usage of bazaar version control software. Within the branch we have Therion files relating to generation of whole cave system maps and outputs, a folder for each cave, and outputs folder and a 'standard files' folder. There are also general information files such as _To Do Issues and Resolutions.txt and this Readme Conventions file. Within each cave's folder, we have an Outputs folder, if there are manual surveys we have a Sketches folder to hold scans of paper sketches, if there are Pockettopo paperless surveys we have a ptopo folder to hold *.top files, archived TEXT and THERION exports from Pockettopo and xvi files generated from *.top files (either by Therion or by Topparser). Name Conventions (Generic) ---------------- Each file is named so that it is descriptive of what it contains, a survey prefix followed by a short English description. Within Therion files, all survey and map objects are named by mimicking the file name and appending standard descriptive words. See http://therion.speleo.sk/wiki/doku.php/drawingchecklist#scrap as an example. See the NZSS Repository/ReadMeFilenaming for details. Files that tie together large chunks of data are prefixed with INDEX (prefixed because this will make them alpha sort together). Files that contain layouts (control how 2d outputs are laid out) are prefixed with Layout. Files that control how a particular set of maps and outputs are compiled are prefixed with thconfig- Therion Survey file structure (Generic) ----------------------------- Therion accommodates many ways of setting up and connecting data files. We put our low level map definitions in the survey.th file at the end, but outside of, the survey-endsurvey block. eg File: 01-Cave.th survey 01 centreline #many of these if changes in metadata within one survey .. endcentreline endsurvey 01 input 01-CavePlan.th2 input 01-CaveElevEXT.th2 map 01-CavePlan -proj plan .. #refer to scraps in 01-CavePlan.th2 endmap map 01-CavePlanCL -proj plan #allows individual survey centrelines to be turned on or off in output maps 01 endmap map 01-CaveElevEXT -proj extended .. #refer to scraps in 01-CaveElevEXT.th2 endmap map 01-CaveElevEXTCL -proj extended 01 endmap #End of file The survey network and map hierarchies are then tied together in INDEX.th files [If I were to start my 'Therion life' again, I would place the map definitions inside of, and at the start of the survey-endsurvey block to promote ease of use and simpler map references in INDEX files. The above structure was intended to make maps independent of surveys (which is preferred), but I did not think it through – to achieve that we would have to have map definitions in separate files. Separate files would work OK, but would increase the number or size of files. At the time, we chose not to go this way. Another time, I might choose differently. Bruce] ---------------------------------------------------------------------------------- Preferred projections and scales (specific to Spanish Parrot project) ------------------------------- plan: 1:500 (but bearing in mind that this is likely to need to be presented at 1:1000 sometimes) extended: 1000 Extended elevations are the main view (because it is a vertical cave), and are defined in a file Extend-SpanishParrot.th It is called from within the SpanishParrot survey in INDEXSpanishParrot.th All extend statements that TopParser places in survey files are to be commented out, and transferred to Extend-SpanishParrot.th. The reason is to centralise and disassociate extended centreline drawing from the survey, and allow future creation of multiple extended elevations of the same piece of passage, using projection indexes. projected elevations: not a focus at this stage, may create at various projections for parts of the cave in future. Have produced some 020 elevations, however these will be prone to errors due to Topparser not having access to the actual precise declination at the time it compiles. Suggest we don't use TopParser for these, and use the method documented for Therion to create projected elevations in future if we want them. Survey and Drawing Conventions ------------------------------ Be rigorous about setting station flags for; entrances continuations, complete with data set out for point continuations here http://therion.speleo.sk/wiki/doku.php/drawingchecklist#points etc Be rigorous about setting survey flags for; surface duplicate approximate Survey markers and cairns: mark natural - use to indicate a natural feature is the survey station ie large pointy rock or stal mark fixed - use to indicate a manmade feature is the survey station ie cairn or bolt Be rigorous about point symbol and label alignments ie be mindful that drawing can in future be compiled at many scales, so placing the symbol point as close as possible to where you want it anchored is required. You can then use the most appropriate of the nine align properties to make sure the symbol or text is positioned as well as possible regardless of the scale eventually used. Text and Labels Use point remark to describe rigging, scale xs (remark is italic by default, and by using 'remark' to describe ONLY rigging, it is easy to switch off rigging display if we do not want it) When rigging is shown, include rigging comment in header map-comment (Use RiggingChangesBranch to track rigging changes with bazaar version control) Use point label scales xs for station-names, dates, altitudes, rigging, minor comments s for comments and pitch or climb labels NOT on main route(s) m (default) for pitch labels, climbs and place names on main route(s) l for significant place names, cave entrances As you work ----------- Refer to and update the _To Do Issues and Resolutions.txt file as necessary (there is not yet one of these for the Arthur dataset). Make sure you update your bazaar commit message as you work, and commit snapshots of your project at milestones or before you make changes you might want to back out of. Before you send patches (if you have repo read-only access) or merge with your trunk (if you are the project owner and have write access to the repo), try to set thconfig files and layout files to produce nice tidy outputs that you would want to find in the central trunk if you were pulling from it. ie don't leave your temporary hacks in the way of other users getting nice outputs. END