Modules¶

projpicker¶

This module implements the CLI and API of ProjPicker.

class projpicker.Geom(is_latlon, type, geom)¶

property geom¶: Alias for field number 2

property is_latlon¶: Alias for field number 0

property type¶: Alias for field number 1

class projpicker.GeomBBox(is_latlon, type, geom, bbox)¶

property bbox¶: Alias for field number 3

property geom¶: Alias for field number 2

property is_latlon¶: Alias for field number 0

property type¶: Alias for field number 1

projpicker.bbox_and(bbox1, bbox2)¶

Return the set-theoretic result of the AND operation on bbox1 and bbox2.

Parameters

bbox1 (list) – List of BBox instances.
bbox2 (list) – List of BBox instances.

Returns

List of BBox instances resulting from the AND operation between bbox1 and bbox2.

Return type

list

projpicker.bbox_binary_operator(bbox1, bbox2, bbox_op)¶

Return the set-theoretic result of the bbox_op binary operator on bbox1 and bbox2. This function invokes invidial binary operator functions.

Parameters

bbox1 (list) – List of BBox instances.
bbox2 (list) – List of BBox instances.
bbox_op (str) – Binary operator (and, or, xor).

Returns

List of BBox instances resulting from the op binary operation between bbox1 and bbox2.

Return type

list

Raises

ValueError – If bbox_op is not one of “and”, “or”, or “xor”.

projpicker.bbox_not(bbox, bbox_all)¶

Return the set-theoretic complement of bbox.

Parameters

bbox (list) – List of BBox instances.
bbox_all (list) – List of BBox instances in the universe.

Returns

List of BBox instances from bbox_all that are not in the input bbox.

Return type

list

projpicker.bbox_or(bbox1, bbox2)¶

Return the set-theoretic result of the OR operation on bbox1 and bbox2.

Parameters

bbox1 (list) – List of BBox instances.
bbox2 (list) – List of BBox instances.

Returns

List of BBox instances resulting from the OR operation between bbox1 and bbox2.

Return type

list

projpicker.bbox_xor(bbox1, bbox2)¶

Return the set-theoretic result of the XOR operation on bbox1 and bbox2.

Parameters

bbox1 (list) – List of BBox instances.
bbox2 (list) – List of BBox instances.

Returns

List of BBox instances resulting from the XOR operation between bbox1 and bbox2.

Return type

list

projpicker.calc_area(bbox)¶

Calculate the surface area of the segment defined by south, north, west, and east floats in decimal degrees. North latitude must be greater than or equal to south latitude, but east longitude can be less than west longitude wieh the segment crosses the antimeridian.

Parameters: bbox (list) – List of south, north, west, and east floats in decimal degrees.
Returns: Area in square kilometers.
Return type: float
Raises: ValueError – If s or n is outside [-90, 90], or s is greater than n.

projpicker.calc_horiz_radius_at_lat(lat)¶

Calculate the horizontal distance from the y-axis to the latitude line.

Parameters: lat (float) – Latitude in decimal degrees.
Returns: Radius.
Return type: float

projpicker.calc_radius_at_lat(lat)¶

Calculate the distance from the center to the latitude line.

Parameters: lat (float) – Latitude in decimal degrees.
Returns: Radius.
Return type: float
Raises: ValueError – If lat is outside [-90, 90].

projpicker.calc_xy_at_lat(lat)¶

Calculate x and y at a given latitude on Earth’s cross section that passes through the South and North Poles. The x- and y-axes are from the center to the right equatorial point and North Pole, respectively. The x-y space is first scaled to [-1, 1]**2, which is then rescaled back to x-y later.

Parameters: lat (float) – Latitude in decimal degrees.
Returns: x and y.
Return type: float, float
Raises: ValueError – If lat is outside [-90, 90].

projpicker.calc_xy_at_lat_noscaling(lat)¶

Calculate x and y at a given latitude on Earth’s cross section that passes through the South and North Poles. The x- and y-axes are from the center to the right equatorial point and North Pole, respectively. The radius at the latitude is first determined, and x and y are calculated using trigonometry functions.

Parameters: lat (float) – Latitude in decimal degrees.
Returns: x and y.
Return type: float, float

projpicker.calc_xy_at_lat_scaling(lat)¶

Parameters: lat (float) – Latitude in decimal degrees.
Returns: x and y.
Return type: float, float
Raises: ValueError – If lat is outside [-90, 90].

projpicker.create_projpicker_db(overwrite=False, projpicker_db=None, proj_db=None)¶

Create a projpicker.db sqlite database. If projpicker_db or proj_db is None (default), get_projpicker_db() or get_proj_db() is used, respectively.

Parameters

overwrite (bool) – Whether or not to overwrite projpicker.db. Defaults to False.
projpicker_db (str) – projpicker.db path. Defaults to None.
proj_db (str) – proj.db path. Defaults to None.

Raises

FileExistsError – If projpicker_db already exists.

projpicker.dictify_bbox(bbox)¶

Convert a list of BBox instances to a list of bbox dicts.

Parameters: bbox (list or BBox) – List of BBox instances or a BBox instance.
Returns: List of bbox dicts.
Return type: list

projpicker.extract_srids(bbox)¶

Extract spatial reference identifiers (SRIDs) from a list of BBox instances.

Parameters: bbox (list or BBox) – List of BBox instances or a BBox instance.
Returns: List of SRID strs.
Return type: list

projpicker.find_unit(proj_table, crs_auth, crs_code, proj_cur)¶

Find and return the unit of a given coordinate reference system (CRS) using the cursor.

Parameters

proj_table (str) – Name of a CRS table in proj.db.
crs_auth – CRS authority name
crs_code – CRS code
proj_cur (sqlite3.Cursor) – proj.db cursor.

Returns

Unit name.

Return type

str

Raises

RuntimeError – If no or multiple units of measure are found.

projpicker.get_proj_db(proj_db=None)¶

Return the proj.db path. If one is given as an argument, return it as is. Otherwise (None), check the PROJ_DB environment variable. If this variable is not available, check the PROJ_LIB environment variable as it is likely to be set by PROJ. If none works, return the default “/usr/share/proj/proj.db”.

Parameters: proj_db (str) – User-provided proj.db path. Defaults to None.
Returns: proj.db path.
Return type: str

projpicker.get_projpicker_db(projpicker_db=None)¶

Return the projpicker.db path. If one is given as an argument, return it as is. Otherwise (None), check the PROJPICKER_DB environment variable. If this variable is not available, return the default “projpicker.db”.

Parameters: projpicker_db (str) – User-provided projpicker.db path. Defaults to None.
Returns: projpicker.db path.
Return type: str

projpicker.get_separator(separator)¶

Convert a separator name to its corresponding character. If an unsupported name is given, return it as is.

Parameters: separator (str) – Separator name. It supports special names including pipe (|), comma (,), space ( ), tab (t), and newline (n).
Returns: Separator character.
Return type: str

projpicker.get_version()¶

Return the ProjPicker version str from the VERSION file.

Returns: ProjPicker version.
Return type: str

