CORTOOLS Automatation Server

Overview

CORTOOLS.DLL is an OLE "automation server" that allows scripting languages like Visual Basic, perl, and others to access CORSIM binary files.  Specifically, CORTOOLS allows scripting languages to access portions of the TSD file (the VEHICLE and SIGNAL messages), and the entire TID file (the LINKMOE messages).

CORTOOLS.DLL defines two primary automation (OLE) objects: tsdReader and tidReader.  These objects encapsulate the corresponding TSD and TID files created by CORSIM, and allow any scripting language to sequentially access the binary data stored in these files.

Required Files

• CORTOOLS.DLL (Size: 341504, Dated: Sun Aug 17 16:47:27 2008)

Installation

1. Download CORTOOLS.DLL.  It doesn't matter where the file is stored.  I suggest either c:\winnt\system32 or the TSIS program file directory.
       
2. Register the DLL with Windows by running REGSVR32.  Try something like the following:
   
   >> c:\winnt\system32\regsvr32 cortools.dll
   
   This will register the DLL with the operating system and allow other programs to access the objects.

Using CORTOOLS

Once installed, any scripting language can gain access to the utility objects maintained by CORTOOLS.  CORTOOLS has been tested using Visual Basic (within Excel) and perl (from the command line.)  The CORTOOLS library contains several COM objects.  The following describes these objects and their properties.

General Implementation Notes

In general, the following steps are necessary to use either objects:

1. Create object
2. Assign file name (full path) to object.  Check to see if the file opened.
3. Process data from each time step until out of data.

Note subtle differences in the property names in the TSD and TID files.  I've tried to be consistent, but as I worked with the TSD object, I learned new tricks that were incorporated into the TID object.  Also,  I added an EOF property to the TID object so that it's use looked similar to ADODB record access.

tsdReader Object (and friends tsdLink, tsdSignal and tsdVehicle)

This object encapsulates the data in a TSD file and provides scripting access to various data elements within the file.  The contents of the TSD file are documented in the "TRAFVU File Description Document" available on the FHWA-TSIS web site.  As documented, the tsdReader object provides access to the "Vehicle" and "Signal" messages.  It does NOT provide acess to the "Incident" and "Ramp Meter" messages within each time step.

tidReader Object (and helper object tidLink)

The tidReader object encapsulates the MOEs stored in the Time Interval Data (TID) file. The TID file contains cumulative MOE data for each link in the CORSIM data file at the end of each interval.  The time interval size (in seconds) is set on RT4 field 2.

Visual Basic Example (processing VEHICLE messages)

The following VB code demonstrate how to use the TSD reader object.  In this example, we will create a file that contains all attributes of vehicles traversing a selected link.   To see this code in action, download the excel spreadsheet demo, provide it with a name of a TSD file and the desired link to track, the press the "run" button in the spreadsheet.

' Create TSDReader object and open a file

Set TSDReader = CreateObject("cortools.tsdreader")
TSDReader.tsdFileName = "d:\tsis projects\corsm1 example\corsm1.tsd"

' Loop over the entire file.  tsdReadNext loads the data
' from the next entire time step.  It returns TRUE if there is more
' data to read.  When it returns FALSE, there is no more time steps
' to read, however, it still HAS read the current time step.

Count = 0
Do While TSDReader.tsdReadNext

' The following statement stores the current simulation time

  Time = TSDReader.tsdTime

' Loop over all links for the current time step.  tsdReader.tsdLinkCount returns
' the number of links in the current time step.  The method tsdReader.tsdLinks(i)
' returns "ith" link as a "variant" object.  This object contains the link ID and
' a list of all the vehicles on the link during this time step.

  For i = 0 To TSDReader.tsdLinkCount - 1

' Get the current link as an object.

    Set tsdLink = TSDReader.tsdLinks(i)

    up = tsdLink.linkid \ 10000  ' Or directly with tsdReader.tsdLinks(i).linkid
    dn = tsdLink.linkid Mod 10000

' If this is the link that we want vehicles data from continue, 
' else, get another link

    If ((up = UpNode) And (dn = DnNode)) Then

' tsdLink.LinkVehCount returns the number of vehicles on the link during
' the current time step.  Each vehicle may be referenced as using the method
' tsdLink.linkVehicles(j). This method returns a vehicle object as a variant.

       For j = 0 To tsdLink.LinkVehCount - 1

          Count = Count + 1
          Set veh = tsdLink.linkVehicles(j)

' The following statements tranfer the data from the TSD file objects directly
' to cells in the spreadsheet - one line per vehicle per link per time step.
' Once gathered for a link, these data may be used to create time-space vehicle
' trajectory diagrams, frequency distributions of velocity-accelerations, etc.

          ActiveWorkbook.ActiveSheet.Range(Chr(StartingColumn + 0)
                              + CStr(StartingRow + Count)).Value = Time
          ActiveWorkbook.ActiveSheet.Range(Chr(StartingColumn + 1)
                              + CStr(StartingRow + Count)).Value = up
          ActiveWorkbook.ActiveSheet.Range(Chr(StartingColumn + 2)
                              + CStr(StartingRow + Count)).Value = dn

' This look scans all the properties associated with a vehicle. The 18 
' fields are documented in the TSIS File Description Document.
' The attached spreadsheet application also contains field headers.

          For k = 1 To 18
             ActiveWorkbook.ActiveSheet.Range(Chr(StartingColumn + 2 + k)
                           + CStr(StartingRow + Count)).Value = veh.vehFields(k)
          Next k

       Next j
     End If
   Next i
Loop

Perl Example (processing SIGNAL messages)

