Working with distance (linear) units in a geoprocessing script

In this article I will answer another common question I am often asked in class:

“When, for example, I want to perform a buffer what linear units are available and where can I get a definitive list of them?

There are many geoprocessing tools which allow to specify some kind of distance unit as an input into the tool. These distance units are usually associated with the linear unit data type. Examples of these tools include Buffer, Generate Near Table, Grid Index Features, to name but a few. In fact the more you look the more you realise that this tool input is really quite common.

Using distance (linear) units in a geoprocessing tool is straight-forwards. Let’s use the trusty Buffer tool as an example:

arcpy.Buffer_analysis(“Roads”,
                      “RoadsBuff100”,
                      100)

In the above example we are buffering the Roads layer to a distance of 100. But is this 100 metres? 100 feet? Or 100 miles? It all depends upon the linear unit of the input dataset’s coordinate system. In the United Kingdom the coordinate system tends to be British National Grid whose unit of measurement is the metre so the Roads layer will be buffered to 100 metres.

A common question I get asked is:

“What about if I wanted to buffer the roads to 100 feet? How would I do that?”

In the Buffer tool dialog this pretty easy as I can select my units from a drop down list:

Unitsdropdown

How would I do this in my Python script?

It is relatively straight-forwards. All you have to do is make the buffer distance into a string and include the distance units of choice inside of the string:

arcpy.Buffer_analysis(“Roads”,
                      “RoadsBuff100”,
                      “100 feet”)

If your distance (linear) units are composed of more than one word, such as “Decimal Degrees” then the two words should be combined into one i.e. “DecimalDegrees

The follow-up question invariably is:

“How do I know what distance units are available to me?”

Well, you could look in the drop down list on the dialog for the tool concerned. Or you could look in the ArcGIS for Desktop Help and find the well-hidden help page which lists the linear units. The page is found at this link.

If you do not have an internet connection then you can find the relevant help document here:

Desktop >

Geoprocessing >

Tool errors and warnings >

Tool errors 1 – 10000 >

Tool errors and warnings: 801 – 900 >

000817 : Invalid linear unit type

In the next blog I will have a look another common question: “What is the best way to specify optional arguments for a geoprocessing tool?”

Advertisements