projpicker.is_latlon()¶: Return True if the coordinate system is latitude-longitude. Otherwise, return False.

projpicker.jsonify_bbox(bbox)¶

Convert a list of BBox instances to a JSON object.

Parameters: bbox (list or BBox) – List of BBox instances or a BBox instance.
Returns: JSONified bbox rows.
Return type: str

projpicker.main()¶: Implement the command-line interface to start() and the standalone web server.

projpicker.match_geoms(gbbox1, gbbox2, match_max=0, match_tol=1)¶

Match two geometries in different coordinate systems within a given distance match_tol in xy and return a subset list of the BBox instances of the xy geometry that can be transformed to the other geometry in latlon. Only the first match_max number of matches are returned. If match_max is 0, all matches are returned. This operation is useful when the coordinates of a geometry in both latlon and xy are known. This operation requires the pyproj module and is very slow.

Parameters

gbbox1 (GeomBBox) – Geometry-bbox 1.
gbbox2 (GeomBBox) – Geometry-bbox 2.
match_max (int) – Maximum number of matches to return. 0 to return all. Defaults to 0.
match_tol (float) – Positive distance tolerance in unknown xy units. Defaults to 1.

Returns

List of matched BBox instances from the BBox instances of the xy geometry.

Return type

list

Raises

SyntaxError – If syntax errors are encountered.

projpicker.message(*args, end=None)¶

Print args to stderr immediately.

Parameters

*args (arguments) – Arguments to print. Passed to print().
end (str) – Passed to print(). Defaults to None.

projpicker.normalize_lines(lines)¶

Normalize a list of str lines in place by splitting combined lines into individual lines.

Parameters: lines (list) – List of str lines.

projpicker.parse()¶

Provide the main() function and Sphinx with argument parsing information for the command-line interface.

Returns: Argument parser.
Return type: argparse.ArgumentParser

projpicker.parse_bboxes(bboxes)¶

Parse a list of strs of four floats, and return them as a list. A list of four floats can be used in place of a str of four floats. Any unparsable str is ignored. If an output from this function is passed, the same output is returned.

For example, [“10,20,30,40”, [50,60,70,80]] returns [[10.0, 20.0, 30.0, 40.0], [50.0, 60.0, 70.0, 80.0]]

Parameters: bboxes (list) – List of parsable strs of four floats.
Returns: List of lists of four floats.
Return type: list

projpicker.parse_geom(geom, geom_type='point')¶

Parse a geometry and return it as a list.

Parameters

geom (list) – List or a str of a parsable geometry. See parse_point(), parse_poly(), and parse_bbox().
geom_type (str) – Geometry type (point, poly, bbox). Defaults to “point”.

Returns

List of a parsed geometry.

Return type

list

Raises

ValueError – If geom_type is not one of “point”, “poly”, or “bbox”.

projpicker.parse_geoms(geoms, geom_type='point')¶

Parse geometries and return them as a list.

Parameters

geom (list) – List of parsable geometries. See parse_points(), parse_polys(), and parse_bboxes().
geom_type (str) – Geometry type (point, poly, bbox). Defaults to “point”.

Returns

List of parsed geometries.

Return type

list

Raises

ValueError – If geom_type is not one of “point”, “poly”, or “bbox”.

projpicker.parse_mixed_geoms(geoms)¶

Parse mixed input geometries and return them as a list. The first non-empty element in geoms can optionally be “all”, “and”, “or”, “xor”, or “not” to set the query operator. The “all” query operator ignores the rest of input geometries and returns all bbox rows from the database. The “and” query operator performs the intersection of bbox rows while the “or” operator the union. Geometry types can be specified using words “point” (default), “poly”, and “bbox”. Words “latlon” (default) and “xy” start the latitude-longitude and x-y coordinate systems, respectively. This function ignores the current coordinate system set by set_coordinate_system(), set_latlon(), or set_xy(), and always starts in the latitude-longitude coordinate system by default.

Parameters: geoms (list or str) – List of “point”, “poly”, “bbox”, “none”, “all”, “latlon”, “xy”, “and”, “or”, “xor”, “not”, “match”, “unit=”, “proj_table=”, “match_tol=”, “match_max=”, and parsable geometries. The first word can be either “and”, “or”, “xor”, or “postfix”. See parse_points(), parse_polys(), and parse_bboxes().
Returns: List of parsed geometries.
Return type: list
Raises: SyntaxError – If syntax errors are encountered.

projpicker.parse_points(points)¶

Parse a list of strs of latitude and longitude or x and y, and return a list of lists of two floats. A list of two floats can be used in place of a str of latitude and longitude. Any unparsable str is ignored with a warning. If an output from this function is passed, the same output is returned.

For example, [“1,2”, “3,4”, “,”, “5,6”, “7,8”] or [[1,2], “3,4”, “,”, “5,6”, [7,8]] returns the same [[1.0, 2.0], [3.0, 4.0], [5.0, 6.0], [7.0, 8.0]] with a warning about the unparsable comma.

Parameters: points (list) – List of parsable point geometries.
Returns: List of lists of parsed point geometries in float.
Return type: list

projpicker.parse_poly(points)¶

Parameters: points (list) – List of parsable point geometries.
Returns: List of lists of parsed point geometries in float.
Return type: list

projpicker.parse_polys(polys)¶

Parse a list of strs of latitude and longitude or x and y, and return a list of lists of lists of two floats. A list of two floats can be used in place of a str of coordinates. Any unparsable str starts a new poly. If an output from this function is passed, the same output is returned.

For example, [“1,2”, “3,4”, “,”, “5,6”, “7,8”] or [[1,2], “3,4”, “,”, “5,6”, [7,8]] returns the same [[[1.0, 2.0], [3.0, 4.0]], [[5.0, 6.0], [7.0, 8.0]]].

Parameters: points (list) – List of parsable point geometries with an unparsable str as a poly separator.
Returns: List of lists of lists of parsed point geometries in float.
Return type: list

projpicker.print_bbox(bbox, outfile=<_io.TextIOWrapper name='<stdout>' mode='w' encoding='UTF-8'>, header=True, separator='|')¶

Print a list of BBox instances in a plain format.

Parameters

bbox (list) – List of BBox instances.
outfile (str) – Output file object. Defaults to sys.stdout.
header (bool) – Whether or not to print header. Defaults to True.
separator (str) – Column separator. It supports special names including pipe (|), comma (,), space ( ), tab (t), and newline (n). Defaults to “|”.

projpicker.print_srids(bbox, outfile=<_io.TextIOWrapper name='<stdout>' mode='w' encoding='UTF-8'>, separator='\n')¶

Print a list of spatial reference identifiers (SRIDs) in a plain format.

Parameters

bbox (list) – List of BBox instances.
outfile (str) – Output file object. Defaults to sys.stdout.
separator (str) – SRID separator. It supports special names including pipe (|), comma (,), space ( ), tab (t), and newline (n). Defaults to “n”.

projpicker.query_all(unit='any', proj_table='any', projpicker_db=None)¶

