network

README

Network

A CLI tool for inspecting and manipulating VITM network shapefiles and DBFs. It supports the following operations:

• Orchestrating conversions from Cube Networks to DBFs or shapefiles.
• Conversion from shapefiles to CSV or GeoJSON, with the option to:
  • Filter by link or more general attributes of a given row.
  • Include only specific fields in the generated CSV.
  • Derive new fields in the generated CSV using expressions.
• Provide route statistics such as travel times and distances.

This README contains information on how to install network, as well as documentation on how to use its commands.

Contents

• Installation
• Usage
  • Cube Network Conversion
  • DBF to CSV Conversion
  • Shapefile to GeoJSON Conversion
  • Route Statistics

Installation

First, ensure that you have Go installed and running. You can then install the latest release globally by running:

go install git.sr.ht/~michaelbyrne/network

Alternatively, download the latest release from the refs page.

Usage

Check that your installation works by running network.exe help or network help if you added the executable to your $PATH. The output should look similar to the following:

This application contains tools for working with VITM network DBFs and shapefiles.

Usage:
  network [command]

Available Commands:
  completion  generate the autocompletion script for the specified shell
  csv         Convert DBFs to CSV files
  cube        Convert Network files shapefiles or DBFs
  geojson     Convert Shapefiles to GeoJSON files
  help        Help about any command
  routes      Calculate route statistics from DBFs

Flags:
  -h, --help   help for network

Use "network [command] --help" for more information about a command.

The tool is split into a number of sub-commands that can each be individually invoked with network [command] where [command] is the name of the sub-command. Help for each sub-command can be viewed with network [command] --help or network help [command]. Further documentation for each sub-command can be found in the subsequent sections.

Cube Network Conversion

Convert Cube Network files (based on input path or pattern) to shapefiles or
DBFs. This will generate a temporary Cube script file and invoke it with Cube
Voyager in the background to generate the specified outputs. Both link and node
files can be created, in shapefile or DBF form.

Usage:
  network cube [source files or glob patterns...] [flags]

Flags:
  -f, --format string    output format ('DBF' or 'SHP') (default "DBF")
  -h, --help             help for cube
  -o, --out-dir string   output directory (default ".")
  -p, --progress         show Cube progress windows
  -t, --type string      output type ('LINK' or 'NODE') (default "LINK")
  -v, --voyager string   path to Cube Voyager (default "VOYAGER.EXE")

The positional arguments to this sub-command can be one or more DBF files or glob patterns. For example, the following are all acceptable invocations of the cube sub-command:

• network csv SUMMARY_LINKS.net
• network csv SUMMARY_LINKS_1.net SUMMARY_LINKS_2.net
• network csv summary_links\*.net
• network csv summary_links_folder_1\*.net summary_links_folder_2\*.net

# network cube [-o | --out-dir] directory

Specify the directory where the generated files are written. If the directory does not exist, it will be created. If this flag is not set, it will default to the current directory.

# network cube [-t | --type] NODE | LINK

Specify whether a node or link file is created. This defaults to link files if not specified.

# network cube [-f | --format] DBF | SHP

Specify whether a DBF or shapefile should be created. This defaults to DBF if not specified.

# network cube [-v | --voyager] path

Specify the location of the Cube Voyager executable. This is most commonly located in a place like C:\Program Files\Citilabs\CubeVoyager\VOYAGER.EXE. If not specified this will default to VOYAGER.EXE, which assumes that the CubeVoyager directory is present on the PATH.

# network cube [-p | --progress]

If set the Cube script progress window will be shown for each conversion.

DBF to CSV Conversion

Convert VITM network DBF files (based on input path or pattern) to CSV files.
An optional YAML configuration file can be provided to filter the rows that are
included in the outputs. This configuration can also be used to select fields
to include or derive new ones using expressions.

Usage:
  network csv [source files or glob patterns...] [flags]

Flags:
  -c, --config string    filtering and field configuration YAML file
  -h, --help             help for csv
  -o, --out-dir string   output directory (default ".")

The positional arguments to this sub-command can be one or more DBF files or glob patterns in a similar fashion to the cube sub-command.

# network csv [-o | --out-dir] directory

Specify the directory where the generated CSV files are written. If the directory does not exist, it will be created. If this flag is not set, it will default to the current directory.

# network csv [-c | --config] path

Optionally specify the path to a csv sub-command configuration YAML file. This can be used to specify filtering and field generation. See examples/example-csv-config.yml for a full set of options that can be configured.

Shapefile to GeoJSON Conversion

Convert VITM network Shapefiles (based on input path or pattern) to GeoJSON
files. An optional YAML configuration file can be provided to filter the
features that are included in the outputs. This configuration can also be used
to select fields to include or derive new ones using expressions.

Usage:
  network geojson [source files or glob patterns...] [flags]

Flags:
  -c, --config string    filtering and field configuration YAML file
  -e, --epsg int         input projection EPSG code (default 20255)
  -h, --help             help for geojson
  -o, --out-dir string   output directory (default ".")

The positional arguments to this sub-command can be one or more shapefiles or glob patterns in a similar fashion to the cube sub-command.

# network geojson [-o | --out-dir] directory

Specify the directory where the generated GeoJSON files are written. If the directory does not exist, it will be created. If this flag is not set, it will default to the current directory.

# network geojson [-c | --config] path

Optionally specify the path to a geojson sub-command configuration YAML file. This can be used to specify filtering and field generation. See examples/example-geojson-config.yml for a full set of options that can be configured.

# network geojson [-e | --epsg] code

Optionally specify the EPSG code that the input data is projected in. By default, this is assumed to be 20255 (AGD66 Zone 55).

Route Statistics

Calculate statistics such as travel time or distance along specified routes.
You must provide a YAML configuration file of the correct format to this
sub-command. The relevant fields will then be provided for each specified route.

Usage:
  network routes [source files or glob patterns...] [flags]

Flags:
  -c, --config string    field and route configuration YAML file
  -h, --help             help for routes
  -o, --out-dir string   output directory (default ".")

The positional arguments to this sub-command can be one or more DBF files or glob patterns in a similar fashion to the cube sub-command.

# network routes [-o | --out-dir] directory

Specify the directory where the generated CSV files are written. If the directory does not exist, it will be created. If this flag is not set, it will default to the current directory.

# network routes [-c | --config] path

Specify the path to a routes sub-command configuration YAML file. This is used to specify the routes to summarise and the fields of interest. See examples/example-routes-config.yml for a full set of options that can be configured.