The following example (in perl) dumps all the signal control information to a file.  The following code loops over all time steps, calling the ShowLinks subroutine to dump the signal control data to a file.  Note that ShowLinks is also called after the loop to ensure that the last time steps data is also output.  

#
# Create object
#

use Win32::OLE;

$ex = Win32::OLE->new( "cortools.tsdReader" ) or die "tsdReader not registered!";

# Loop over all time steps in TSD file, processing at the end of
# each read.
#

while ($ex->{tsdReadNext}){

  #
  # View Link Information - See the sub for special tricks
  #

  &ShowSignals;
}
&ShowSignals;

The following code displays the contents of the ShowLinks subroutine.

sub ShowSignals{

#
# loop over signal messages.  This is NOT the same as signals.  Signal
# messages contain lists of links and the signal displays being displayed
# to each turning movement on the link.
#

for ($i=0;$i<$ex->{tsdSignalCount};$i++){

  $signal = $ex->tsdSignals($i);

#
# loop over moving link in each signal record, displaying attributes
#

  for ($j=0;$j< $signal->sigLinkCount; $j++){

#
# Print common parts of record - time
#

    print $ex->{tsdTime} . "\t";

#
# Get a moving link object from the TSDReader. Dump attributes.
#

    $link = $signal->sigLinks($j);
    $up = int($link->Fields(1) / 10000);
    $dn = $link->Fields(1) % 10000;

    print "$up\t$dn\t"; # UpNode and DnNode for link
    print $link->Fields(2) . "\t"; # Signal code for left turns
    print $link->Fields(3) . "\t"; # Signal code for thru turns
    print $link->Fields(4) . "\t"; # Signal code for right turns
    print $link->Fields(5) . "\n"; # Signal code for diagonal turns

  }#end loop $j

} #end loop $i

} #end sub

Perl Example (Processing TID file and LINKMOE messages)

#
# Create object
#

use Win32::OLE;
$ex = Win32::OLE->new( "cortools.tsdReader" ) or die "tsdReader not registered!";

#
# Assign file and exit program (die) if it doesn't open
#

$ex->{FileName} = "d:\\tsis projects\\corsm1 example\\corsim1.tid";
die "File not opened\n" if (!$ex->{IsOpen});

#
# Loop over all time intervals, printing link ID (field 1)
#

do {
  $ex->ReadNext;
  print $ex->Time . "\n";
  for ($i=0;$i<$ex->tidLinkCount;$i++){
    print "\t" . $ex->tidLinks($i)->Fields(1) . "\n";
  }
} until ($ex->EOF);

#
# That's it!  Refer to previous examples for code to check links, etc.
#

Link MOE Field Definitions

The following table documents the attributes accessible from the tidLink.Fields method.  The table provides the data type, size, and name (from the KSC.FD source code file.)

 1 INTEGER*4 itsLinkID
 2 INTEGER*2 Number of time intervals (always 1)
 3 INTEGER*4 always 9999 
 4 INTEGER*4 itsTimeInterval
 5 REAL*4 itsAverageVehicleLength
 6 INTEGER*4 itsCumulativeStops
 7 INTEGER*4 itsCumulativeContent
 8 INTEGER*4 itsCumulativeDischargeLeft
 9 INTEGER*4 itsCumulativeDischargeThrough
10 INTEGER*4 itsCumulativeDischargeRight
11 REAL*4 itsCumulativeTravelTimeLeft
12 REAL*4 itsCumulativeTravelTimeThrough
13 REAL*4 itsCumulativeTravelTimeRight
14 INTEGER*4 itsCumulativeTripsLinkLeft
15 INTEGER*4 itsCumulativeTripsLinkThrough
16 INTEGER*4 itsCumulativeTripsLinkRight
17 REAL*4 itsCumulativeQueueDelayLeft
18 REAL*4 itsCumulativeQueueDelayThrough
19 REAL*4 itsCumulativeQueueDelayRight
20 REAL*4 itsCumulativeStopDelayLeft
21 REAL*4 itsCumulativeStopDelayThrough
22 REAL*4 itsCumulativeStopDelayRight
23 INTEGER*4 itsCumulativeLaneChanges
24 INTEGER*4 itsCumulativePhaseFailures
25 REAL*4 itsCumulativeFuelConsumptionAut
26 REAL*4 itsCumulativeFuelConsumptionBus
27 REAL*4 itsCumulativeFuelConsumptionTru
28 REAL*4 itsCumulativeEmissionsGramsCO
29 REAL*4 itsCumulativeEmissionsGramsHC
30 REAL*4 itsCumulativeEmissionsGramsNOx
31 INTEGER*2 COUNT number of lanes
32-38 REAL*4 ARRAY(7) itsAverageQueueLength (for each lane)
39 INTEGER*2 COUNT number of lanes
40-46 REAL*4 ARRAY(7) itsMaxQueueLength (for each lane)
47 REAL*4 itsPersonTrips
48 REAL*4 itsCumulativeMilesTraversedLeft
49 REAL*4 itsCumulativeMilesTraversedThru
50 REAL*4 itsCumulativeMilesTraversedRght
51 REAL*4 itsCumulativeMilesTraversedAll
52 INTEGER*4 itsBUSTotalBusesDischarged
53 INTEGER*4 itsBUSTotalPersonTrips
54 REAL*4 itsBUSTotalTravelTime
55 REAL*4 itsBUSTotalDelayTime
56 REAL*4 itsBUSMovingTime
57 REAL*4 itsBUSMeanSpeed
58 INTEGER*4 itsBUSTotalBusesStopped