Return a list of all BBox instances in unit in proj_table. Each BBox instance is a named tuple with all the columns from the bbox table in projpicker.db. Results are sorted by area. If projpicker_db is None (default), get_projpicker_db() is used.

Parameters

unit (str) – Unit values from projpicker.db. Defaults to “any”.
proj_table (str) – Proj table values from projpicker.db. Defaults to “any”.
projpicker_db (str) – projpicker.db path. Defaults to None.

Returns

List of all BBox instances sorted by area.

Return type

list

projpicker.query_all_using_bbox(prevbbox, unit='any', proj_table='any')¶

Return a subset list of input BBox instances in unit in proj_table. Each BBox instance is a named tuple with all the columns from the bbox table in projpicker.db. This function is used to perform an intersection operation on BBox instances consecutively.

Parameters

prevbbox (list) – List of BBox instances from a previous query.
unit (str) – Unit values from projpicker.db. Defaults to “any”.
proj_table (str) – Proj table values from projpicker.db. Defaults to “any”.

Returns

List of queried BBox instances sorted by area.

Return type

list

projpicker.query_bbox(bbox, unit='any', proj_table='any', projpicker_db=None)¶

Return a list of BBox instances in unit in proj_table that completely contain an input bbox geometry. Each BBox instance is a named tuple with all the columns from the bbox table in projpicker.db. Results are sorted by area from the smallest to largest. If projpicker_db is None (default), get_projpicker_db() is used.

Parameters

bbox (list or str) – List of four floats or a parsable str of a bbox geometry. See parse_bbox().
unit (str) – Unit values from projpicker.db. Defaults to “any”.
proj_table (str) – Proj table values from projpicker.db. Defaults to “any”.
projpicker_db (str) – projpicker.db path. Defaults to None.

Returns

List of queried BBox instances sorted by area.

Return type

list

projpicker.query_bbox_using_bbox(prevbbox, bbox, unit='any', proj_table='any')¶

Return a subset list of input BBox instances in unit in proj_table that completely contain an input bbox geometry defined by sout, north, west, and east. Each BBox instance is a named tuple with all the columns from the bbox table in projpicker.db. This function is used to perform an intersection operation on bbox rows consecutively.

Parameters

prevbbox (list) – List of BBox instances from a previous query.
bbox (list or str) – List of south, north, west, and east floats in decimal degrees or a parsable str of south, north, west, and east. See parse_bbox().
unit (str) – Unit values from projpicker.db. Defaults to “any”.
proj_table (str) – Proj table values from projpicker.db. Defaults to “any”.

Returns

List of queried BBox instances sorted by area.

Return type

list

projpicker.query_bboxes(bboxes, query_op='and', unit='any', proj_table='any', projpicker_db=None)¶

Return a list of BBox instances in unit in proj_table that completely contain input bbox geometries. Each BBox instance is a named tuple with all the columns from the bbox table in projpicker.db. The “and” query operator performs the intersection of bbox rows while the “or” operator the union and the “xor” operator the exclusive OR. Results are sorted by area from the smallest to largest. If projpicker_db is None (default), get_projpicker_db() is used.

Parameters

bboxes (list) – List of parsable bbox geometries. See parse_bboxes().
query_op (str) – Query operator (and, or, xor). Defaults to “and”.
unit (str) – Unit values from projpicker.db. Defaults to “any”.
proj_table (str) – Proj table values from projpicker.db. Defaults to “any”.
projpicker_db (str) – projpicker.db path. Defaults to None.

Returns

List of queried BBox instances sorted by area.

Return type

list

Raises

ValueError – If query_op is not one of “and”, “or”, or “xor”.

projpicker.query_bboxes_using_bbox(prevbbox, bboxes, query_op='and', unit='any', proj_table='any')¶

Return a subset list of input BBox instances in unit in proj_table that completely contain input bbox geometres. Each BBox instance is a named tuple with all the columns from the bbox table in projpicker.db. This function is used to perform an intersection operation on bbox rows consecutively.

Parameters

prevbbox (list) – List of BBox instances from a previous query.
bboxes (list) – List of parsable bbox geometries. See parse_bboxes().
query_op (str) – Query operator (and, or, xor). Defaults to “and”.
unit (str) – Unit values from projpicker.db. Defaults to “any”.
proj_table (str) – Proj table values from projpicker.db. Defaults to “any”.

Returns

List of queried BBox instances sorted by area.

Return type

list

Raises

ValueError – If query_op is not one of “and”, “or”, “xor”.

projpicker.query_geom(geom, geom_type='point', unit='any', proj_table='any', projpicker_db=None)¶

Return a list of BBox instances in unit in proj_table that completely contain an input geometry. Each BBox instance is a named tuple with all the columns from the bbox table in projpicker.db. Results are sorted by area from the smallest to largest. If projpicker_db is None (default), get_projpicker_db() is used.

Parameters

geom (list or str) – List or str of a parsable geometry. See parse_points(), parse_polys(), and parse_bboxes().
geom_type (str) – Geometry type (point, poly, bbox). Defaults to “point”.
unit (str) – Unit values from projpicker.db. Defaults to “any”.
proj_table (str) – Proj table values from projpicker.db. Defaults to “any”.
projpicker_db (str) – projpicker.db path. Defaults to None.

Returns

List of queried BBox instances sorted by area.

Return type

list

Raises

ValueError – If geom_type is not one of “point”, “poly”, or “bbox”.

projpicker.query_geom_using_bbox(prevbbox, geom, geom_type='point', unit='any', proj_table='any')¶

Return a subset list of input BBox instances in unit in proj_table that completely contain an input geometry. Each BBox instance is a named tuple with all the columns from the bbox table in projpicker.db. This function is used to perform an intersection operation on bbox rows consecutively.

Parameters

prevbbox (list) – List of BBox instances from a previous query.
geom (list or str) – List or str of a parsable geometry. See parse_points(), parse_polys(), and parse_bboxes().
geom_type (str) – Geometry type (point, poly, bbox). Defaults to “point”.
unit (str) – Unit values from projpicker.db. Defaults to “any”.
proj_table (str) – Proj table values from projpicker.db. Defaults to “any”.

Returns

List of queried BBox instances sorted by area.

Return type

list

Raises

ValueError – If geom_type is not one of “point”, “poly”, or “bbox”.

projpicker.query_geoms(geoms, geom_type='point', query_op='and', unit='any', proj_table='any', projpicker_db=None)¶

Return a list of BBox instances in unit in proj_table that completely contain input geometries. Each BBox instance is a named tuple with all the columns from the bbox table in projpicker.db. The “and” query operator performs the intersection of bbox rows while the “or” operator the union and the “xor” operator the exclusive OR. Results are sorted by area from the smallest to largest. If projpicker_db is None (default), get_projpicker_db() is used.

Parameters

geoms (list) – List of parsable geometries. See parse_points(), parse_polys(), and parse_bboxes().
geom_type (str) – Geometry type (point, poly, bbox). Defaults to “point”.
query_op (str) – Query operator (and, or, xor). Defaults to “and”.
unit (str) – Unit values from projpicker.db. Defaults to “any”.
proj_table (str) – Proj table values from projpicker.db. Defaults to “any”.
projpicker_db (str) – projpicker.db path. Defaults to None.

