githubmirror/omim

3party/open-location-code/openlocationcode.h
113 строк5 KB
Ilya Zverev
[search] Add Open Location Code library
04 апр 2018, 15:40
04 апр 2018, 15:4034a4e33
// The OpenLocationCode namespace provides a way of encoding between geographic
// coordinates and character strings that use a disambiguated character set.
// The aim is to provide a more convenient way for humans to handle geographic
// coordinates than latitude and longitude pairs.
//
// The codes can be easily read and remembered, and truncating codes converts
// them from a point to an area, meaning that where extreme accuracy is not
// required the codes can be shortened.
#ifndef LOCATION_OPENLOCATIONCODE_OPENLOCATIONCODE_H_
#define LOCATION_OPENLOCATIONCODE_OPENLOCATIONCODE_H_

#include <string>

#include "codearea.h"

namespace openlocationcode {

// Encodes a pair of coordinates and return an Open Location Code representing a
// rectangle that encloses the coordinates. The accuracy of the code is
// controlled by the code length.
//
// Returns an Open Location Code with code_length significant digits. The string
// returned may be one character longer if it includes a separator character
// for formatting.
std::string Encode(const LatLng &location, size_t code_length);

// Encodes a pair of coordinates and return an Open Location Code representing a
// rectangle that encloses the coordinates. The accuracy of the code is
// sufficient to represent a building such as a house, and is approximately
// 13x13 meters at Earth's equator.
std::string Encode(const LatLng &location);

// Decodes an Open Location Code and returns a rectangle that describes the area
// represented by the code.
CodeArea Decode(const std::string &code);

// Removes characters from the start of an OLC code.
// This uses a reference location to determine how many initial characters
// can be removed from the OLC code. The number of characters that can be
// removed depends on the distance between the code center and the reference
// location.
//
// The reference location must be within a safety factor of the maximum range.
// This ensures that the shortened code will be able to be recovered using
// slightly different locations.
//
// If the code isn't a valid full code or is padded, it cannot be shortened and
// the code is returned as-is.
std::string Shorten(const std::string &code, const LatLng &reference_location);

// Recovers the nearest matching code to a specified location.
// Given a short Open Location Code of between four and seven characters,
// this recovers the nearest matching full code to the specified location.
//
// If the code isn't a valid short code, it cannot be recovered and the code
// is returned as-is.
std::string RecoverNearest(const std::string &short_code,
                           const LatLng &reference_location);

// Returns the number of valid Open Location Code characters in a string. This
// excludes invalid characters and separators.
size_t CodeLength(const std::string &code);

// Determines if a code is valid and can be decoded.
// The empty string is a valid code, but whitespace included in a code is not
// valid.
bool IsValid(const std::string &code);

// Determines if a code is a valid short code.
bool IsShort(const std::string &code);

// Determines if a code is a valid full Open Location Code.
//
// Not all possible combinations of Open Location Code characters decode to
// valid latitude and longitude values. This checks that a code is valid
// and also that the latitude and longitude values are legal. If the prefix
// character is present, it must be the first character. If the separator
// character is present, it must be after four characters.
bool IsFull(const std::string &code);

namespace internal {
// The separator character is used to identify strings as OLC codes.
extern const char kSeparator;
// Provides the position of the separator.
extern const size_t kSeparatorPosition;
// Defines the maximum number of digits in a code (excluding separator). Codes
// with this length have a precision of less than 1e-10 cm at the equator.
extern const size_t kMaximumDigitCount;
// Padding is used when less precise codes are desired.
extern const char kPaddingCharacter;
// The alphabet of the codes.
extern const char kAlphabet[];
// The number base used for the encoding.
extern const size_t kEncodingBase;
// How many characters use the pair algorithm.
extern const size_t kPairCodeLength;
// Number of columns in the grid refinement method.
extern const size_t kGridColumns;
// Number of rows in the grid refinement method.
extern const size_t kGridRows;
// Defines the minimum pair resolution (in degrees) to remove when shortening a
// code.
extern const double kMinShortenDegrees;
// Gives the exponent used for the first pair.
extern const size_t kInitialExponent;
// Size of the initial grid in degrees. This is the size of the area represented
// by a 10 character code, and is kEncodingBase ^ (2 - kPairCodeLength / 2).
extern const double kGridSizeDegrees;
}  // namespace internal

}  // namespace openlocationcode

#endif  // LOCATION_OPENLOCATIONCODE_OPENLOCATIONCODE_H_