Spud thoughts

[Philip Underwood]

A selection of thoughts regarding the data structures needed for spud.

The data we potentially get coming in...
   Surveys, consisting of 
      Calibration details
      Date surveyed
      People surveying & instruments
      Leg descriptions
      Station descriptions (eg LRUD, and GPS fixes(for entrances/ other       
                            location data))
      Sub-surveys (eg bits done with different calibrations (such as          
                   tapeworm))
      Graphical data 
      Other comments
      Stations & legs can also have comments
   Linkage data (*equates under survex, also grouping surveys together)
   Terrain data (eg Map overlay)

Plus interactive data added whilst running the program (e.g. reversing 
sections on an extended elevation)

I would propose a data structure similar to the following(using STL)...
Note that this is aimed at being able to use survex files with a minimum of 
fettling. In particular, I am aiming to keep the station/survey naming 
hierarchy style. Note that I haven't approached Terrain data, or graphical 
data. I would see both of these as being implemented via plug-ins. This is 
more of a cue for discussion rather than my strongly held belief - there will 
probably be many items which would benefit from changing, but I see the 
general structure being similar to this.

class Unit;
class DataSet; //a wrapper holding everything else;
class Survey;
class Leg;
class Pos;     //an actual station - a 3d point
class Station; //a reference to a station - one pos can have many stations,   
               //but not vice versa
class PassageDimension; //a stick extending from a station to the passage
                        //wall e.g LRUDEs or shaft dimensions
class ext_data {}; //empty class, root for extension data

typedef LIST<Station> StationList; 
typedef LIST<Station*> StationRefList; //a list of pointers to Stations
typedef LIST<PassageDimension> DimList;
typedef LIST<Leg> LegList;
typedef LIST<Leg*> LegRefList; //a list of pointers to Legs
typedef LIST<Survey> SurveyList;
typedef LIST<string> stringList;
typedef VECTOR<ext_data*> ExtraData; //list of pointers to data added by
                                     //plug-ins

class Unit {
  public:
     char measure; // 'm' for metres 'f' for feet 'd' for degrees etc
     double zero_error;
     double scale;
     double sd;
}

class DataSet {
  string filename;
  Survey *root; //root Survey of dataset
  stringList comments;
  ExtraDate extra_data;
}

class Survey {
  public:
     string name;
     string authors;
     string instruments;
     string orig_file; // if we are keeping copies of original files this is  
                       // the path to it
     int date_day;
     int date_month;
     int date_year;  // these date bits should probably be more compact
     Unit length;
     Unit horizangle; //units used for horizontal angles (compass)
     Unit vertangle; //units used for vertical angles (clino)
     Survey *parent; //one up in Survey tree. NULL if root
     StationList stat_list; //stations used in this namespace
     LegList leg_list; //legs defined in this Survey
     SurveyList survey_list; //List of child Surveys
     stringList comments; //list of comment lines
     ExtraData extra_data;
}

class Leg {
  public:
     string text; //the text line describing this leg
     string comment;
     Survey *parent;
     Station *from, *to;
     Pos *from_pos, *to_pos; // these are not technically necessary, but      
                             // could help speed up some code...
     double d[3]; // dx,dy,dz as described by the text
     ExtraData extra_data;
}

class PassageDimension {
  public:
    double d[3]; //offset from station to wall of cave in dx,dy,dz
};

class Station {
  public:
    Pos pos;
    string name; 
    string text; //the text line (if any) describing this station
    string comment;
    LegRefList legs; //legs conencted to this point
    ExtraData extra_data;	
}

class Pos {
  public:
    double p[3]; // x,y,z coordinates
    DimList dimlist; //LRUDE / shaft dimension data for this point
    StationRefList aliases; // names for this position
    ExtraData extra_data;
}

The ExtraData allows plug-ins to add new data to the data structure. Other 
plug-ins could then share this info. It could be argued that the 
PaassageDimensions should be done in this way, as there is not yet any code 
available either for reading in LRUDs or for displaying them with Survex. 
This would instead be done as follows...

class PassageDimension: public ext_data {
...
}

The plug-in that reads this data in registers "PassageDimension" as a data 
extension to Pos when spud starts up. It is given a number in return, which 
could be stored as a global variable pass_num.

One could then access a PassageDimension record by...
   PassageDimension*(mypos->extra_data[pass_num]);

A completely different plug-in could access the data by say...

   int my_pass_num = spud_get_station_data_index("PassageDimension");
   PassageDimension* myLRUD = PassageDimension*(mypos->extra_data[pass_num]);



--
Phil Underwood <furbrain@furbrain.screaming.net>
Fighting disease, illness, and little flaky bits throughout the North West.
--