Returns

List of queried BBox instances sorted by area.

Return type

list

Raises

ValueError – If geom_type is not one of “point”, “poly”, or “bbox”, or query_op is not one of “and”, “or”, or “xor”.

projpicker.query_geoms_using_bbox(prevbbox, geoms, geom_type='point', query_op='and', unit='any', proj_table='any')¶

Return a subset list of input BBox instances in unit in proj_table that completely contain input geometries. Each BBox instance is a named tuple with all the columns from the bbox table in projpicker.db. This function is used to perform an intersection operation on bbox rows consecutively.

Parameters

prevbbox (list) – List of BBox instances from a previous query.
geoms (list) – List of parsable geometries. See parse_points(), parse_polys(), and parse_bboxes().
geom_type (str) – Geometry type (point, poly, bbox). Defaults to “point”.
query_op (str) – Query operator (and, or, xor). Defaults to “and”.
unit (str) – Unit values from projpicker.db. Defaults to “any”.
proj_table (str) – Proj table values from projpicker.db. Defaults to “any”.

Returns

List of queried BBox instances sorted by area.

Return type

list

Raises

ValueError – If geom_type is not one of “point”, “poly”, or “bbox”.

projpicker.query_mixed_geoms(geoms, projpicker_db=None)¶

Return a list of BBox instances that completely contain mixed input geometries. Each BBox instance is a named tuple with all the columns from the bbox table in projpicker.db. The first non-empty element in geoms can optionally be “all”, “and” (default), “or”, “xor”, or “postfix” to set the query operator. The “all” query operator ignores the rest of input geometries and returns all bbox rows from the database. The “and” query operator performs the intersection of bbox rows while the “or” operator the union and the “xor” operator the exclusive OR. The “postfix” operator supports the “and”, “or”, “xor”, and “not” operators in a postfix arithmetic manner. Geometry types can be specified using words “point” (default), “poly”, and “bbox”. Words “latlon” (default) and “xy” start the latitude-longitude and x-y coordinate systems, respectively. This function ignores the current coordinate system set by set_coordinate_system(), set_latlon(), or set_xy(), and always starts in the latitude-longitude coordinate system by default. Results are sorted by area from the smallest to largest. If projpicker_db is None (default), get_projpicker_db() is used.

Parameters

geoms (list or str) – List of “point”, “poly”, “bbox”, “none”, “all”, “latlon”, “xy”, “and”, “or”, “xor”, “not”, “match”, “unit=”, “proj_table=”, “match_tole=”, “match_max=”, and parsable geometries. The first word can be either “and”, “or”, “xor”, or “postfix”. See parse_points(), parse_polys(), and parse_bboxes().
projpicker_db (str) – projpicker.db path. Defaults to None.

Returns

List of queried BBox instances sorted by area.

Return type

list

Raises

SyntaxError – If syntax errors are encountered.

projpicker.query_point(point, unit='any', proj_table='any', projpicker_db=None)¶

Return a list of BBox instances in unit in proj_table that completely contain an input point geometry. Each BBox instance is a named tuple with all the columns from the bbox table in projpicker.db. Results are sorted by area from the smallest to largest. If projpicker_db is None (default), get_projpicker_db() is used.

Parameters

point (list or str) – List of two floats or a parsable point geometry. See parse_point().
unit (str) – Unit values from projpicker.db. Defaults to “any”.
proj_table (str) – Proj table values from projpicker.db. Defaults to “any”.
projpicker_db (str) – projpicker.db path. Defaults to None.

Returns

List of queried BBox instances sorted by area.

Return type

list

projpicker.query_point_using_bbox(prevbbox, point, unit='any', proj_table='any')¶

Return a subset list of input BBox instances in unit in proj_table that completely contain an input point geometry. Each BBox instance is a named tuple with all the columns from the bbox table in projpicker.db. This function is used to perform an intersection operation on BBox instances consecutively.

Parameters

prevbbox (list) – List of BBox instances from a previous query.
point (list or str) – List of two floats or a parsable str of a point. See parse_point().
unit (str) – Unit values from projpicker.db. Defaults to “any”.
proj_table (str) – Proj table values from projpicker.db. Defaults to “any”.

Returns

List of queried BBox instances sorted by area.

Return type

list

projpicker.query_points(points, query_op='and', unit='any', proj_table='any', projpicker_db=None)¶

Return a list of BBox instances in unit in proj_table that completely contain input point geometries. Each BBox instance is a named tuple with all the columns from the bbox table in projpicker.db. The “and” query operator performs the intersection of bbox rows while the “or” operator the union and the “xor” operator the exclusive OR. Results are sorted by area from the smallest to largest. If projpicker_db is None (default), get_projpicker_db() is used.

Parameters

points (list) – List of parsable point geometries. See parse_points().
query_op (str) – Query operator (and, or, xor). Defaults to “and”.
unit (str) – Unit values from projpicker.db. Defaults to “any”.
proj_table (str) – Proj table values from projpicker.db. Defaults to “any”.
projpicker_db (str) – projpicker.db path. Defaults to None.

Returns

List of queried BBox instances sorted by area.

Return type

list

Raises

ValueError – If query_op is not one of “and”, “or”, or “xor”.

projpicker.query_points_using_bbox(prevbbox, points, query_op='and', unit='any', proj_table='any')¶

Return a subset list of input BBox instances in unit in proj_table that completely contain input point geometres. Each BBox instance is a named tuple with all the columns from the bbox table in projpicker.db. This function is used to perform an intersection operation on BBox instances consecutively.

Parameters

prevbbox (list) – List of BBox instances from a previous query.
points (list) – List of parsable point geometries. See parse_points().
query_op (str) – Query operator (and, or, xor). Defaults to “and”.
unit (str) – Unit values from projpicker.db. Defaults to “any”.
proj_table (str) – Proj table values from projpicker.db. Defaults to “any”.

Returns

List of queried BBox instances sorted by area.

Return type

list

Raises

ValueError – If query_op is not one of “and”, “or”, or “xor”.

projpicker.query_poly(poly, unit='any', proj_table='any', projpicker_db=None)¶

Return a list of BBox instances in unit in proj_table that completely contain an input poly geometry. Each BBox instance is a named tuple with all the columns from the bbox table in projpicker.db. Results are sorted by area from the smallest to largest. If projpicker_db is None (default), get_projpicker_db() is used.

Parameters

poly (list) – List of parsable point geometries. See parse_poly().
unit (str) – Unit values from projpicker.db. Defaults to “any”.
proj_table (str) – Proj table values from projpicker.db. Defaults to “any”.
projpicker_db (str) – projpicker.db path. Defaults to None.

Returns

List of queried BBox instances sorted by area.

Return type

list

projpicker.query_poly_using_bbox(prevbbox, poly, unit='any', proj_table='any')¶

