MaNIS/HerpNet/ORNIS Georeferencing Guidelines 4
There are several fundamental sources of uncertainty in locality descriptions. These uncertainties vary in magnitude as well as in their interactions with each other. It is essential during georeferencing to determine and record the net uncertainty of a geographic coordinate determination. This document will explain the methodology for expressing the uncertainty as a single measurement - a maximum error. There are numerous ways in which this maximum error might be expressed, but the most convenient is as a simple distance. The sources of uncertainty, their relative magnitudes, and the interactions between them are discussed in the second section, Determining Maximum Error Distance from Uncertainties.
An Appendix containing a glossary, references, and a description of the data that should be captured for each georeferenced locality is appended for the convenience of the reader.
Determining Latitude & Longitude
Geographic coordinates can be expressed in a number of different coordinate
systems (e.g. decimal degrees, degrees minutes seconds, degrees decimal
minutes, UTM, etc.). Conversions can be made readily between coordinate
systems, but decimal degrees provide the most convenient coordinates to
use for georeferencing for no more profound a reason than a locality can
be described with only two attributes - decimal latitude and decimal longitude.
Named Places
The simplest locality descriptions consist of only a named place. Many
gazetteers record the location of the main post office of a populated place,
unless that place is a county seat, in which case the location of the courthouse
is recorded. Use the same method when making measurements on a map from
a populated place. Use the geographic center for the latitude and longitude
of other named places. Some gazetteers give bounding boxes to describe
the extents of large places. Use the distance from the coordinates of the
named place to the furthest point within the named place as the maximum
error distance. If the geographic center of the named place is not within
the confines of the shape of the named place, use the point nearest to
the geographic center that lies within the shape. In each of these cases
it is best to record the method of determination of the coordinates and
error in the remarks for the determination (e.g., "measured from the main
post office" or "measured from the geographic center of Bakersfield").
Example: "Bakersfield"
Township Range Section (TRS) descriptions are essentially no different
from that of any other named place. It is necessary to understand TRS descriptions
and how they describe a place. See the
References section, below,
for links to TRS information.
Example: "E of Bakersfield, T29S R29E Sec. 34 NE 1/4"
Offsets
Offsets generally consist of combinations of distances and directions
from a named place. Use the geographic coordinates of the named place (see
the Named Places section, above) as a starting point. Sometimes
the locality description gives a method for determining the offset (e.g.,
"by road", "by river", "by air", "up the valley", etc.). No special remark
about how the coordinates and error were determined is necessary in cases
where the measurement method is given in the locality description.
Example: "10 mi E (by air) Bakersfield"
Localities that have two orthogonal measurements in them should be treated
as if the measurements are "by air."
Example: "2 mi E and 1.5 mi N of Bakersfield"
If the distance was along a linear feature such as a road or river,
measure along the feature rather than use a straight line. There is no
uncertainty due to direction imprecision (see the Precision section,
below) for this type of locality description.
Example: "13 mi E (by road) Bakersfield"
There is a long-standing convention that the left and right sides of
a river are from the perspective of facing downstream.
(Note: The text incorrectly stated that the convention was based on
the perspective facing the source and was amended on 17 Jan 2004.
Thanks to Margaret Thayer of FMNH for this correction.)
Thus, in
the following example, the locality is on the east side of the river, in
Illinois, rather than on the west side, in Missouri.
Example: "left bank of the Mississippi River, 16 mi downstream
from St. Louis"
Localities that have one linear offset measurement from a named place,
but that do not specify how that measurement was taken are open for case-by-case
judgment.
Example: "10.2 mi E of Yuma"
The judgment itself must be documented in the remarks for the determination (e.g., "Assumed 'by air' - no roads E out of Yuma", or "Assumed 'by road' on Hwy. 80"). If there is no clear best choice, use the midpoint between the two possibilities as the geographic coordinate and assign an error large enough to encompass the coordinates and uncertainties of both methods. In this case, the remark should be something like "Error encompasses both distance by air and distance by road (Hwy. 80)".
Vagueness
At times, locality descriptions are fraught with vagueness. It is not
the purpose here to belittle localities of this type; in fact, an honest
admission of the unknown is preferable to masking it with unwarranted precision.
The most important type of vagueness in a locality description is one
in which the locality is in question. No such locality should be georeferenced.
Example: "Bakersfield?"
Many locality descriptions imply an offset from a named place without
definitive directions or distances. In these cases use the geographic center
of the named place for the geographic coordinates. For the maximum error
distance, use the greatest distance that is not likely to be considered
in the area of another named place. Clearly there is a measure of subjectivity
involved here. Let common sense prevail and document the assumptions made.
Example: "near Bakersfield"
Sometimes offset information is vague either in its direction or in
its distance. If the direction information is vague, record the geographic
coordinates of the center of the named place and include the offset distance
in the determination of the maximum error distance.
Example: "5 mi from Bakersfield"
Uncertainty in the offset distance is a fact of the business; most localities
are recorded without
error estimates. The addition of an adverbial modifier to the distance
part of a locality description, while an honest observation, should not
affect the determination of the geographic coordinates or the maximum error.
For the example below, treat the locality as if it read "3 mi E of Bakersfield."
Example: "about 3 mi E of Bakersfield"
The worst type of locality description to georeference is one that is
internally inconsistent. There are numerous possible causes for inconsistencies.
Rather than determine coordinates for such localities, annotate the locality
with the nature of the inconsistency and refer the locality to the source
institution for reconciliation. One common source of inconsistency in locality
descriptions comes from trying to match elevation information with the
rest of the description.
Example: "10 mi W of Bakersfield, 6000 ft" (There is
no place anywhere near 10 mi W of Bakersfield at an elevation of 6000 ft).
Another common source of inconsistency occurs when the locality description
does not match the geopolitical subdivision of which it is supposed to
be a part. At times the locality can still be determined because the geopolitical
subdivision is clearly at fault. In this case, georeference the locality
and annotate it to describe the problem.
Example: "Delano, Tulare Co." (Delano is in Kern Co.)
Often there is no way to know if the geopolitical subdivision or something
in the locality description itself is at fault. In the following example
the county may be wrong, the distance may be wrong, or the direction may
be wrong. This locality cannot be disambiguated without further research,
which is best left to the institution that provided the locality description.
Example: "5 mi N of Delano, Kern Co." (5 mi N would put
the locality in Tulare Co.)
Determining Maximum Error Distance from
Uncertainties
The three basic sources of coordinate information used in georeferencing
are maps, gazetteers, and localities already recorded with coordinates.
The process of georeferencing includes an assessment of the uncertainties
in geographic coordinate determinations. Uncertainties may arise due to
combinations of the following sources:
1) the extent of a locality
2) GPS accuracy
3) unknown datum
4) imprecision in distance measurements
5) imprecision in coordinate measurements
6) map scale
7) imprecision in direction measurements
It is essential to understand how each of these sources contribute to the net error in a geographic coordinate determination. The first six of these are sources of distance uncertainty. Though distance uncertainties may generally be summed, there are exceptions, and the georeferencer must be cognizant of them. Distance uncertainties must never be summed with direction uncertainties; the interactions between these two different types of sources are always non-linear. The types of uncertainty that may apply for each of the sources of coordinate information are as follows:
map - locality extent, unknown datum, distance imprecision, map scale, and coordinate imprecision, which must all be summed before calculating their interaction with direction imprecision.
gazetteer - locality extent, unknown datum, distance imprecision, and coordinate imprecision, which must be summed before calculating their interaction with direction imprecision.
coordinates - unknown datum and coordinate imprecision, which must be summed to get the maximum error distance.
GPS - unknown datum, GPS accuracy, and coordinate imprecision, which must be summed to get the maximum error distance.
Guidelines for determining the magnitude of each of the types of uncertainty are given in the paragraphs below. Following the guidelines for the individual types of uncertainty are two sections on the combinations of uncertainties.
Uncertainty due to the extent of a locality
Named places are not single points; they have extents. Although there
are conventions for placing the coordinates of a named place at the post
office, courthouse, or geographic center of a town, one cannot be sure
that the person who recorded the locality used a particular convention.
Use the distance
from the geographic center of the named place to its furthest extent as
the uncertainty. Since many localities
are based on cities that have changed in size over the years, the extents
on current maps might not reflect the extents when specimens were collected.
In almost every case the current extents will be greater than the historical
ones and the error calculations will be overestimated. This is consistent
with our conservative approach to georeferencing.
Townships are just another instance of a named place (see the
References
section, below, for links to information on townships). In general, a
township is a 6 mile square, with each of its component sections being
a 1 mile square. Exceptions to this rule occur often in practice to account
for the curvature of the earth, but it is generally safe to use the values
in the table below as the extents of various divisions of a township.
These values assume that the greatest extent is from the center of the
division to a corner of that division, and that the coordinates of the division
are not being calculated from orthogonal offsets.
Note that the tools for calculating coordinates for TRS locations only
calculate based on a Township Section. If you want the center of a Township
or another location in a Township more precisely defined than a Section,
you'll need to make calculations based on orthogonal offsets from the center
of a Township Section. For example,
to find the center of a Township, first find the coordinates of the
center of Section 15 in that Township. Then calculate the coordinates of a
point 0.5 mi W and 0.5 mi S of the center of Section 15. This new point is
the center of the Township. To calculate the maximum error distance for this
example, make sure to use a distance precision of "exact" and an extent of
3 mi. This will insure that the contribution to the error based on the extent
of the Township will be 4.243 mi (see the Extents of divisions of a
township Table, below).
To find the center of a quarter section, first find the center of the
Section. Then calculate the coordinates of the quarter section by using
offsets of 0.25 mi in the appropriate directions from these coordinates.
For example, the center
of the NW 1/4 of Section 13 would be 0.25 mi N and 0.25 mi W of the center
of Section 13. In calculating the maximum error distance for this example,
set the distance precision to "exact" and set the extent to 0.25 mi.
This will insure that the contribution to the error based on the extent
of the Township wil be 0.354 mi (see the Extents of divisions of a
township Table, below). This
same method can be extended to calculate the centers
of other divisions of a Section as well. For 1/4 of 1/4 of a Section, use an
extent of 0.125 mi, and for 1/4 of 1/4 of 1/4 of a Section, use 0.625 mi
for the extent.
| Division | Example |
|
|
| Township | T6S R14E |
4.243 mi
|
3 mi
|
| Section | T6S R14E Sec. 23 |
0.707 mi
|
0.5 mi
|
| 1/4 Section | T6N R14E Sec. 23 NE 1/4 |
0.354 mi
|
0.25 mi
|
| 1/4 of 1/4 Section | T6N R14E Sec. 23 NE 1/4 SW 1/4 |
0.177 mi
|
0.125 mi
|
| 1/4 of 1/4 of 1/4 Section | T6N R14E Sec. 23 NW 1/4 NE 1/4 SW 1/4 |
0.089 mi
|
0.0625 mi
|
Uncertainty due to GPS accuracy
The accuracy of the coordinate data reported by a GPS varies with time,
place, and equipment used. Previous to the order to cease
Selective Availability (deliberate GPS signal scrambling)
at 8PM EST 1 May 2000, uncorrected GPS receivers were subject to artificial
inaccuracies of about 100 meters. Today, many GPS receivers have a function to
determine the estimated accuracy of given reading, but this information is
not universally available, nor is it often recorded with the coordinates.
It is not possible to determine the actual accuracy of a GPS reading
retroactively if it was not recorded at the time of the reading. In fact,
many GPS receivers estimate accuracy poorly. My Garmin eTrex Summit, for
example, reports positions with putative accuracies of 7 meters
that are demonstrably off by 15 meters. Where extreme accuracy is required,
be sure of the capabilities of your GPS under the prevailing conditions
when the coordinates are recorded. For retrospective uncertainty estimates
where detailed information is not available, 30 meters is a reasonable,
conservative estimate of GPS accuracy in the absence of Selective Availability.
Uncertainty due to an unknown datum
Seldom in natural history collections have geographic coordinates been
recorded along with the underlying datum on which they were determined.
Even now, when GPS coordinates are being recorded seemingly as definitive
locations, the geodetic datum is being ignored. Interestingly, even the
GNIS placename data are derived from maps in both NAD27 and NAD83 without
direct reference to which datum was used for any particular record. Without
recording the datum with the coordinates, uncertainty is being introduced.
Figure 1 shows the magnitude of uncertainty (in meters) over North America
based on not knowing the datum on which the source was based.
Figure 1. Map of North America showing the magnitude of uncertainty from not knowing whether coordinates were taken from a source using NAD27, NAD83, or WGS84.
The uncertainty due to an unknown datum is a complicated, non-linear function of latitude and longitude. This map can be used as a rough guide for determining the magnitude of that uncertainty in North America. If the locality is outside the area covered by the map in Figure 1, use 1 km as the uncertainty due to an unknown datum.
Precision
Precision can be difficult to gauge from locality descriptions; it
is seldom, if ever, explicitly recorded. Furthermore, a database record
may not reflect, or may reflect incorrectly, the precision inherent in
the original measurement, especially if the locality description has undergone
interpretation from the original, verbatim description. Different precision
issues arise from recording distance measurements, directions (headings),
and coordinates. Potential uncertainties from each of these sources are
discussed in the paragraphs below.
Uncertainty associated with distance
precision
Distance may be recorded in a locality description with or without
significant digits, and those digits may or may not be warranted. A conservative
way to insure that distance precision is not inflated is to treat distance
measurements as integers with fractional remainders. Thus 10.25 becomes
10 1/4, 10.5 becomes 10 1/2, etc. Calculate the uncertainty for
these distances based on the fractional part of the distance, using 1 divided
by the denominator of the fraction.
Example: "10.5 mi N of Bakersfield" (the fraction is
1/2, uncertainty should be 0.5 mi)
Example: "10.6 mi N of Bakersfield" (the fraction is
6/10, uncertainty should be 0.1 mi)
Example: "10.75 mi N of Bakersfield" (the fraction is
3/4, uncertainty should be 0.25 mi)
For distances that appear as integer powers of ten (10, 20, 300, 4000), use
0.5 times ten to that power for the uncertainty.
Example: "10 mi N of Bakersfield" (the uncertainty should be 5 mi)
Example: "140 mi N of Bakersfield" (the uncertainty should be 5 mi)
Example: "100 mi N of Bakersfield" (the uncertainty should be 50 mi)
Example: "2000 m N of Bakersfield" (the uncertainty should be 500 m)
Note: If the locality description contains distance measures of varying
precision, the person recording the data was demonstrably sensitive to
the highest level of precision expressed in the locality, and it is fair
to assume that level of precision would not vary within a single locality
description. Therefore, the distance precision for the locality can safely
be assumed to be the same as for the highest precision measurement in the
locality description.
Uncertainty associated with directional
precision
Direction is almost always expressed in locality descriptions using
cardinal or intercardinal directions rather than degree headings. This
traditional practice can introduce unfortunate directional imprecisions.
The problem arises from the fact that we don't know, out of context, what
the recorder meant by, say, "north", except that it is probably distinct
from the other cardinal directions. Hence, "north" is not "east" or "west",
but it could be any direction between northeast and northwest. The directional
uncertaintyin this case is 45 degrees in either direction from the given
direction.
Example: "10 mi N of Bakersfield"
Of course, if the locality description contains two orthogonal directions,
then the measurements are likely to have been made on a map in exactly
those directions. In this case, directional imprecision can be ignored.
Example: "10 mi N and 5 mi E of Bakersfield"
If the locality description contains directions more specific than the
cardinal directions (e.g., "NE"), then the person recording the data was
demonstrably sensitive to intercardinal directions and the directional
precision can safely be assumed to be greater than if only cardinal directions
were used. Thus, "NE" could mean any direction between ENE and NNE, which
is twice as precise as the first direction example, above. The directional
uncertainty in this case is 22.5 degrees in either direction from the given
direction.
Example: "10 mi NE of Bakersfield"
A locality description that contains further refined directions is correspondingly
more precise. Thus, in the following example the directional uncertainty
is 11.25 degrees.
Example: "10 mi ENE of Bakersfield"
Uncertainty associated with coordinate
precision
When recording geographic coordinates, always keep as many digits as
possible. Recording coordinates with insufficient precision can result
in unnecessary uncertainties. The magnitude of the uncertainty is a function
not only of the precision with which the data are recorded, but also a
function of the datum and the coordinates themselves. This is a direct
result of the fact that a degree does not correspond to the same distance
everywhere on the surface of the earth. Uncertainty due to the precision
with which the original coordinates were recorded can be estimated as follows:
uncertainty=sqrt( lat_error2 + long_error2)
where
R is the radius of curvature of the meridian at the given latitude,
X is the distance from the point to the polar axis orthogonal to the
polar axis, and
lat_long_precision is the precision with which the coordinates were
recorded, as a fraction of one degree.
R is given by the following equation:
R = a (1-e2)/(1-e2sin2(latitude))3/2
where
a is the semi-major axis of the reference ellipsoid (the radius at
the equator),
e is the first eccentricity of the reference ellipsoid, defined by
the following equation:
e2 = 2f - f2
where
f is the flattening of the reference ellipsoid.
X is also a function of geodetic latitude and is given by the following equation:
X = abs(Ncos(latitude))
where
N is the radius of curvature in the prime vertical at the given latitude
and is defined as follows:
N = a/sqrt(1-e2sin2(latitude))
Example: Lat: 10.27 Long: -123.6
In this example the lat_long_precision is 0.01 degrees. Thus, lat_error
= 1.1061 km, long_error = 1.0955 km, and the uncertainty resulting from
the combination of the two is 1.5568 km. Note: The foregoing method uses
a semi-major axis of 6378137.0 meters and a flattening of 1/298.25722356
based on the WGS84 datum1. Following is a table showing examples
of error contributions for different levels of precision in the original
coordinates using the WGS84 reference ellipsoid.  For most maps, particularly
old ones, accuracy of scale is not documented. However, the USGS
does have horizontal accuracy standards that are supposed to be met for
all of its maps. Specifically,
"For maps on publication scales larger than 1:20,000, not more than 10 percent of the points tested shall be in error by more than 1/30 inch, measured on the publication scale; for maps on publication scales of 1:20,000 or smaller, 1/50 inch."2
It is extremely important to note that a digital map is not more accurate
than the original from which it was derived, nor is it more accurate when
you zoom in on it. The accuracy is strictly a function of the scale of
the original map. Below is a table showing the uncertainty due to scale
for USGS maps.
|
|
|
|
|
1:1200
|
|
|
|
1:2400
|
|
|
|
1:4800
|
|
|
|
1:10,000
|
|
|
|
1:12,000
|
|
|
|
1:24,000
|
|
|
|
1:25,000
|
|
|
|
1:63,360
|
|
|
|
1:100,000
|
|
|
|
1:250,000
|
|
|
The uncertainty inherent in non-USGS maps may not be documented. Use a value of 1mm of uncertainty on non-USGS maps. 1mm is the specified chart accuracy of all NOAA nautical charts"3, and corresponds to about three times the detectable graphical error and should serve well as an uncertainty estimate for most maps. By this rule, the uncertainty for a map of scale 1:25,000, for example, would be 25 meters and that for a 1:500,000 map would be 500 meters.
Combinations of uncertainties:
distances
Distance uncertainties in any given direction are linear and additive.
Following is an example of a simple locality description and an explanation
of the manner in which multiple sources of uncertainty interact to result
in an overall maximum error distance.
Example: "6 km E (by road) of Bakersfield"
In the example above, there is no error contribution from direction; all uncertainties apply only to the distance. The possible sources of uncertainty for this example are 1) the extent of Bakersfield, 2) unknown datum, 3) distance imprecision, and 4) map scale. Suppose the center of Bakersfield is 3 km from the eastern city limit and the distance is being measured on a USGS map at 1:100,000 scale on the NAD83 datum. The uncertainty due to the extent of Bakersfield is 3 km, there is no uncertainty due to an unknown datum (assuming the datum is recorded with the coordinates), the distance imprecision is 1 km, and the uncertainty due to map scale is 51 meters. The maximum error distance for this locality is the sum of these, or 4.051 km
If more than one direction is used in the locality description, uncertainties
apply to each of the two cardinal directions and the combination of them
is non-linear.
Example: "6 km E and 8 km N of Bakersfield"
This example consists of two orthogonal distance measures from a named place, each with its own uncertainty due to distance imprecision. Ignore for the moment all sources of uncertainty except those arising from distance imprecision. Under this simplification, a proper description of the uncertainty is a bounding box centered on the point 6 km E and 8 km N of Bakersfield. Each side of the box is 2 km in length (1 km uncertainty in each cardinal direction from the center). Since we are characterizing the maximum error as a single distance measurement, we need the circle that circumscribes the above-mentioned bounding box. The radius of this circle is the distance from the center of the box to any corner. The radius could either be measured on a map or calculated using a right triangle, the hypotenuse of which is the line between the center of the bounding box and a corner. Given the rule that the distance precision is the same in both cardinal directions, the triangle will always be a right isosceles triangle and the hypotenuse will always be the the square root of 2 times the distance precision. So, for the above example the error distance associated with only the distance precision would be 1.414 km.
So far we have accounted only for distance imprecision for this example.
How do we take into account the uncertainty due to the shape of the named
place? There are many methods that could be used to determine the coordinates
and error for this situation.
Note: The method presented here is quite
conservative, resulting in errors larger than they need to be. A better
alternative would be to multiply only the distance precision error by the
square root of 2 (contributions in both dimensions), and then sum that with
all other sources, which already account for the two dimensions. This second
method is the one used in the Georeferencing
Calculator since version 20130205.
Determine the furthest distance within the named place from the geographic center of the named place in either of the two cardinal directions mentioned in the locality description. Add this distance to the distance precision and take the square root of 2 times the sum to get the maximum error distance associated with the combination of distance precision and the extent of the named place. For the example above, suppose the furthest extent of the city limits of Bakersfield either E or N from the geographic center is 3 km. There would be a total of 4 km of uncertainty in each of the two directions and the radius of the circumscribing circle would be 4 km times the square root of 2, or 5.657 km.
What other sources of uncertainty need to be accounted for in this example? Suppose the coordinates for Bakersfield were taken from the GNIS database, in which there is no reference to datum and the coordinates are given to the nearest second. The coordinates for Bakersfield are given in the GNIS database as 35d 22' 24" N, 119d 01' 04" W. At this location the uncertainty due to an unknown datum is 79 meters. The datum uncertainty contributes in each of the orthogonal directions. Thus, the uncertainty in each direction would be 4.079 km and the net uncertainty is this number times the square root of two, or 5.769 km.
The coordinates in the GNIS database are given to the nearest second. Based on the Uncertainty associated with coordinate precision section, above, the uncertainty due to coordinate precision alone is about 39 meters at the latitude of Bakersfield. This number already accounts for the contributions in both cardinal directions, so it must not be multiplied by the square root of 2. Instead, simply add the coordinate precision uncertainty to the calculated sum of uncertainties from the other sources. For the example above, the maximum error distance is just 5.769 + 0.039 = 5.808 km.
If the coordinates for Bakersfield had been taken from a USGS map with a scale of 1:100,000, the datum would be on the map, so there would be no contribution to the error from an unknown datum (assuming the georeferencer records the datum with the coordinates). However, the uncertainty due to the map scale would have to be considered. For a USGS map at 1:100,000 scale, the uncertainty is 167 feet, or 50 meters. In the above example, the net uncertainty in each direction would be 4.050 km. When multiplied by the square root of 2 their combination would be 5.728 km. Add the uncertainty due to coordinate imprecision to get the maximum error distance. Suppose the minutes are marked on the margin of the map and you interpolated to the nearest tenth of a minute. The coordinate precision would be 0.1 minutes and the uncertainty would be about 0.239 km from this source, therefore the maximum error distance would be 5.768 + 0.239 = 5.967 km.
Combinations of uncertainties: distance and direction
Though distance imprecisions in a given direction are linear and additive,
the sum of them contributes non-linearly to the error arising from directional
imprecision. An additional technique is required to account for the correlation
between distance and direction uncertainties.
Example: "10 km NE of Bakersfield"
If we don't consider distance imprecision, the uncertainty due to the direction imprecision is encompassed by an arc centered 10 km (d) from the center of Bakersfield (at x,y) at a heading of 45 degrees (θ), extending 22.5 degrees in either direction from that point. At this scale the distance (e) from the center of the arc to the furthest extent of the arc (at x',y') at a heading of 22.5 degrees (θ') from the center of Bakersfield can be approximated by the Pythagorean Theorem.
e=sqrt( (x'-x)2 + (y'-y)2 )
Now let's consider the distance uncertainties in this example. Suppose
the contributions to distance uncertainty are 3 km (extent of Bakersfield),
1 km (distance imprecision for "10 km"), 0.079 km (unknown datum, coordinates
are from the GNIS database), and 0.040 km (gazetteer data are recorded to the
nearest second) for a sum of 4.119 km. The error region (the shape of the region
describing the combination of distance and direction uncertainties) will be a band
twice this width (2 x 4.119 = 8.238 km) centered on 10 km offset arc spanning 22.5
degrees on either side of 45 degrees.
but now x = d cos(θ), y = d sin(θ),
x' = (d+d') cos(θ'), and y' = (d+d') sin(θ')
where d' is the sum of the distance uncertainties.
The geometry can be generalized, and simplified, by rotating the image above so that the point (x',y') is on the x axis.
but now x = d cos(α), y = d sin(α),
x' = d+d', and y' = 0
where d' is still the sum of the distance uncertainties and α is
an angle equal to the magnitude of the direction uncertainty. For our example
above, the distance uncertainty is 4.119 km and the direction uncertainty
is 22.5 degrees. Given these values, the maximum error distance is 6.210
km.
Summary
Locality descriptions are inexact and seldom give estimates of uncertainty.
An ideal description of a specific locality has no uncertainty. One way
to achieve this ideal is to describe the locality by a complex shape within
which the whole locality must certainly lie. The capture of shape data
is certainly possible with current GIS technology, and is even demonstrably
more efficient than the methods described above. However, there are technical
challenges yet to be met in order to make the capture of shape data feasible
in a collaborative, Internet-based georeferencing environment.
One alternative is to describe a locality using a point of arbitrarily
high precision with an attendant maximum error distance, which encompasses
all of the uncertainties associated with the geographic coordinates. This
is an expression of the locality which satisfies the requirement that the
locality given in the text description must lie within the spatial description.
There is a fundamental advantage of this alternative; the uncertainties
are summarized as a single value, the meaning of which is independent of
any geodetic surface. This allows for quantitative filtering on spatial
data quality, which ultimately allows the user of the spatial data to select
appropriate subsets of the data for analyses.
Appendix
Decimal degrees - degrees expressed as a single real number (e.g., -22.343456) rather than as a composite of degrees, minutes, seconds, and direction (e.g., 7d 54' 18.32" E).
Geodetic surface model - a geometric description of the surface of the earth.
Geodetic radius - the distance from a point on the geodetic surface to the intersection of the geodetic vertical with the geodetic equatorial plane.
Geographic coordinates - latitude and longitude, measured in any of various coordinate systems.
Geographic center - To find the geographic center of a shape, first find the extremes of both latitude and longitude within the shape and then take their respective means. If the result is not within the shape itself, choose instead the point in the shape nearest to the calculated center.
UTM - Universal Transverse Mercator. A grid coordinate system specifying a datum, zone, and offsets from the equator and from the meridian of the zone. See the References section, below, for more information.
DecimalLongitude - the longitude coordinate (in decimal degrees) at
the center of a circle encompassing the whole of a specific locality. Decimal
longitudes west of the Greenwich Meridian are considered negative and must
be greater than or equal to -180, while eastern longitudes are positive
and less than or equal to 180.
Example: -122.4900 degrees (which is roughly the same as 122d
29' 24" W).
Uncertainty (m) - the upper limit of the distance from the given latitude and longitude describing a circle within which the whole of the described locality must lie, in meters.
GeodeticDatum - the geometric description of a geodetic surface model (e.g., NAD27, NAD83, WGS84). Datums are often recorded on maps and in gazetteers, and can be specifically set for most GPS devices so the waypoints match the chosen datum. Use "not recorded" when the datum is not known.
VerbatimCoordinateSystem - the coordinate system in which the raw data are being entered. For the purpose of collaborative georeferencing this value will be "decimal degrees." However, existing geographic coordinates may be entered in degrees minutes seconds, degrees decimal minutes, or UTM coordinates. Original coordinates should be recorded as well if they are different from decimal degrees.
GeoreferenceSources - the reference source (e.g., the specific map, gazetteer, or software) used to determine the coordinates. Such information should provide enough detail so that anyone can locate the actual reference that was used (e.g., name, edition or version, year). Map scales should be recorded in the reference as well (e.g., USGS Gosford Quad map 1:24000, 1973).
GeoreferenceProtocol - a citation of a publicly available document describing the methods of georeferencing that were followed.
GeoreferencedBy - the person or organization making the coordinate and error determination.
GeoreferenceDate - the date on which the determination was made.
GeoreferenceRemarks - comments on methods and assumptions used in determining coordinates or errors when those methods or assumptions differ from or expand upon the accepted guidelines.
Coordinates Only
Example 1: 35 degrees 22' 24" N, 119 degrees 1' 4" W
Locality Type: Coordinates only
Coordinate Source: locality description
Coordinate Format: degrees minutes seconds
Latitude (input): 35 degrees 22' 24" N
Longitude (input): 119 degrees 1' 4" W
Datum: not recorded
Coordinate Precision: nearest second
Measurement Error: 0
Distance Units: km, m, mi, yds, or ft
Decimal Latitude: 35.3733333
Decimal Longitude: -119.0177778
Uncertainty (m): 3085 m (3.085 km, 1.91693 mi, 33373.8 yds, 10121
ft, or 1.66578 nm)
Uncertainty sources: 3045 m from unknown datum at that location, 40 m from coordinate precision nearest
second
Example 2: 35.37, -119.02, NAD27, Digital USGS Gosford Quad 1:24000 map
Locality Type: Coordinates only
Coordinate Source: Digital USGS map: 1:24,000
Coordinate Format: decimal degrees
Latitude (input): 35.37
Longitude (input): -119.02
Datum: NAD27
Coordinate Precision: 0.01 degrees
Measurement Error: 0 (digital map - no measurement)
Distance Units: km, m, mi, yds, or ft
Decimal Latitude: 35.37
Decimal Longitude: -119.02
Uncertainty (m): 1446 m (1.446 km, 0.899 mi, 1582 yds, 4745
ft, or 0.781 nm)
Uncertainty sources: 12 m from coordinate source USGS 1:24,000 map, 1434 m from
coordinate precision 0.02 degrees
Geographic feature only
Example: Bakersfield
Suppose the coordinates for Bakersfield came from the GNIS database
(a gazetteer) and the distance from the center of Bakersfield to the furthest
city limit is 3 km.
Locality Type: Named place only
Coordinate Source: gazetteer
Coordinate Format: degrees minutes seconds
Latitude (input): 35 degrees 22' 24" N
Longitude (input): 119 degrees 1' 4" W
Datum: not recorded
Coordinate Precision: nearest second
Measurement Error: 0
Radial of Feature: 3 km
Distance Units: km
Decimal Latitude: 35.3733333
Decimal Longitude: -119.0177778
Uncertainty (m): 6085 m
Uncertainty sources: 3045 m from unknown datum, 40 m from coordinate precision nearest
second, 3000 m from the extent of the named place
Distance Only
Example: 5 mi from Bakersfield
Suppose the coordinates for Bakersfield came from Topozone for which
all map coordinates have been reprojected in NAD27. Suppose also that the
distance from the center of Bakersfield to the furthest city limit is 2
mi.
Locality Type: Distance only
Coordinate Source: gazetteer
Coordinate Format: decimal degrees
Latitude (input): 35.373
Longitude (input): -119.018
Datum: NAD27
Coordinate Precision: 0.001 degrees
Offset Distance: 5 mi
Radial of Feature: 2 mi
Measurement Error: 0
Distance Units: mi
Distance Precision: 1 mi
Decimal Latitude: 35.373
Decimal Longitude: -119.018
Uncertainty (m): 12213 m (7.589 mi)
Uncertainty sources: 143 m (0.089 mi) from coordinate precision 0.001 degrees, 3219 m
(2 mi) from the extent of the named place, 8047 m (5 mi) from the offset distance, 805 m
(0.5 mi) from the 1 mi distance precision
Distance Along a Path
Example: 13 mi E (by road) Bakersfield
Suppose the coordinates for this locality were interpolated to the nearest
1/10th minute from the printed USGS Taft 1:100,000 Quad map and the
distance from the center of Bakersfield to the furthest city limit is 2
mi.
Locality Type: Distance along path
Coordinate Source: USGS map: 1:100,000
Coordinate Format: degrees decimal minutes
Latitude (input): 35 degrees 26.1' N
Longitude (input): 118 degrees 48.1' W
Datum: NAD27
Coordinate Precision: 0.1 minutes
Radial of Feature: 2 mi
Measurement Error: 0.03107 mi (0.5 mm on 1:100,000 map)
Distance Units: mi
Distance Precision: 1 mi
Decimal Latitude: 35.435
Decimal Longitude: -118.8016667
Uncertainty (m): 4363 m (2.711 mi)
Uncertainty sources: 50 m (0.03107 mi) from printed USGS 1:100,000 map accuracy,
239 m (0.148 mi) from coordinate precision 0.1 minutes, 3219 m (2 mi) from the extent of
the named place, 50 m (0.03107 mi) from the ability to distinguish 0.5 mm on a printed USGS
1:100,000 map, 805 m (0.5 mi) from the 1 mi distance precision
Distance Along Orthogonal Directions
Example: 2 mi E and 3 mi N of Bakersfield
Suppose the coordinates for Bakersfield (the named place) came from the GNIS database
(a gazetteer), the coordinates of the locality were calculated to the nearest second,
and the distance from the center of Bakersfield to
the furthest city limit is 2 mi.
Locality Type: Distance along orthogonal directions
Coordinate Source: gazetteer
Coordinate Format: degrees minutes seconds
Latitude (input): 35 degrees 25' 4" N
Longitude (input): 118 degrees 58' 54" W
Datum: not recorded
Coordinate Precision: nearest second
North or South Offset Distance: 3 mi
North or South Offset Direction: N
East or West Offset Distance: 2 mi
East or West Offset Direction: E
Radial of Feature: 2 mi
Measurement Error: 0
Distance Units: mi
Distance Precision: 1 mi
Decimal Latitude: 35.4612939
Decimal Longitude: -118.946227
Uncertainty (m): 7441 m (4.624 mi)
Uncertainty sources: 3045 m (0.049 mi) from unknown datum, 40 m (0.025 mi) from
coordinate precision nearest second, 3219 m (2 mi) from the extent of the named place,
1138 m (0.707 mi) from the 1 mi distance precision in two dimensions (the diagonal of a
0.5 mi by 0.5 mi square)
Distance at a Heading
Example 1: 10 mi E (by air) Bakersfield
Suppose the coordinates for Bakersfield came from the GNIS database
(a gazetteer), the coordinates of the locality were calculated to the nearest second,
and the distance from the center of Bakersfield to the furthest
city limit is 2 mi.
Locality Type: Distance at a heading
Coordinate Source: gazetteer
Coordinate Format: degrees minutes seconds
Latitude( input): 35 degrees 22' 24" N
Longitude(input): 118 degrees 50' 56 W
Datum: not recorded
Coordinate Precision: nearest second
Offset Distance: 10 mi
Radial of Feature: 2 mi
Measurement Error: 0
Distance Units: mi
Distance Precision: 10 mi
Decimal Latitude: 35.3733333
Decimal Longitude: -118.6717880
Uncertainty (m): 22208 m (13.8 mi)
Direction Precision: 45 degrees (between NE and SE, each 45 degrees from E)
Uncertainty sources: complicated combination of unknown datum, coordinate precision
nearest second, extent of the named place, distance precision, and direction precision
Example 2: 10 mi ENE (by air) Bakersfield
Suppose the coordinates for the locality were interpolated to the nearest
second from the USGS Gosford 1:24,000 Quad map on which you can distinguish
between millimeters and the distance from the center of Bakersfield to the furthest city
limit is 2 mi.
Locality Type: Distance at a heading
Coordinate Source: USGS map: 1:24,000
Coordinate Format: degrees minutes seconds
Latitude (input): 35 degrees 24' 21" N
Longitude (input): 118 degrees 51' 25" W
Datum: NAD27
Coordinate Precision: nearest second
Offset Distance: 10 mi
Radial of Feature: 2 mi
Measurement Error: 0.007 mi (0.5 mm on 1:24,000 map)
Distance Units: mi
Distance Precision: 10 mi
Decimal Latitude: 35.4613445
Decimal Longitude: -118.6932627
Uncertainty (m): 12055 m (7.491 mi)
Direction Precision: 11.25 degrees either side of ENE
Uncertainty sources: complicated combination of map accuracy, unknown datum,
coordinate precision nearest second, extent of the named place, measurement accuracy
(0.5 mm at 1:24,000), distance precision, and direction precision
1. NIMA, 2000. Department of Defense World Geodetic System 1984. Its Definition and relationships with local geodetic systems. TR8350.2, Third Edition, 3 Jan 2000. This document can be found at the following URL:
http://earth-info.nga.mil/GandG/publications/tr8350.2/wgs84fin.pdf2. USGS, 1999. National Mapping Program Technical Instructions. Part 2. Specifications. Standards for Digital Line Graphs. This document can be found at the following URL:
http://nationalmap.gov/standards/pdf/Pdlg0999.pdf3. NOAA. Differential GPS (DGPS) & Your Chart. Specified Chart Accuracy.
http://www.nauticalcharts.noaa.gov/nsd/DGPSchart.html4. The results of this work were published as the point-radius method in the following manuscripts:
Georeferencing Calculator:
Map Accuracy Standards:
|
Copyright 2001-2019, The Regents of the University of California |
|
John Wieczorek 24 Sep 2001 |
Rev. 14 Dec 2019 |


Positioning is a way of telling the browser how we want our elements to interact with the viewport. The different position values allow our elements to take on a range of positioning behaviours.
The position properties look like this:
Different types:
static
Static is the positioning element that all elements start off with by default on the page. If we’re thinking about elements as a block of pixels, static just means it will display in its normal form. The static property is the default property so the only time we would declare it would be if it were to overwrite a property declaration made by a parent element. To try and make an attempt at an analogy, the static element acts like a still photo frame of your family (without you in it...).Absolute
This position property lets you place items literally wherever you want on the page. With the use of top, bottom, left and right you can position the item in the exact spot you want. The Absolute element does have a higher Z-index than static element’s, however you can use the z-index property to get the element to display at the desired depth. An analogy for the absolute position value would be, if you took the still photo from the above static positioning analogy, then got a pin and a cut out photo of yourself and pinned it where ever you wanted on the image of you’re family which you didn’t make the cut for the first time.
Fixed
Fixed is exactly what it sounds like. The element is fixed within the viewport of the display. Ever noticed how some header nav’s stay in place as you scroll down the page? Thats a fixed position element. An example best portrays the fixed element because there’s one right there. not there, up there. Your browser top bar acts in the way a fixed element would within a web page. (Also the heading for this blog post!)
Relative
Relative is an element I have had trouble with in the past, but in my research for this post I can across a line that was very simple, thats helped me understand how it works. Relative means to be relative to itself. So naturally, a relative element won’t appear any different to itself in a static form if nothing else is done. It is not until we use the position properties top, bottom, left, right and z-index that it starts to take on its relative position. So for example, if you wanted to move a button up from the bottom of where it is currently, you could set the css rules : .className { position: relative; bottom: 5vh; }
Sticky
The sticky position property acts somewhat like a mix between a static element and a fixed, where in it will follow the flow of the page scroll, until it runs out of room, then it will remain fixed at the down stream point of the scroll flow until the container element it is within has been scrolled passed. An example of this may be on an online paper, where the name and page of the paper may be displayed at the top, and while you scroll down that page it will display that info, until you reach the next page where its name and new page number will make its way up the display and take its place at the top.


#include <sys/socket.h>
#include <linux/if_packet.h>
#include <net/ethernet.h> /* the L2 protocols */ packet_socket = socket(AF_PACKET, int socket_type, int protocol);
The socket_type is either SOCK_RAW for raw packets including the link-level header or SOCK_DGRAM for cooked packets with the link-level header removed. The link-level header information is available in a common format in a sockaddr_ll. protocol is the IEEE 802.3 protocol number in network byte order. See the <linux/if_ether.h> include file for a list of allowed protocols. When protocol is set to htons(ETH_P_ALL) then all protocols are received. All incoming packets of that protocol type will be passed to the packet socket before they are passed to the protocols implemented in the kernel.
Only processes with effective UID 0 or the CAP_NET_RAW capability may open packet sockets.
SOCK_RAW packets are passed to and from the device driver without any changes in the packet data. When receiving a packet, the address is still parsed and passed in a standard sockaddr_ll address structure. When transmitting a packet, the user supplied buffer should contain the physical layer header. That packet is then queued unmodified to the network driver of the interface defined by the destination address. Some device drivers always add other headers. SOCK_RAW is similar to but not compatible with the obsolete AF_INET/SOCK_PACKET of Linux 2.0.
SOCK_DGRAM operates on a slightly higher level. The physical header is removed before the packet is passed to the user. Packets sent through a SOCK_DGRAM packet socket get a suitable physical layer header based on the information in the sockaddr_ll destination address before they are queued.
By default all packets of the specified protocol type are passed to a packet socket. To get packets only from a specific interface use bind(2) specifying an address in a struct sockaddr_ll to bind the packet socket to an interface. Only the sll_protocol and the sll_ifindex address fields are used for purposes of binding.
The connect(2) operation is not supported on packet sockets.
When the MSG_TRUNC flag is passed to recvmsg(2), recv(2), recvfrom(2) the real length of the packet on the wire is always returned, even when it is longer than the buffer.
struct sockaddr_ll { unsigned short sll_family; /* Always AF_PACKET */ unsigned short sll_protocol; /* Physical layer protocol */ int sll_ifindex; /* Interface number */ unsigned short sll_hatype; /* ARP hardware type */ unsigned char sll_pkttype; /* Packet type */ unsigned char sll_halen; /* Length of address */ unsigned char sll_addr[8]; /* Physical layer address */ };
sll_protocol is the standard ethernet protocol type in network byte order as defined in the <linux/if_ether.h> include file. It defaults to the socket's protocol. sll_ifindex is the interface index of the interface (see netdevice(7)); 0 matches any interface (only permitted for binding). sll_hatype is an ARP type as defined in the <linux/if_arp.h> include file. sll_pkttype contains the packet type. Valid types are PACKET_HOST for a packet addressed to the local host, PACKET_BROADCAST for a physical layer broadcast packet, PACKET_MULTICAST for a packet sent to a physical layer multicast address, PACKET_OTHERHOST for a packet to some other host that has been caught by a device driver in promiscuous mode, and PACKET_OUTGOING for a packet originated from the local host that is looped back to a packet socket. These types make sense only for receiving. sll_addr and sll_halen contain the physical layer (e.g., IEEE 802.3) address and its length. The exact interpretation depends on the device.
When you send packets it is enough to specify sll_family, sll_addr, sll_halen, sll_ifindex. The other fields should be 0. sll_hatype and sll_pkttype are set on received packets for your information. For bind only sll_protocol and sll_ifindex are used.
struct packet_mreq { int mr_ifindex; /* interface index */ unsigned short mr_type; /* action */ unsigned short mr_alen; /* address length */ unsigned char mr_address[8]; /* physical layer address */ };
mr_ifindex contains the interface index for the interface whose status should be changed. The mr_type parameter specifies which action to perform. PACKET_MR_PROMISC enables receiving all packets on a shared medium (often known as "promiscuous mode"), PACKET_MR_MULTICAST binds the socket to the physical layer multicast group specified in mr_address and mr_alen, and PACKET_MR_ALLMULTI sets the socket up to receive all multicast packets arriving at the interface.
In addition, the traditional ioctls SIOCSIFFLAGS, SIOCADDMULTI, SIOCDELMULTI can be used for the same purpose.
struct tpacket_auxdata { __u32 tp_status; __u32 tp_len; /* packet length */ __u32 tp_snaplen; /* captured length */ __u16 tp_mac; __u16 tp_net; __u16 tp_vlan_tci; __u16 tp_padding; };
Fanout supports multiple algorithms to spread traffic between sockets. The default mode, PACKET_FANOUT_HASH, sends packets from the same flow to the same socket to maintain per-flow ordering. For each packet, it chooses a socket by taking the packet flow hash modulo the number of sockets in the group, where a flow hash is a hash over network-layer address and optional transport-layer port fields. The load-balance mode PACKET_FANOUT_LB implements a round-robin algorithm. PACKET_FANOUT_CPU selects the socket based on the CPU that the packet arrived on. PACKET_FANOUT_ROLLOVER processes all data on a single socket, moves to the next when one becomes backlogged. PACKET_FANOUT_RND selects the socket using a pseudo-random number generator. PACKET_FANOUT_QM (available since Linux 3.14) selects the socket using the recorded queue_mapping of the received skb.
Fanout modes can take additional options. IP fragmentation causes packets from the same flow to have different flow hashes. The flag PACKET_FANOUT_FLAG_DEFRAG, if set, causes packet to be defragmented before fanout is applied, to preserve order even in this case. Fanout mode and options are communicated in the second 16 bits of the integer option value. The flag PACKET_FANOUT_FLAG_ROLLOVER enables the roll over mechanism as a backup strategy: if the original fanout algorithm selects a backlogged socket, the packet rolls over to the next available one.
struct tpacket_stats { unsigned int tp_packets; /* Total packet count */ unsigned int tp_drops; /* Dropped packet count */ };
Receiving statistics resets the internal counters. The statistics structure differs when using a ring of variant TPACKET_V3.
In addition, all standard ioctls defined in netdevice(7) and socket(7) are valid on packet sockets.
In addition, other errors may be generated by the low-level driver.
The SOCK_DGRAM packet sockets make no attempt to create or parse the IEEE 802.2 LLC header for a IEEE 802.3 frame. When ETH_P_802_3 is specified as protocol for sending the kernel creates the 802.3 frame and fills out the length field; the user has to supply the LLC header to get a fully conforming packet. Incoming 802.3 packets are not multiplexed on the DSAP/SSAP protocol fields; instead they are supplied to the user as protocol ETH_P_802_2 with the LLC header prefixed. It is thus not possible to bind to ETH_P_802_3; bind to ETH_P_802_2 instead and do the protocol multiplex yourself. The default for sending is the standard Ethernet DIX encapsulation with the protocol filled in.
Packet sockets are not subject to the input or output firewall chains.
struct sockaddr_pkt { unsigned short spkt_family; unsigned char spkt_device[14]; unsigned short spkt_protocol; };
spkt_family contains the device type, spkt_protocol is the IEEE 802.3 protocol type as defined in <sys/if_ether.h> and spkt_device is the device name as a null-terminated string, for example, eth0.
This structure is obsolete and should not be used in new code.
#ifndef SOL_PACKET #define SOL_PACKET 263 #endifThis is fixed in later glibc versions.
The IEEE 802.2/803.3 LLC handling could be considered as a bug.
Socket filters are not documented.
The MSG_TRUNC recvmsg(2) extension is an ugly hack and should be replaced by a control message. There is currently no way to get the original destination address of packets via SOCK_DGRAM.
RFC 894 for the standard IP Ethernet encapsulation. RFC 1700 for the IEEE 802.3 IP encapsulation.
The <linux/if_ether.h> include file for physical layer protocols.
The Linux kernel source tree. /Documentation/networking/filter.txt describes how to apply Berkeley Packet Filters to packet sockets. /tools/testing/selftests/net/psock_tpacket.c contains example source code for all available versions of PACKET_RX_RING and PACKET_TX_RING.


#!/usr/bin/env python
########################################################################
#
# (C) 2015, Chris Houseknecht<EMAIL_ADDRESS>#
# This file is part of Ansible
#
# Ansible is free software: you can redistribute it and/or modify
# it under the terms of the GNU General Public License as published by
# the Free Software Foundation, either version 3 of the License, or
# (at your option) any later version.
#
# Ansible is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
# GNU General Public License for more details.
#
# You should have received a copy of the GNU General Public License
# along with Ansible. If not, see <http://www.gnu.org/licenses/>.
#
########################################################################
from __future__ import (absolute_import, division, print_function)
__metaclass__ = type
import getpass
import json
import urllib
from urllib2 import quote as urlquote, HTTPError
from urlparse import urlparse
from ansible.errors import AnsibleError, AnsibleOptionsError
from ansible.module_utils.urls import open_url
from ansible.utils.color import stringc
try:
from __main__ import display
except ImportError:
from ansible.utils.display import Display
display = Display()
[docs]class GalaxyLogin(object):
''' Class to handle authenticating user with Galaxy API prior to performing CUD operations '''
GITHUB_AUTH = 'https://api.github.com/authorizations'
def __init__(self, galaxy, github_token=None):
self.galaxy = galaxy
self.github_username = None
self.github_password = None
if github_token == None:
self.get_credentials()
[docs] def get_credentials(self):
display.display(u'\n\n' + "We need your " + stringc("Github login",'bright cyan') +
" to identify you.", screen_only=True)
display.display("This information will " + stringc("not be sent to Galaxy",'bright cyan') +
", only to " + stringc("api.github.com.","yellow"), screen_only=True)
display.display("The password will not be displayed." + u'\n\n', screen_only=True)
display.display("Use " + stringc("--github-token",'yellow') +
" if you do not want to enter your password." + u'\n\n', screen_only=True)
try:
self.github_username = raw_input("Github Username: ")
except:
pass
try:
self.github_password = getpass.getpass("Password for %s: " % self.github_username)
except:
pass
if not self.github_username or not self.github_password:
raise AnsibleError("Invalid Github credentials. Username and password are required.")
[docs] def remove_github_token(self):
'''
If for some reason an ansible-galaxy token was left from a prior login, remove it. We cannot
retrieve the token after creation, so we are forced to create a new one.
'''
try:
tokens = json.load(open_url(self.GITHUB_AUTH, url_username=self.github_username,
url_password=self.github_password, force_basic_auth=True,))
except HTTPError as e:
res = json.load(e)
raise AnsibleError(res['message'])
for token in tokens:
if token['note'] == 'ansible-galaxy login':
display.vvvvv('removing token: %s' % token['token_last_eight'])
try:
open_url('https://api.github.com/authorizations/%d' % token['id'], url_username=self.github_username,
url_password=self.github_password, method='DELETE', force_basic_auth=True,)
except HTTPError as e:
res = json.load(e)
raise AnsibleError(res['message'])
[docs] def create_github_token(self):
'''
Create a personal authorization token with a note of 'ansible-galaxy login'
'''
self.remove_github_token()
args = json.dumps({"scopes":["public_repo"], "note":"ansible-galaxy login"})
try:
data = json.load(open_url(self.GITHUB_AUTH, url_username=self.github_username,
url_password=self.github_password, force_basic_auth=True, data=args))
except HTTPError as e:
res = json.load(e)
raise AnsibleError(res['message'])
return data['token']