Return a subset list of input BBox instances in unit in proj_table that completely contain an input poly geometres. Each BBox instance is a named tuple with all the columns from the bbox table in projpicker.db. This function is used to perform an intersection operation on BBox instances consecutively.

Parameters

prevbbox (list) – List of BBox instances from a previous query.
poly (list) – List of parsable point geometries. See parse_poly().
unit (str) – Unit values from projpicker.db. Defaults to “any”.
proj_table (str) – Proj table values from projpicker.db. Defaults to “any”.

Returns

List of queried BBox instances sorted by area.

Return type

list

projpicker.query_polys(polys, query_op='and', unit='any', proj_table='any', projpicker_db=None)¶

Return a list of BBox instances in unit in proj_table that completely contain input poly geometries. Each BBox instance is a named tuple with all the columns from the bbox table in projpicker.db. The “and” query operator performs the intersection of bbox rows while the “or” operator the union and the “xor” operator the exclusive OR. Results are sorted by area from the smallest to largest. If projpicker_db is None (default), get_projpicker_db() is used.

Parameters

polys (list) – List of parsable poly geometries. See parse_polys().
query_op (str) – Query operator (and, or, xor). Defaults to “and”.
unit (str) – Unit values from projpicker.db. Defaults to “any”.
proj_table (str) – Proj table values from projpicker.db. Defaults to “any”.
projpicker_db (str) – projpicker.db path. Defaults to None.

Returns

List of queried BBox instances sorted by area.

Return type

list

projpicker.query_polys_using_bbox(prevbbox, polys, query_op='and', unit='any', proj_table='any')¶

Return a subset list of input BBox instances in unit in proj_table that completely contain input poly geometres. Each BBox instance is a named tuple with all the columns from the bbox table in projpicker.db. This function is used to perform an intersection operation on BBox instances consecutively.

Parameters

prevbbox (list) – List of BBox instances from a previous query.
polys (list) – List of parsable poly geometries. See parse_polys().
query_op (str) – Query operator (and, or, xor). Defaults to “and”.
unit (str) – Unit values from projpicker.db. Defaults to “any”.
proj_table (str) – Proj table values from projpicker.db. Defaults to “any”.

Returns

List of queried BBox instances sorted by area.

Return type

list

projpicker.read_bbox_db(bbox_db, unit='any', proj_table='any')¶

Return a list of all BBox instances in unit in proj_table in a bbox database. Each BBox instance is a named tuple with all the columns from the bbox table in projpicker.db. Results are sorted by area.

Parameters

bbox_db (str) – Path for the input bbox database.
unit (str) – Unit values from the input bbox database. Defaults to “any”.
proj_table (str) – Proj table values from the input bbox database. Defaults to “any”.

Returns

List of all BBox instances sorted by area.

Return type

list

projpicker.read_file(infile='-')¶

Read a file (stdin by default) and return a list of str lines.

Parameters: infile (str) – Input filename. Defaults to “-” for stdin.
Returns: List of str lines read from infile.
Return type: list
Raises: FileNotFoundError – If infile does not exist.

projpicker.search_bbox(bbox, text, ignore_case=True, search_op='and')¶

Search a list of BBox instances for text in any string fields. Text can be a CRS ID in crs_auth_name:crs_code.

Parameters

bbox (list) – List of BBox instances.
text (list or str) – List of strings or a string to search for.
ignore_case (bool) – Whether or not to ignore case. Defaults to True.
search_op (str) – Search operator (and, or). Defaults to “and”.

Returns

List of BBox instances any of whose string field values contain text.

Return type

list

projpicker.set_coordinate_system(coor_sys='latlon')¶

Set the coordinate system to either latitude-longitude or x-y by globally exposing coordinate-system-specific functions from the corresponding module.

Parameters: coor_sys (str) – Coordinate system (latlon, xy). Defaults to “latlon”.
Raises: ValueError – If coor_sys is not one of “latlon” or “xy”.

projpicker.set_latlon()¶: Set the coordinate system to latitude-longitude by calling set_coordinate_system().

projpicker.set_xy()¶: Set the coordinate system to x-y by calling set_coordinate_system().

projpicker.sort_bbox(bbox)¶

Sort a list of BBox instances by area_sqkm in place after deduplicating data.

Parameters: bbox (list) – List of BBox instances.

projpicker.start(geoms=None, infile='-', outfile='-', fmt='plain', no_header=False, separator=None, max_bbox=0, print_geoms=False, overwrite=False, append=False, start_gui=None, single=False, projpicker_db=None, proj_db=None, create=False)¶

Process options and perform requested tasks. This is the main API function. If geometries and an input file are specified at the same time, both sources are used except when the default stdin input file is specified and the function is run from a termal. In the latter case, only geometries are used and stdin is ignored. The first non-empty element in geoms can optionally be “and” or “or” to set the query operator. The “and” query operator performs the set-theoretic intersection of bbox rows while the “or” operator the union. Geometry types can be specified using words “point” for points (default), “poly” for polylines and polygons, and “bbox” for bounding boxes. Words “latlon” (default) and “xy” start the latitude-longitude and x-y coordinate systems, respectively. This function ignores the current coordinate system set by set_coordinate_system(), set_latlon(), or set_xy(), and always starts in the latitude-longitude coordinate system by default. The “plain”, “json”, “pretty”, “sqlite”, and “srid” formats are supported. No header and separator options only apply to the plain output format. The max_bbox option is used to limit the maximum number of returned BBox instances. Use 0 for all. The overwrite option applies to both projpicker.db and the output file, but the append option only appends to the output file. Only one of the overwrite or append options must be given. For selecting a subset of queried BBox instances, a GUI can be launched by setting gui to True. Results are sorted by area from the smallest to largest. The single argument is used to allow only one selection in the GUI. If projpicker_db or proj_db is None (default), get_projpicker_db() or get_proj_db() is used, respectively.

Parameters

geoms (list) – List of parsable geometries. Defaults to None.
infile (str) – Input geometry file. Defaults to “-” for sys.stdin.
outfile (str) – Output file. None for no output file. Defaults to “-” for sys.stdout.
fmt (str) – Output format (plain, json, pretty, sqlite, srid). Defaults to “plain”.
no_header (bool) – Whether or not to print header for plain. Defaults to False.
separator (str) – Column separator for plain and srid output formats. It supports special names including pipe (|), comma (,), space ( ), tab (t), and newline (n). Defaults to None, meaning “|” for plain and “n” for srid.
max_bbox (int) – Maximum number of returned BBox instances. Defaults to 0, meaning all.
print_geoms (bool) – Whether or not to print parsed geometries and exit. Defaults to False.
overwrite (bool) – Whether or not to overwrite output file. Defaults to False.
append (bool) – Whether or not to append output to file. Defaults to False.
start_gui (str) – “select” to start the GUI for selecting queried BBox instances. “gui” to ignore input geometries and start the GUI immediatenly. None to not start the GUI. Defaults to None.
single (bool) – Whether or not to allow only one selection in the GUI. Defaults to False.
projpicker_db (str) – projpicker.db path. Defaults to None.
proj_db (str) – proj.db path. Defaults to None.
create (bool) – Whether or not to create a new projpicker.db. Defaults to False.

Returns

List of queried BBox instances sorted by area.

Return type

list

Raises

ValueError – If format is invalid, both overwrite and append are True, output is None or “-” when append is True, or sqlite format is written to stdout.
FileExistsError – If either projpicker_db or outfile already exists when overwrite is False.
FileNotFoundError – If proj_db does not exist when create is True, projpicker_db does not exist when create is False.

projpicker.stringify_bbox(bbox, header=True, separator='|')¶

Convert a list of BBox instances to a str. If the input bbox list is empty, an empty string is returned.

Parameters

bbox (list or BBox) – List of BBox instances or a BBox instance.
header (bool) – Whether or not to print header. Defaults to True.
separator (str) – Column separator. Some CRS names contain commas. It supports special names including pipe (|), comma (,), space ( ), tab (t), and newline (n). Defaults to “|”.

Returns

Stringified bbox rows.

Return type

str

projpicker.tidy_lines(lines)¶

Tidy a list of str lines in place by removing leading and trailing whitespaces including newlines. Comments start with a hash and comment-only lines are deleted as if they did not even exist. A line starting with whitespaces immediately followed by a comment is considered a comment-only line and deleted. This function directly modifies the input list and does not return anything.

Parameters: lines (list) – List of str lines.

projpicker.transform_latlon_bbox(bbox, to_crs)¶

Transform a bbox defined by south, north, west, and east floats in decimal degrees in EPSG:4326 to the projected bbox in the to_crs CRS defined by bottom, top, left, and right floats in to_crs units. It requires the pyproj module. If, for any reason, the transformed bbox is not finite, a tuple of four Nones is returned.

Parameters

bbox (list) – List of south, north, west, and east floats in decimal degrees.
to_crs (str) – Target CRS.

Returns

Bottom, top, left, and right in to_crs units or all Nones on failed transformation.

Return type

float, float, float, float

projpicker.transform_latlon_point(point, to_crs)¶

Transform a point defined by latitude and longitude floats in decimal degrees in EPSG:4326 to the projected x and y floats in the to_crs CRS. It requires the pyproj module.

Parameters

point (list) – List of latitude and longitude floats in decimal degrees.
to_crs (str) – Target CRS.

Returns

x and y floats.

Return type

float, float

projpicker.transform_xy_point(point, from_crs)¶

Transform a point defined by x and y floats in the from_crs CRS to latitude and longitude floats in decimal degrees in EPSG:4326. It requires the pyproj module.

Parameters

point (list) – List of x and y floats.
from_crs (str) – Source CRS.

Returns

Latitude and longitude in decimal degrees.

Return type

float, float

projpicker.write_bbox_db(bbox, bbox_db, overwrite=False)¶

Write a list of BBox instances to a bbox database.

Parameters

bbox (list) – List of BBox instances.
bbox_db (str) – Path for output bbox_db.
overwrite (bool) – Whether or not to overwrite output file. Defaults to False.

Raises

FileExistsError – If bbox_db file already exists when overwriting is not requested.

common¶

This module provides common variables and functions for other ProjPicker modules.

class common.BBox(proj_table, crs_name, crs_auth_name, crs_code, usage_auth_name, usage_code, extent_auth_name, extent_code, south_lat, north_lat, west_lon, east_lon, bottom, top, left, right, unit, area_sqkm)¶

property area_sqkm¶: Alias for field number 17

property bottom¶: Alias for field number 12

property crs_auth_name¶: Alias for field number 2

property crs_code¶: Alias for field number 3

property crs_name¶: Alias for field number 1

property east_lon¶: Alias for field number 11

property extent_auth_name¶: Alias for field number 6

property extent_code¶: Alias for field number 7

property left¶: Alias for field number 14

property north_lat¶: Alias for field number 9

property proj_table¶: Alias for field number 0

property right¶: Alias for field number 15

property south_lat¶: Alias for field number 8

property top¶: Alias for field number 13

property unit¶: Alias for field number 16

property usage_auth_name¶: Alias for field number 4

property usage_code¶: Alias for field number 5

property west_lon¶: Alias for field number 10

common.get_float(x)¶

Typecast x into float; return None on failure.

Parameters: x (str or float) – Float in str or float.
Returns: Typecasted x in float if successful, None otherwise.
Return type: float or None

common.query_using_cursor(projpicker_cur, sql, unit='any', proj_table='any')¶

Return a list of BBox instances in unit in proj_table using a SQL statement.

Parameters

projpicker_cur (sqlite3.Cursor) – projpicker.db cursor.
sql (str) – SQL statement with optional AND_UNIT and AND_PROJ_TABLE.
unit (str) – Unit values from projpicker.db. Defaults to “any”.
proj_table (str) – Proj table values from projpicker.db. Defaults to “any”.

Returns

List of queried BBox instances sorted by area.

Return type

list

coor_latlon¶

This module provides parsing functions for the latitude-longitude coordinate system for the ProjPicker API.

coor_latlon.calc_poly_bbox(poly)¶

Calculate the bounding box of a poly geometry and return south, north, west, and east floats in decimal degrees.

Parameters: poly (list) – List of parsable point geometries. See parse_poly().
Returns: South, north, west, and east in decimal degrees.
Return type: float, float, float, float

coor_latlon.is_bbox_within_bbox(bbox1, bbox2)¶

Return True if bbox1 is within bbox2. Otherwise, return False.

Parameters

bbox1 (list) – List of south, north, west, and east floats in decimal degrees.
bbox2 (BBox) – BBox instance.

Returns

True if bbox1 is within bbox2. Otherwise, False.

Return type

bool

coor_latlon.is_point_within_bbox(point, bbox)¶

Return True if point is within bbox. Otherwise, return False.

Parameters

point (list) – List of latitude and longitude floats in decimal degrees.
bbox (BBox) – BBox instance.

Returns

True if point is within bbox. Otherwise, False.

Return type

bool

coor_latlon.parse_bbox(bbox)¶

Parse a str of south, north, west, and east, and return south, north, west, and east floats in decimal degrees. A list of four floats can be used in place of a str of south, north, west, and east. Any Any missing or invalid coordinate is returned as None. If an output from this function is passed, the same output is returned.

For example, “10,20,30,40” returns (10.0, 20.0, 30.0, 40.0).

Parameters: bbox (str) – Parsable str of south, north, west, and east.
Returns: South, north, west, and east in decimal degrees.
Return type: float, float, float, float

coor_latlon.parse_coor(m, ith, lat)¶

Parse the zero-based ith coordinate from a matched m. If the format is degrees, minutes, and seconds (DMS), lat is used to determine its negativity.

Parameters

m (re.Match) – re.compile() output.
ith (int) – Zero-based index for a coordinate group to parse from m.
lat (bool) – True if parsing latitude, False otherwise.

Returns

Parsed coordinate in decimal degrees.

Return type

float

coor_latlon.parse_lat(m, ith)¶

Parse the ith coordinate from a matched m as a latitude.

Parameters

m (re.Match) – re.compile() output.
ith (int) – Zero-based index for a coordinate group to parse from m as latitude.

Returns

Parsed coordinate in decimal degrees.

Return type

float

coor_latlon.parse_lon(m, ith)¶

Parse the ith coordinate from a matched m as a longitude.

Parameters

m (re.Match) – re.compile() output.
ith (int) – Zero-based index for a coordinate group to parse from m as longitude.

Returns

Parsed coordinate in decimal degrees.

Return type

float

coor_latlon.parse_point(point)¶

Parse a str of latitude and longitude. Return latitude and longitude floats in decimal degrees. A list of two floats can be used in place of a str of latitude and longitude. Any missing or invalid coordinate is returned as None. If an output from this function is passed, the same output is returned.

For example, “10,20” returns (10.0, 20.0).

Parameters: point (str) – Parsable str of latitude and longitude.
Returns: Parsed latitude and longitude in decimal degrees.
Return type: float, float

coor_latlon.query_bbox_using_cursor(projpicker_cur, bbox, unit='any', proj_table='any', negate=False)¶

Return a list of BBox instances in unit in proj_table that completely contain an input bbox geometry defined by sout, north, west, and east using a database cursor. Use the negate argument to return non-containing BBox instances. Each BBox instance is a named tuple with all the columns from the bbox table in projpicker.db. This function is used to perform a union operation on bbox rows consecutively. Results are sorted by area from the smallest to largest.

Parameters

projpicker_cur (sqlite3.Cursor) – projpicker.db cursor.
bbox (list or str) – List of south, north, west, and east floats in decimal degrees or parsable str of south, north, west, and east. See parse_bbox().
unit (str) – Unit values from projpicker.db. Defaults to “any”.
proj_table (str) – Proj table values from projpicker.db. Defaults to “any”.
negate (bool) – Whether or not to negate query. Defaults to False.

Returns

List of queried BBox instances sorted by area.

Return type

list

coor_latlon.query_point_using_cursor(projpicker_cur, point, unit='any', proj_table='any', negate=False)¶

Return a list of BBox instances in unit in proj_table that completely contain an input point geometry defined by latitude and longitude in decimal degrees. Use the negate argument to return non-containing BBox instances. Each BBox instance is a named tuple with all the columns from the bbox table in projpicker.db. This function is used to perform a union operation on BBox instances consecutively. Results are sorted by area from the smallest to largest.

Parameters

projpicker_cur (sqlite3.Cursor) – projpicker.db cursor.
point (list or str) – List of latitude and longitude floats in decimal degrees or parsable str of latitude and longitude. See parse_point().
unit (str) – Unit values from projpicker.db. Defaults to “any”.
proj_table (str) – Proj table values from projpicker.db. Defaults to “any”.
negate (bool) – Whether or not to negate query. Defaults to False.

Returns

List of queried BBox instances sorted by area.

Return type

list

coor_xy¶

This module provides parsing functions for the x-y coordinate system for the ProjPicker API.

coor_xy.calc_poly_bbox(poly)¶

Calculate the bounding box of a poly geometry and return bottom, top, left, and right floats.

Parameters: poly (list) – List of parsable point geometries. See parse_poly().
Returns: Bottom, top, left, and right.
Return type: float, float, float, float

coor_xy.is_bbox_within_bbox(bbox1, bbox2)¶

Return True if bbox1 is within bbox2. Otherwise, return False.

Parameters

bbox1 (list) – List of bottom, top, left, and right floats.
bbox2 (BBox) – BBox instance.

Returns

True if bbox1 is within bbox2. Otherwise, False.

Return type

bool

coor_xy.is_point_within_bbox(point, bbox)¶

Return True if point is within bbox. Otherwise, return False.

Parameters

point (list) – List of x and y floats.
bbox (BBox) – BBox instance.

Returns

True if point is within bbox. Otherwise, False.

Return type

bool

coor_xy.parse_bbox(bbox)¶

Parse a str of bottom, top, left, and right, and return bottom, top, left, and right floats. A list of four floats can be used in place of a str of left, right, bottom, and top. Any Any missing or invalid coordinate is returned as None. If an output from this function is passed, the same output is returned.

For example, “10,20,30,40” returns (10.0, 20.0, 30.0, 40.0).

Parameters: bbox (str) – Parsable str of bottom, top, left, and right.
Returns: Bottom, top, left, and right floats.
Return type: float, float, float, float

coor_xy.parse_point(point)¶

Parse a str of x and y. Return x and y floats. A list of two floats can be used in place of a str of x and y. Any missing or invalid coordinate is returned as None. If an output from this function is passed, the same output is returned.

For example, “10,20” returns (10.0, 20.0).

Parameters: point (str) – Parsable str of x and y.
Returns: Parsed x and y floats.
Return type: float, float

coor_xy.query_bbox_using_cursor(projpicker_cur, bbox, unit='any', proj_table='any', negate=False)¶

Return a list of BBox instances in unit in proj_table that completely contain an input bbox geometry defined by bottom, top, left, and right floats using a database cursor. Use the negate argument to return non-containing BBox instances. Each BBox instance is a named tuple with all the columns from the bbox table in projpicker.db. This function is used to perform a union operation on bbox rows consecutively. Results are sorted by area from the smallest to largest.

Parameters

projpicker_cur (sqlite3.Cursor) – projpicker.db cursor.
bbox (list or str) – List of bottom, top, left, and right floats or parsable str of bottom, top, left, and right. See parse_bbox().
unit (str) – “any”, unit values from projpicker.db.
proj_table (str) – Proj table values from projpicker.db. Defaults to “any”.
negate (bool) – Whether or not to negate query. Defaults to False.

Returns

List of queried BBox instances sorted by area.

Return type

list

coor_xy.query_point_using_cursor(projpicker_cur, point, unit='any', proj_table='any', negate=False)¶

Return a list of BBox instances in unit in proj_table that completely contain an input point geometry defined by x and y. Use the negate argument to return non-containing BBox instances. Each BBox instance is a named tuple with all the columns from the bbox table in projpicker.db. This function is used to perform a union operation on BBox instances consecutively. Results are sorted by area from the smallest to largest.

Parameters

projpicker_cur (sqlite3.Cursor) – projpicker.db cursor.
point (list or str) – List of x and y floats or parsable str of x and y. See parse_point().
unit (str) – “any”, unit values from projpicker.db.
proj_table (str) – Proj table values from projpicker.db. Defaults to “any”.
negate (bool) – Whether or not to negate query. Defaults to False.

Returns

List of queried BBox instances sorted by area.

Return type

list

gui¶

This module imports the gui_tk or gui_wx module.

gui_common¶

This module implements common functions for the gui modules.

gui_common.adjust_lon(prev_x, x, prev_lon, lon)¶

Adjust the current longitude (lon) at x in pixels relative to the previous one (prev_lon) at prev_x in pixels such that it becomes between lon - 360 and lon + 360. This function is used to draw geometries that cross the antimeridian.

Parameters

prev_x (int) – Previous x in pixels.
x (int) – Current x in pixels.
prev_lon (float) – Previous longitude in decimal degrees.
lon (float) – Current longitude in decimal degrees.

Returns

Adjusted longitude in decimal degrees.

Return type

float

gui_common.calc_geoms_bbox(geoms)¶

Calculate the union bbox in south, north, west, and east floats in decimal degrees that contains all the geometries in geoms.

Parameters: geoms (list) – List of parsed geometries.
Returns: South, north, west, and east in decimal degrees.
Return type: float, float, float, float

gui_common.create_crs_info(bbox, format_crs_info=None)¶

Create CRS info text optionally using format_crs_info().

Parameters

bbox (BBox) – BBox instance.
format_crs_info (function) – Function that takes a BBox instance and formats it to a string.

Returns

Formatted CRS info text.

Return type

str

gui_common.find_bbox(crs_id, bbox)¶

Find a BBox instance from a list of BBox instances that matches a CRS ID.

Parameters

crs_id (str) – CRS ID with the authority name and code delimited by a colon.
bbox (list) – List of BBox instances.

Returns

BBox instance whose CRS ID is crs_id.

Return type

BBox

gui_common.get_dzoom()¶

Get the delta zoom level from the PROJPICKER_DZOOM environment variable. If this environment variable is not available or not a number, return 1. The returned delta zoom level is always between -18 and 18.

Returns: Delta zoom level.
Return type: float

gui_common.get_latlon()¶

Get the initial latitude and longitude in decimal degrees from the PROJPICKER_COORDINATES environment variable. If this environment variable is not available, return 0 and 0.

Returns: Initial latitude and longitude in decimal degrees.
Return type: float, float

gui_common.get_zoom()¶

Get the initial zoom level from the PROJPICKER_ZOOM environment variable. If this environment variable is not available or not a number, return 0. If it is a float, it is rounded to the nearest even integer. The returned zoom level is always an integer between 0 and 18.

Returns: Initial zoom level.
Return type: int

gui_common.parse_geoms(geoms)¶

Parse geometries and create a query string.

Parameters: geoms (list or str) – Parsable geometries.
Returns: List of parsed geometries and query string.
Return type: list, str

gui_tk¶

This module implements the ProjPicker GUI using tkinter.

class gui_tk.AutoScrollbar(master, **kwargs)¶

Implement the auto-hiding scrollbar widget. https://stackoverflow.com/a/66338658/16079666

grid(**kwargs)¶

Override the grid() method.

Parameters: **kwargs (keyword arguments) – Keyword arguments for grid().

pack(**kwargs)¶

Override the pack() method.

Parameters: **kwargs (keyword arguments) – Keyword arguments for pack().

place(**kwargs)¶

Override the place() method.

Parameters: **kwargs (keyword arguments) – Keyword arguments for place().

set(first, last)¶

Override the set() method.

Parameters

first (float) – First slider position between 0 and 1.
last (float) – Last slider position between 0 and 1.

gui_tk.start(geoms=None, bbox=[], bbox_or_quit=False, single=False, format_crs_info=None, projpicker_db=None)¶

Start the GUI. Parsable geometries by geoms or queried BBox instances by bbox can be specified optionally. If both are given, bbox is ignored and only geoms is used. If single is True, it returns a single BBox instance in a list.

Parameters

geoms (list or str) – Parsable geometries. Defaults to None.
bbox (list) – Queried BBox instances. Defaults to [].
bbox_or_quit (bool) – Whether or not to quit when bbox queried using input geoms or input bbox is empty. Defaults to False.
single (bool) – Whether or not a single BBox instance is returned. Defaults to False.
format_crs_info (function) – User function used for formatting CRS info. Defaults to None in which case the default function is provided.
projpicker_db (str) – projpicker.db path. Defaults to None.

Returns

Lists of selected BBox instances, queried BBox instances sorted by area, and parsed geometries.

Return type

list, list, list

gui_wx¶

web¶

This module implements the standalone HTTP server, WSGI and CGI interfaces to the ProjPicker Web client, index.html.

class web.web.Color¶: Define color constants using ANSI color codes.

class web.web.HTTPRequestHandler(*args, **kwargs)¶

Implement the HTTP request handler for the standalone server.

do_POST()¶: Override the do_POST method of the base class, http.server.SimpleHTTPRequestHandler.

web.web.application(environ, start_response)¶

Implement the application function for the Web Server Gateway Interface (WSGI).

Parameters

environ (dict) – Dictionary of environment variables.
start_response (function) – Function to start a response.

Returns

List of bytes responses.

Return type

list

web.web.cgi()¶: Implement the Common Gateway Interface (CGI) of the web module.

web.web.main()¶: Implement the command-line interface to the standalone HTTP server.

web.web.print_color(color, *args)¶

Print colorized arguments.

Parameters

color (Color constant) – Color for arguments.
*args (arguments) – Arguments to print.

web.web.run_application(environ, reader, send_response, send_header, end_headers, write_data, flush_data, https=False)¶

Run the main application function for the standalone HTTP server and Common Gateway Interface (CGI).

Parameters

environ (dict) – Dictionary of environment variables.
reader (function) – Function to read data from the client. It should be able to read bytes data.
send_response (function) – Function to send the response to the client.
send_header (function) – Function to send headers to the client.
end_headers (function) – Function to stop sending headers to the client.
write_data (function) – Function to write data to the client. It should be able to write bytes data.
flush_data (function) – Function to top writing data to the client.
https (bool) – Whether or not the HTTP connection is secured. Defaults to False.

Raises

AssertionError – If writing data is attempted before a new response is triggered or headers are being sent more than once.
Exception – If exceptions are raised by the start_response() caller.

web.web.start(server='localhost:8000', start_client=False)¶

Start the standalone HTTP server for the ProjPicker Web client. It should be only used for localhost desktop uses because it uses the standard http.server module, which is not recommended for production because it only implements basic security checks (https://docs.python.org/3/library/http.server.html). This server does not go into the background and uses the PROJPICKER_VERBOSE environment variable to verbosely print debugging messages. Set it to YES to print requested queries, parsed geometries, and queried CRSs. Do not set it or set it to NO to avoid these extra messages.

Parameters

server (str) – Server address and port number joined by a colon. Defaults to localhost:8000.
start_client (bool) – Whether or not to start the client in the browser. Defaults to False.

Raises

Exception – If the server argument is not specified or the start fails
to start. –

web.web.verbose_args(*args)¶

Print arguments if verbose printing is requested.

Parameters: *args (arguments) – Arguments to print.

web.web.verbose_color(color, *args)¶

Print colorized arguments if verbose printing is requested.

Parameters

color (Color constant) – Color for arguments.
*args (arguments) – Arguments to print.

web.web.verbose_header(*args)¶

Print arguments in bold if verbose printing is requested.

Parameters: *args (arguments) – Arguments to print.

web.web.verbose_key_value(key, value)¶

Print a key-value pair if verbose printing is requested.

Parameters

key (str) – Key string.
value (any type) – Value object.

web.web.verbose_line()¶: Print a bold line that is 79 columns wide if verbose printing is requested.