caltopo_python module

This module provides one main class: CaltopoSession. Class methods are categorized and documented below.

Downstream code should create and use one instance of this class.

An exception class is also defined, CTSException, which could be thrown during initialization but is not documented here.

class CaltopoSession(domainAndPort: str = 'localhost:8080', mapID=None, configpath=None, account=None, id=None, key=None, accountId=None, accountIdInternet=None, sync=True, syncInterval=10, syncTimeout=10, syncDumpFile=None, cacheDumpFile=None, propertyUpdateCallback=None, geometryUpdateCallback=None, newFeatureCallback=None, deletedFeatureCallback=None, requestQueueChangedCallback=None, failedRequestCallback=None, disconnectedCallback=None, reconnectedCallback=None, mapClosedCallback=None, syncCallback=None, useFiddlerProxy=False, caseSensitiveComparisons=False, validatePoints='modify', blockingByDefault=True)

The core session object.

Parameters:

  • domainAndPort (str, optional) – Domain-and-port portion of the URL; defaults to ‘localhost:8080’; common values are ‘caltopo.com’ for the web interface, and ‘localhost:8080’ (or different hostname or port as needed) for CalTopo Desktop

  • mapID (str, optional) – 3-to-7-character map ID, or [NEW] optionally followed by new map specification (see .openMap documentation); omit this argument during initialization to create a ‘mapless’ session; defaults to None

  • configpath (str, optional) – Configuration file path (full file name); defaults to None

  • account (str, optional) – Account name; used to reference a section of the config file; defaults to None

  • id (str, optional) – 12-character credential ID; specify here to override value from config file; defaults to None

  • key (str, optional) – Credential key; specify here to override value from config file; defaults to None

  • accountId (str, optional) – 6-character account ID; specify here to override value from config file; defaults to None

  • accountIdInternet (str, optional) – 6-character internet-specific account ID; specify here to override value from config file; defaults to None

  • sync (bool, optional) – If True, the session will use multi-threaded background sync to keep the local cache in sync with the specified hosted map; defaults to True

  • syncInterval (int, optional) – Sync interval in seconds; defaults to 10

  • syncTimeout (int, optional) – Sync timeout in seconds; defaults to 10

  • syncDumpFile (str, optional) – Base filename (will be appended by timestamp) to dump the results of each sync call; defaults to None

  • cacheDumpFile (str, optional) – Base filename (will be appended by timestamp) to dump the local cache contents on each sync call; defaults to None

  • propertyUpdateCallback (function, optional) – Function to call when any feature’s property has changed during sync; the function will be called with the affected feature object as the only argument; defaults to None

  • geometryUpdateCallback (function, optional) – Function to call when any feature’s geometry has changed during sync; the function will be called with the affected feature object as the only argument; defaults to None

  • newFeatureCallback (function, optional) – Function to call when a new feature was added to the local cache during sync; the function will be called with the new feature object as the only argument; defaults to None

  • deletedFeatureCallback (function, optional) – Function to call when a feature was deleted from the local cache during sync; the function will be called with the deleted feature object and class as two separate arguments; defaults to None

  • requestQueueChangedCallback (function, optional) – Function to call when the non-blocking request queue changes; the function will be called with the updated request queue object (an instance of queue.Queue); defaults to None

  • failedRequestCallback (function, optional) – Function to call when a web request returns a response other than 200 / OK; the function will be called with the queued request (the current element of the request queue) and its response (an instance of requests.Response) as two separate arguments; defaults to None

  • disconnectedCallback (function, optional) – Function to call when a disconnect is detected, from an invalid response or a request timeout; the function is not called with any arguments; defaults to None

  • reconnectedCallback (function, optional) – Function to call when a resconnect is detected, from the first good response following a disconnect; the function is not called with any arguments; defaults to None

  • mapClosedCallback (function, optional) – Function to call when a map is closed; the function will optionally be called with a requests.Response object as the only argument; defaults to None

  • syncCallback (function, optional) – Function to call on each successful sync; the function is not called with any arguments; defaults to None

  • useFiddlerProxy (bool, optional) – If True, all requests for this session will be sent through the Fiddler proxy, which allows Fiddler to watch outgoing network traffic for debug purposes; defaults to False

  • caseSensitiveComparisons (bool, optional) – If True, various string comparisons will be done in a case-sensitive manner; see ._caseMatch; defaults to False

  • validatePoints (optional) – one of ‘modify’, ‘warn’, or False: should coordinates be checked or modified for correct longitude-then-latitide sequence as requests are sent; defaults to ‘modify’; setting to False disables calls to ._validatePoints from ._sendRequest

  • blockingByDefault (bool, optional) – If True, all requests are blocking unless specified otherwise in an argument to the individual request: the request takes place in the main thread, and main thread execution will stop until the response is available; if False, all requests are non-blocking unless specified otherwise in an argument to the individual request: the request takes place in a separate thread, and its response is handled by callbacks; the request is blocking within the request thread, but the main thread is not blocked. See the blocking / non-blocking documentation for more detail; defaults to True

CaltopoSession.openMap(mapID: str = '', newTitle: str = 'newMap', newTeamAccount: str = '', newFolderIDOrPath: str = '', newMode: str = 'cal', newSharing: str = 'SECRET') → bool

Open a map for usage in the current session. This is automatically called during session initialization (by _setupSession) if mapID was specified when the session was created, but can be called later from your code if the session was initially ‘mapless’.

If mapID is ‘[NEW]’, a new map will be created and opened for use in the current session. The remaining arguments are only relevant if mapID is ‘[NEW]’.

The new map’s ID will be stored in the session’s .mapID varaiable.

Parameters:

  • mapID (str, optional) – 3-to-7-character Map ID, or ‘[NEW]’ as above; defaults to ‘’

  • newTitle (str, optional) – title of newly created map; defaults to newMap

  • newTeamAccount (str, optional) – name of an existing team account that the user has access to; defaults to ‘’ in which case the map will be created in the user’s own account

  • newFolderIDOrPath (str, optional) – folder ID or path of newly created map; the path is a case-sensitive slash-delimited folder path, and must exactly match an existing folder; defaults to ‘’ in which case the map will be created in the root of the account

  • newMode (str, optional) – map mode of the newly created map; defaults to ‘cal’ for recreation mode; the only other allowed value is ‘sar’

  • newSharing (str, optional) – sharing mode of the the newly created map; defaults to ‘SECRET’; other allowed values are ‘PRIVATE’, ‘URL’, or ‘PUBLIC’; see CalTopo documentaiton for details

Returns:

True if map was opened successfully; False otherwise.

Return type:

bool

CaltopoSession.closeMap(badResponse=None)

Close an open map (stop syncing, clear the cache, etc.), but leave the mapless session open.

Parameters:

badResponse (requests.Response, optional) – optional requests.Response object to be passed to mapClosedCallback, which could be used to show the ‘reason’ for the map closure; defaults to None

Account data access methods

These methods may be called from either a mapless or a map-associated session.

CaltopoSession.getAccountData(callbacks=[]) → dict

Get all account data for the session account. Populates .accountData, .groupAccounts, and .personalAccounts.

Parameters:

callbacks (list, optional) – optional list of callback specifications; see the callbacks documentation

Returns:

value of .accountData

Return type:

dict

CaltopoSession.getMapList(groupAccountTitle: str = '', includeBookmarks=True, refresh=False, titlesOnly=False) → list

Get a list of all maps in the user’s personal account, or in the specified group account.

Parameters:

  • groupAccountTitle (str, optional) – Title of the group account to get the map list from; defaults to ‘’, in which case only the personal map list is returned

  • includeBookmarks (bool, optional) – If True, bookmarks will be included in the returned list; defaults to True

  • refresh (bool, optional) – If True, a refresh will be performed before getting the map list; defaults to False

  • titlesOnly (bool, optional) – If True, the return value will be a list of strings only; defaults to False

Returns:

List of dicts, chronologically sorted (most recent first) by the value of ‘updated’:

id -> 5-character map ID

title -> map title

updated -> timestamp of most recent update to the map

type -> ‘map’ or ‘bookmark’

if type is ‘bookmark’, another key permission will exist, with corresponding value

folderId -> folder ID, if the map is in an account-level folder or subfolder folderName -> folder name, or ‘<Top Level>’

Return type:

list

CaltopoSession.getAllMapLists(includePersonal=False, includeBookmarks=True, refresh=False, titlesOnly=False) → list

Get a structured list of maps from all group accounts of which the current user is a member. Optionally include the user’s personal account(s).

Parameters:

  • includePersonal (bool, optional) – If True, the user’s personal account(s) will be included in the return value; defaults to False

  • includeBookmarks (bool, optional) – If True, bookmarks will be included in the returned lists; defaults to True

  • refresh (bool, optional) – If True, a refresh will be performed before getting the map lists; defaults to False

  • titlesOnly (bool, optional) – If True, the return value will be a list of strings only; defaults to False

Returns:

list of dicts:

groupAccountTitle -> title of the group account

-OR-

personalAccountTitle -> title of the personal account

mapList -> list of maps for this group account, in the same format as the return value from .getMapList

Return type:

list

CaltopoSession.getMapTitle(mapID='', refresh=False) → str

Get the title of a map specified by mapID.

Parameters:

  • mapID (str, optional) – 5-character map ID; defaults to ‘’

  • refresh (bool, optional) – If True, a refresh will be performed before getting the map title; defaults to False

Returns:

Map title

Return type:

str

CaltopoSession.getAccountsAndFolders(refresh=False) → list

Get a list of all of the group accounts for which the current account is a member, and their subaccounts and folders (and subfolders).

A flat list of pathnames and folder IDs is also generated for each group account, which can be used to build a folder selection GUI.

Parameters:

refresh (bool, optional) – If True, a refresh will be performed before getting the folder data; defaults to False

Returns:

List of dictionaries representing the account’s group account and hierarrchical folder structure; rather than document the structure here, it’s best to try this method and look at the results

Return type:

list

CaltopoSession.getGroupAccountTitles(refresh=False) → list

Get the titles of all of the user’s group accounts.

Parameters:

refresh (bool, optional) – If True, a refresh will be performed before getting the account titles; defaults to False

Returns:

List of account titles

Return type:

list

Feature creation methods

In caltopo_python 1.0.0, most of these feature creation methods could be used to edit an existing feature, by specifying the existingId argument. .editFeature was a convenience method that called the appropriate .add… method with existingId specified.

In caltopo_python 2.0.0, the potentially-confusing existingId argument has been removed, and .editFeature now does all the work internally.

CaltopoSession.addFolder(label='New Folder', visible=True, labelVisible=True, returnJson='ID', timeout=0, dataQueue=False, callbacks=[], blocking=None)

Add a folder to the current map.

Parameters:

  • label (bool, optional) – Name of the folder; defaults to “New Folder”

  • visible – If True, the folder will be initially checked and expanded in the left bar, and new objects added to the folder will be visible.

  • labelVisible – If True, labels will be visible for objects in this folder.

  • returnJson (str, optional) – see ‘Returns’ section below; defaults to ‘ID’

  • timeout (int, optional) – Request timeout in seconds; if specified as 0 here, uses the value of .syncTimeout; defaults to 0

  • dataQueue (bool, optional) – If True, the folder creation will be endataQueued / deferred until a call to .flush; defaults to False

  • callbacks (list, optional) – optional list of callback specifications; see the callbacks documentation

  • blocking (bool or None, optional) – If True, the request is blocking: the request takes place in the main thread, and execution will stop until the response is available; if False, the request is non-blocking: the request takes place in a separate thread, and its response is handled by callbacks; if None, the value of .blockingByDefault is applied. See the blocking / non-blocking documentation for more detail; defaults to None

Returns:

various, depending on request details:

  • False for any error or failure, whether queued or blocking

  • True for a non-blocking request successfully submitted to the queue

  • for blocking requests:

  • Entire response json structure (dict) if returnJson is ‘ALL’

  • ID only, if returnJson is ‘ID’

CaltopoSession.addMarker(lat: float, lon: float, title='New Marker', description='', color='#FF0000', symbol='point', rotation=None, folderId=None, size=1, returnJson='ID', timeout=0, dataQueue=False, callbacks=[], blocking=None)

Add a marker to the current map.

Parameters:

  • lat (float) – Latitude of the marker, in decimal degrees; positive values indicate the northern hemisphere

  • lon (float) – Longitude of the marker, in decimal degrees; negative values indicate the western hemisphere

  • title (str, optional) – Title of the marker; defaults to ‘New Marker’

  • description (str, optional) – Marker description; defaults to ‘’

  • color (str, optional) – Marker color, in RGB #FFFFFF hex notation; defaults to ‘#FF0000’

  • symbol (str, optional) – Marker symbol name; must be one of the known symbol names; defaults to ‘point’

  • rotation (int, optional) – Marker rotation; not valid for all marker styles; defaults to None

  • folderId (str, optional) – Folder ID of the folder this marker should be created in, if any; defaults to None

  • size (int, optional) – Marker size; defaults to 1

  • returnJson (str, optional) – see ‘Returns’ section below; defaults to ‘ID’

  • timeout (int, optional) – Request timeout in seconds; if specified as 0 here, uses the value of .syncTimeout; defaults to 0

  • dataQueue (bool, optional) – If True, the marker creation will be endataQueued / deferred until a call to .flush; defaults to False

  • callbacks (list, optional) – optional list of callback specifications; see the callbacks documentation

  • blocking (bool or None, optional) – If True, the request is blocking: the request takes place in the main thread, and execution will stop until the response is available; if False, the request is non-blocking: the request takes place in a separate thread, and its response is handled by callbacks; if None, the value of .blockingByDefault is applied. See the blocking / non-blocking documentation for more detail; defaults to None

Returns:

various, depending on request details:

  • False for any error or failure, whether queued or blocking

  • True for a non-blocking request successfully submitted to the queue

  • for blocking requests:

  • Entire response json structure (dict) if returnJson is ‘ALL’

  • ID only, if returnJson is ‘ID’

CaltopoSession.addLine(points: list, title='New Line', description='', width=2, opacity=1, color='#FF0000', pattern='solid', folderId=None, returnJson='ID', timeout=0, dataQueue=False, callbacks=[], blocking=None)

Add a line to the current map.

(See .addLineAssignment to add an assignment feature instead.)

Parameters:

  • points (list) – List of points; each point is a list: [lon,lat]

  • title (str, optional) – Title of the line; defaults to ‘New Line’

  • description (str, optional) – Line description; defaults to ‘’

  • width (int, optional) – Line width in pixels; defaults to 2

  • opacity (float, optional) – Line opacity, ranging from 0 to 1; defaults to 1

  • color (str, optional) – Line color, in RGB #FFFFFF hex notation; defaults to ‘#FF0000’

  • pattern (str, optional) – Line dash pattern; must be from the known list of pattern names; defaults to ‘solid’

  • folderId (str, optional) – Folder ID of the folder this line should be created in, if any; defaults to None

  • returnJson (str, optional) – see ‘Returns’ section below; defaults to ‘ID’

  • timeout (int, optional) – Request timeout in seconds; if specified as 0 here, uses the value of .syncTimeout; defaults to 0

  • dataQueue (bool, optional) – If True, the line creation will be endataQueued / deferred until a call to .flush; defaults to False

  • callbacks (list, optional) – optional list of callback specifications; see the callbacks documentation

  • blocking (bool or None, optional) – If True, the request is blocking: the request takes place in the main thread, and execution will stop until the response is available; if False, the request is non-blocking: the request takes place in a separate thread, and its response is handled by callbacks; if None, the value of .blockingByDefault is applied. See the blocking / non-blocking documentation for more detail; defaults to None

Returns:

various, depending on request details:

  • False for any error or failure, whether queued or blocking

  • True for a non-blocking request successfully submitted to the queue

  • for blocking requests:

  • Entire response json structure (dict) if returnJson is ‘ALL’

  • ID only, if returnJson is ‘ID’

CaltopoSession.addPolygon(points: list, title='New Shape', folderId=None, description='', strokeOpacity=1, strokeWidth=2, fillOpacity=0.1, stroke='#FF0000', fill='#FF0000', returnJson='ID', timeout=0, dataQueue=False, callbacks=[], blocking=None)

Add a polygon to the current map.

(See .addAreaAssignment to add an assignment feature instead.)

Parameters:

  • points (list) –

    List of points; each point is a list: [lon,lat]

    • The final point does not need to be the same as the first point; the polygon will be automatically closed

  • title (str, optional) – Title of the polygon; defaults to ‘New Shape’

  • folderId (str, optional) – Folder ID of the folder this line should be created in, if any; defaults to None

  • description (str, optional) – Polygon description; defaults to ‘’

  • strokeOpacity (float, optional) – Opacity of the boundary line, ranging from 0 to 1; defaults to 1

  • strokeWidth (int, optional) – Width of the boundary line in pixels; defaults to 2

  • fillOpacity (float, optional) – Opacity of the polygon fill, ranging from 0 to 1; defaults to 0.1

  • stroke (str, optional) – Color of the boundary line, in RGB #FFFFFF hex format; defaults to ‘#FF0000’

  • fill (str, optional) – Color of the polygon fill, in RGB #FFFFFF hex format; defaults to ‘#FF0000’

  • returnJson (str, optional) – see ‘Returns’ section below; defaults to ‘ID’

  • timeout (int, optional) – Request timeout in seconds; if specified as 0 here, uses the value of .syncTimeout; defaults to 0

  • dataQueue (bool, optional) – If True, the polygon creation will be endataQueued / deferred until a call to .flush; defaults to False

  • callbacks (list, optional) – optional list of callback specifications; see the callbacks documentation

  • blocking (bool or None, optional) – If True, the request is blocking: the request takes place in the main thread, and execution will stop until the response is available; if False, the request is non-blocking: the request takes place in a separate thread, and its response is handled by callbacks; if None, the value of .blockingByDefault is applied. See the blocking / non-blocking documentation for more detail; defaults to None

Returns:

various, depending on request details:

  • False for any error or failure, whether queued or blocking

  • True for a non-blocking request successfully submitted to the queue

  • for blocking requests:

  • Entire response json structure (dict) if returnJson is ‘ALL’

  • ID only, if returnJson is ‘ID’

CaltopoSession.addOperationalPeriod(title='New OP', color='#FF0000', strokeOpacity=1, strokeWidth=2, fillOpacity=0.1, returnJson='ID', timeout=0, dataQueue=False, callbacks=[], blocking=None)

Add an Operational Period to the current map.

(This is a SAR-specific feature and has no meaning in ‘Recreation’ mode.)

Parameters:

  • title (str, optional) – Title of the operational period; defaults to ‘New OP’

  • color (str, optional) – Color of the fill and lines for assignments in this operational period, in RGB #FFFFFF hex format; defaults to ‘#FF0000’

  • strokeOpacity (float, optional) – Opacity of boundary lines of assignments in this operational period, ranging from 0 to 1; defaults to 1

  • strokeWidth (int, optional) – Width of boundary lines of assignments in this operational period, in pixels; defaults to 2

  • fillOpacity (float, optional) – Opacity of polygon fill of assignments in this operational period, ranging from 0 to 1; defaults to 0.1

  • returnJson (str, optional) – see ‘Returns’ section below; defaults to ‘ID’

  • timeout (int, optional) – Request timeout in seconds; if specified as 0 here, uses the value of .syncTimeout; defaults to 0

  • dataQueue (bool, optional) – If True, the operational period creation will be endataQueued / deferred until a call to .flush; defaults to False

  • callbacks (list, optional) – optional list of callback specifications; see the callbacks documentation

  • blocking (bool or None, optional) – If True, the request is blocking: the request takes place in the main thread, and execution will stop until the response is available; if False, the request is non-blocking: the request takes place in a separate thread, and its response is handled by callbacks; if None, the value of .blockingByDefault is applied. See the blocking / non-blocking documentation for more detail; defaults to None

Returns:

various, depending on request details:

  • False for any error or failure, whether queued or blocking

  • True for a non-blocking request successfully submitted to the queue

  • for blocking requests:

  • Entire response json structure (dict) if returnJson is ‘ALL’

  • ID only, if returnJson is ‘ID’

CaltopoSession.addAssignment(points: list, geomType=None, number=None, letter=None, title=None, opId=None, folderId=None, resourceType='GROUND', teamSize=0, priority='LOW', responsivePOD='LOW', unresponsivePOD='LOW', cluePOD='LOW', description='', previousEfforts='', transportation='', timeAllocated=0, primaryFrequency='', secondaryFrequency='', preparedBy='', status='DRAFT', returnJson='ID', timeout=0, dataQueue=False, callbacks=[], blocking=None)

Add a Line or Area Assignment to the current map.

(This is a SAR-specific feature and has no meaning in ‘Recreation’ mode.)

Parameters:

  • points (list) –

    List of points; each point is a list: [lon,lat]

    • For an Area assignment, the final point does not need to be the same as the first point; the polygon will be automatically closed

  • geomType (string) – ‘Line’ or ‘Area’; specified here for direct calls, or, passed from addLineAssignment or addAreaAssignment

  • number (str, optional) – String value to put in the ‘number’ field, if any; defaults to None

  • letter (str, optional) – String value to put in the ‘letter’ field, if any; defaults to None

  • opId (str, optional) – ID of the Operational Period feature that this assignment will belong to, if any; defaults to None

  • folderId (str, optional) – Folder ID of the folder this line assignment should be created in, if any; defaults to None

  • resourceType (str, optional) – Resource type; must be from the allowable list of resource types; defaults to ‘GROUND’

  • teamSize (int, optional) – Team size (number of people), defaults to 0

  • priority (str, optional) – Priority for the assignment; must be one of LOW, MEDIUM, or HIGH; defaults to ‘LOW’

  • responsivePOD (str, optional) – Expected POD for a responsive subject; must be one of LOW, MEDIUM, or HIGH; defaults to ‘LOW’

  • unresponsivePOD (str, optional) – Expected POD for an unresponsive subject; must be one of LOW, MEDIUM, or HIGH; defaults to ‘LOW’

  • cluePOD (str, optional) – Expected POD for clues; must be one of LOW, MEDIUM, or HIGH; defaults to ‘LOW’

  • description (str, optional) – Assignment description; defaults to ‘’

  • previousEfforts (str, optional) – Description of previous efforts in the assignment; defaults to ‘’

  • transportation (str, optional) – Description of how the team should transport to and from the assignment; defaults to ‘’

  • timeAllocated (str, optional) – Allotted time (typically a number of hours) to complete the assignment; can be a string or integer; defaults to 0

  • primaryFrequency (str, optional) – Primary radio frequency or channel name; defaults to ‘’

  • secondaryFrequency (str, optional) – Secondary radio frequency or channel name; defaults to ‘’

  • preparedBy (str, optional) – Name or ID of the person who prepared the assignment; defaults to ‘’

  • status (str, optional) – Overall status of the assignment; must be one of DRAFT, PREPARED, INPROGRESS, or COMPLETED; defaults to ‘DRAFT’

  • returnJson (str, optional) – see ‘Returns’ section below; defaults to ‘ID’

  • timeout (int, optional) – Request timeout in seconds; if specified as 0 here, uses the value of .syncTimeout; defaults to 0

  • dataQueue (bool, optional) – If True, the assignment creation will be endataQueued / deferred until a call to .flush; defaults to False

  • callbacks (list, optional) – optional list of callback specifications; see the callbacks documentation

  • blocking (bool or None, optional) – If True, the request is blocking: the request takes place in the main thread, and execution will stop until the response is available; if False, the request is non-blocking: the request takes place in a separate thread, and its response is handled by callbacks; if None, the value of .blockingByDefault is applied. See the blocking / non-blocking documentation for more detail; defaults to None

Returns:

various, depending on request details:

  • False for any error or failure, whether queued or blocking

  • True for a non-blocking request successfully submitted to the queue

  • for blocking requests:

  • Entire response json structure (dict) if returnJson is ‘ALL’

  • ID only, if returnJson is ‘ID’

CaltopoSession.addAreaAssignment(..., geomType='Area')

Convenience method that calls addAssignment with geomType=’Area’

CaltopoSession.addLineAssignment(..., geomType='Line')

Convenience method that calls addAssignment with geomType=’Line’

CaltopoSession.addLiveTrack(title='New LiveTrack', deviceId='', width=2, opacity=1, color='#FF0000', pattern='solid', folderId=None, returnJson='ID', timeout=0, dataQueue=False, callbacks=[], blocking=None)

Add a LiveTrack to the current map.

This method does not define any initial set of points for the LiveTrack. All updates must be done using .updateLiveTrack, or direct GET requests to the URL as noted in the CalTopo documentation.

Parameters:

  • title (str, optional) – Title of the line; defaults to ‘New Line’

  • deviceId (str) – string starting with ‘FLEET:’ followed by a hyphenated unique device identifier; see CalTopo documentation for details

  • width (int, optional) – Line width in pixels; defaults to 2

  • opacity (float, optional) – Line opacity, ranging from 0 to 1; defaults to 1

  • color (str, optional) – Line color, in RGB #FFFFFF hex notation; defaults to ‘#FF0000’

  • pattern (str, optional) – Line dash pattern; must be from the known list of pattern names; defaults to ‘solid’

  • folderId (str, optional) – Folder ID of the folder this line should be created in, if any; defaults to None

  • returnJson (str, optional) – see ‘Returns’ section below; defaults to ‘ID’

  • timeout (int, optional) – Request timeout in seconds; if specified as 0 here, uses the value of .syncTimeout; defaults to 0

  • dataQueue (bool, optional) – If True, the line creation will be endataQueued / deferred until a call to .flush; defaults to False

  • callbacks (list, optional) – optional list of callback specifications; see the callbacks documentation

  • blocking (bool or None, optional) – If True, the request is blocking: the request takes place in the main thread, and execution will stop until the response is available; if False, the request is non-blocking: the request takes place in a separate thread, and its response is handled by callbacks; if None, the value of .blockingByDefault is applied. See the blocking / non-blocking documentation for more detail; defaults to None

Returns:

various, depending on request details:

  • False for any error or failure, whether queued or blocking

  • True for a non-blocking request successfully submitted to the queue

  • for blocking requests:

  • Entire response json structure (dict) if returnJson is ‘ALL’

  • ID only, if returnJson is ‘ID’

CaltopoSession.flush(timeout=20)

Saves any dataQueued (deferred) request data to the hosted map.

Any of the feature creation methods can be called with dataQueue=True to dataQueue (defer) the creation until this method is called.

Parameters:

timeout (int, optional) – Maximum allowable duration for the save request, in seconds; defaults to 20

Feature query methods

CaltopoSession.getFeature(featureClass=None, title=None, id=None, featureClassExcludeList=[], letterOnly=False, allowMultiTitleMatch=False, timeout=0, forceRefresh=False)

Get the complete feature data structure for one feature from the local cache, after a refresh if needed.

This convenience function calls .getFeatures, but will only have a valid return if exactly one feature is a match.

All arguments are the same as for .getFeatures; see that method’s documentation.

Returns:

Data structure (dict) of the feature matching the requested filtering (if any), or False if zero or multiple features matched the fitler, or if there was an error prior to the cache search

CaltopoSession.getFeatures(featureClass=None, title=None, id=None, featureClassExcludeList=[], letterOnly=False, allowMultiTitleMatch=False, timeout=0, forceRefresh=False)

Get the complete feature data structure/s for one or more features from the local cache, after a refresh if needed.

The features to get data for can be specified / filtered in various methods:

  • all features of a given class

  • all features of any one of several classes (see featureClassExcludeList)

  • one feature with an exact ID

  • feature/s with specified title (can return mutliple features; see allowMultiTitleMatch)

  • assignment features specified by ‘letter’, regardless of ‘number’ (see letterOnly)

  • all features / the entire cache, if none of featureClass, ID, or title are specified

Parameters:

  • featureClass (str, optional) –

    Feature class name used for selection filtering; defaults to None

    • if neither ID nor title are specified, then all features of this class will be returned

    • if ID is not specified but title is specified, then feature/s of this class matching the title (possibly only the letter; see letterOnly) will be returned

  • title (str, optional) –

    Feature title used for selection filtering; defaults to None

    • title is only relevant if ID is not specified

    • only features whose class name matches featureClass (if specified) or whose class name is not in featureClassExcludeList are candidates for title matching; so, if neither featureClass nor featureClassExcludeList are specified, all features will be checked for title match

    • see allowMultiTitleMatch for handling of multiple features that have the specified title

  • id (str, optional) – Feature ID; if specified, only one feature will be returned, if there is a match; defaults to None

  • featureClassExcludeList (list, optional) – List of feature classes to exclude from possible matches; not relevant if featureClass or ID are specified; defaults to []

  • letterOnly (bool, optional) – If True, all assignments with matching ‘letter’ will be returned, regardless of ‘number’; defaults to False

  • allowMultiTitleMatch (bool, optional) –

    If True, and there are multiple features that have the specified title, they will all be returned; defaults to False

    If False, and there are multiple features that have the specified title, a warning will be displayed and the return will be an empty list

  • timeout (int, optional) – Request timeout in seconds; if specified as 0 here, uses the value of .syncTimeout; defaults to 0

  • forceRefresh (bool, optional) – If True, a refresh will be performed before getting the map list, even if the cache has been refreshed within the standard sync interval; defaults to False

Returns:

List of data structures (dicts) of feature/s matching the requested filtering; the list will be empty if there are no matches or if there was a failure prior to the cache request

Feature editing methods

CaltopoSession.editFeature(id=None, className=None, title=None, letter=None, folderId=None, properties={}, geometry={}, timeout=0, callbacks=[], blocking=None)

Edit properties and/or geometry of a specified feature.

The feature to edit can be specified in various methods:

  • exact ID

  • class name, with either the title or the letter

Only the specific properties or geometries to be edited need to be included in the properties and geometry arguments; they will be merged with existing properties and geometries. However, when editing geometry, it probably makes more sense to overwrite the entire geometry dictionary.

Parameters:

  • id (str, optional) – ID of the feature to edit; defaults to None

  • className (str, optional) – Feature class name used for selection; defaults to None

  • title (str, optional) – Feature title used for selection; defaults to None

  • letter (str, optional) –

    Assignment letter used for selection; defaults to None

    (only relevant for assignment features)

  • folderId (str, optional) – ID of the folder that the feature should be placed in; specifying this argument is the same as specifying properties[‘folderId’]; defaults to None

  • properties (dict, optional) – Dict of properties to edit; defaults to None

  • geometry (dict, optional) – Dict of geometry to edit; defaults to None

  • timeout (int, optional) – Request timeout in seconds; if specified as 0 here, uses the value of .syncTimeout; defaults to 0

  • callbacks (list, optional) – optional list of callback specifications; see the callbacks documentation

  • blocking (bool or None, optional) – If True, the request is blocking: the request takes place in the main thread, and execution will stop until the response is available; if False, the request is non-blocking: the request takes place in a separate thread, and its response is handled by callbacks; if None, the value of .blockingByDefault is applied. See the blocking / non-blocking documentation for more detail; defaults to None

Returns:

ID of the edited feature (should be the same as the ‘id’ argument), or False if there was a failure prior to the edit request

CaltopoSession.moveMarker(newCoords, id=None, title=None, callbacks=[], blocking=None)

Move an existing marker.

The marker to move can be specified either with ID or by title.

This convenience function calls .editFeature.

Parameters:

  • newCoords (list) – List of [lon,lat] that the marker should be moved to

  • id (str, optional) – ID of the marker to move; defaults to None

  • title (str, optional) – Title of the marker to move; defaults to None

  • callbacks (list, optional) – optional list of callback specifications; see the callbacks documentation

  • blocking (bool or None, optional) – If True, the request is blocking: the request takes place in the main thread, and execution will stop until the response is available; if False, the request is non-blocking: the request takes place in a separate thread, and its response is handled by callbacks; if None, the value of .blockingByDefault is applied. See the blocking / non-blocking documentation for more detail; defaults to None

Returns:

ID of the edited feature (should be the same as the ‘id’ argument, if specified), or False if there was a failure prior to the edit request

CaltopoSession.editMarkerDescription(newDescription, id=None, title=None, callbacks=[], blocking=None)

Edit the description of an existing marker.

The marker to edit can be specified either with ID or by title.

This convenience function calls .editFeature.

Parameters:

  • newDescription – The new description

  • id (str, optional) – ID of the marker to move; defaults to None

  • title (str, optional) – Title of the marker to move; defaults to None

  • callbacks (list, optional) – optional list of callback specifications; see the callbacks documentation

  • blocking (bool or None, optional) – If True, the request is blocking: the request takes place in the main thread, and execution will stop until the response is available; if False, the request is non-blocking: the request takes place in a separate thread, and its response is handled by callbacks; if None, the value of .blockingByDefault is applied. See the blocking / non-blocking documentation for more detail; defaults to None

Returns:

ID of the edited feature (should be the same as the ‘id’ argument, if specified), or False if there was a failure prior to the edit request

CaltopoSession.updateLiveTrack(id='', lat=None, lon=None, elevation=None)

Append one new location to an existing LiveTrack

Parameters:

  • id (str) – ID of the LiveTrack feature to be updated

  • lat (float) – Latitude of the new point, in WGS84 decimal degrees

  • lon (float) – Longitude of the new point, in WGS84 decimal degrees

  • elevation – Optional elevation of the new point, in feet; defaults to None

Returns:

requests.Response object from the .get request if successful; False for a failure of any reason

CaltopoSession.stopLiveTrack(id='')

Stop a LiveTrack recording; the server will automatically convert it to a Line with the same ID.

Parameters:

id (str) – ID of the LiveTrack

Feature deletion methods

CaltopoSession.delFeature(featureOrId='', fClass='', timeout=0, callbacks=[], blocking=None)

Delete the specified feature from the current map. The feature to delete can be specified by ID, or by passing the entire marker data object.

Parameters:

  • featureOrId (str, optional) – Feature ID, or entire feature data object; defaults to ‘’

  • fClass (str, optional) – Feature class; there should be no need to specify a value here, since the code will try to automatically determine the class from the feature data object; defaults to ‘’

  • timeout (int, optional) – Request timeout in seconds; if specified as 0 here, uses the value of .syncTimeout; defaults to 0

  • callbacks (list, optional) – optional list of callback specifications; see the callbacks documentation

  • blocking (bool or None, optional) – If True, the request is blocking: the request takes place in the main thread, and execution will stop until the response is available; if False, the request is non-blocking: the request takes place in a separate thread, and its response is handled by callbacks; if None, the value of .blockingByDefault is applied. See the blocking / non-blocking documentation for more detail; defaults to None

Returns:

Return value from the delete request, or False if there was an error prior to the request

CaltopoSession.delFeatures(featuresOrIdAndClassList=[], timeout=0)

Delete one or more features on the current map, in a non-blocking asynchronous batch of delete requests.

Parameters:

  • featuresOrIdAndClassList (list, optional) –

    List of dicts specifying the features to delete; each dict is either a complete feature data object, or this simplified dict; defaults to []

    • id -> the feature’s ID

    • class -> the feature’s class name

  • timeout (int, optional) – Request timeout in seconds; if specified as 0 here, uses the value of .syncTimeout; defaults to 0

Returns:

Return value of the asynchronous delete loop initialization routine, or False if there was an error prior to the loop

CaltopoSession.delMarker(markerOrId='', timeout=0, callbacks=[], blocking=None)

Delete a marker on the current map.

The marker to delete can be specified by ID, or by passing the entire marker data object.

This convenience function calls .delFeature.

Parameters:

  • markerOrId – Marker ID, or entire marker data object; defaults to ‘’

  • timeout (int, optional) – Request timeout in seconds; if specified as 0 here, uses the value of .syncTimeout; defaults to 0

  • callbacks (list, optional) – optional list of callback specifications; see the callbacks documentation

  • blocking (bool or None, optional) – If True, the request is blocking: the request takes place in the main thread, and execution will stop until the response is available; if False, the request is non-blocking: the request takes place in a separate thread, and its response is handled by callbacks; if None, the value of .blockingByDefault is applied. See the blocking / non-blocking documentation for more detail; defaults to None

Returns:

Return value from the delete request, or False if there was an error prior to the request

CaltopoSession.delMarkers(markersOrIds=[], timeout=0)

Delete one or more markers on the current map, in a non-blocking asynchronous batch of delete requests.

The markers to delete can be specified by ID, or by passing the entire marker data objects; all markers to delete should be specified in the same manner.

This convenience function calls .delFeatures.

Parameters:

  • markersOrIds (list, optional) – List of marker IDs, or of entire marker data objects; defaults to []

  • timeout (int, optional) – Request timeout in seconds; if specified as 0 here, uses the value of .syncTimeout; defaults to 0

Returns:

Return value from the delete request, or False if there was an error prior to the request

Geometry operation methods

These methods use the python Shapely module.

CaltopoSession.cut(target, cutter, deleteCutter=True, useResultNameSuffix=True)
Cut a ‘target’ geometry using a ‘cutter’ geometry:

  • remove a notch from a polygon target, using a polygon cutter

  • slice a polygon target, using a polygon cutter or a line cutter

  • slice a line target, using a polygon cutter or a line cutter

Parameters:

  • target – ID, title, or entire feature dict of the target feature

  • cutter – ID, title, or entire feature dict of the cutter feature

  • deleteCutter (bool, optional) – If True, delete the cutter feature after the cut operation; defaults to True

  • useResultNameSuffix (bool, optional) – If True, any new features resulting from the cut operation will have their titles suffixed; defaults to True

Returns:

List of resulting feature IDs, or False if a failure occured prior to the cut operation

CaltopoSession.expand(target, p2, deleteP2=True)

Expand a ‘target’ polygon to include the area of the ‘p2’ polygon.

This is basically a boolean ‘OR’ operation, using Shapely’s ‘|’ method.

Parameters:

  • target – ID, title, or entire feature dict of the target feature

  • p2 – ID, title, or entire feature dict of the p2 feature

  • deleteP2 (bool, optional) – If True, delete the p2 feature after the expand operation; defaults to True

Returns:

True if successful; False otherwise

CaltopoSession.crop(target, boundary, beyond=0.0001, deleteBoundary=False, useResultNameSuffix=False, drawSizedBoundary=False, noDraw=False)

Remove portions of a line or polygon that are outside a boundary polygon. Optionally grow the boundary polygon by the specified distance before cropping.

Parameters:

  • target – ID, title, or entire feature dict of the target feature

  • boundary – ID, title, or entire feature dict of the boundary polygon

  • beyond (float, optional) – Distance to oversize the boundary polygon (in degrees) prior to the crop operation; defaults to 0.0001

  • deleteBoundary (bool, optional) – If True, the boundary polygon will be deleted after the crop operation; defaults to False

  • useResultNameSuffix (bool, optional) – If True, any new features resulting from the cut operation will have their titles suffixed; defaults to False

  • drawSizedBoundary (bool, optional) – If True, the oversized boundary polygon will be drawn as a feature; defaults to False

  • noDraw (bool, optional) – If True return the resulting coordinate list(s) instead of editing / adding map features; defaults to False

Returns:

Resulting feature IDs, or resulting coordinate list(s) (see noDraw), or False if a failure occurred prior to the crop operation

CaltopoSession.getBounds(objectList: list, padDeg=0.0001, padPct=None)

Get the bounding box of a list of features, optionally oversized by padDeg or padPct.

Shapely.bounds is used to compute the extent of each feature.

Parameters:

  • objectList (list) – List of IDs, titles or entire feature dicts of the features in question

  • padDeg (float, optional) – Amount to expand the bounding box, in degrees; defaults to 0.0001; only relevant if padPct is not specified

  • padPct (float, optional) –

    Amount to expand the bounding box, in percent (integer), or as a fraction (from 0 to 1); defaults to None;

    If padPct is specified, it will be applied; if padPct is not specified, the padDeg value will be applied

Returns:

Bounding box of the features in question, optionally oversized as above; returned as a list, in the same format as shapely.bounds: [min X, min Y, max X, max Y]

Internal data management methods

These methods are typically only called internally, from other class methods. They can be called from downstream code if needed, with caution. Not all internal data management methods are documented.

CaltopoSession._setupSession() → bool

Called internally from __init__, regardless of whether this is a mapless session. Reads account information from the config file and takes care of various other setup tasks.

Returns:

True if setup was successful; False otherwise (which will raise CTSException from __init__).

Return type:

bool

CaltopoSession._sendUserdata(activeLayers=[['mbt', 1]], center=[-120, 39], zoom=13)

Send a POST request to /api/v0/userdata with initial map center and zoom; this might actually no longer be needed; only called during creation of a new map.

Parameters:

  • activeLayers (list, optional) – initial map layer setup, defaults to [[‘mbt’,1]]

  • center (list, optional) – initial map center location, defaults to [-120,39]

  • zoom (int, optional) – initial map zoom, defaults to 13

CaltopoSession._doSync(fromLoop=False)

Internal method to keep the cache (.mapData) in sync with the associated hosted map. Calling this method directly could cause sync problems.

  • called on a regular interval from ._syncLoop in the sync thread

  • called once from .openMap, when the map is first opened

  • called as needed from ._refresh

Parameters:

fromLoop (bool, optional) – A flag to indicate whether this is being called from ._syncLoop. If True, any exception during sync will be passed along to _syncLoop for handling, and will typically cause a disconnect. False would indicate that an immediate sync is being request from some other internal method. Defaults to False.

CaltopoSession._refresh(forceImmediate=False)

Refresh the cache (.mapData). This method should not need to be called when sync is on.

Parameters:

forceImmediate (bool, optional) – If True, the refresh will happen immediately, even if a refresh was already done within the timeout period; defaults to False

CaltopoSession.__del__()

Object destructor. Also stops the sync thread if needed.

CaltopoSession._start()

Internal method to start the sync thread.

Called from .openMap if sync is enabled. Calls ._syncLoop in a new thread. Calling this method directly could cause sync problems.

CaltopoSession._stop()

Internal method to stop the sync thread.

Called from __del__ (when the object is destroyed) if sync was enabled. Calling this method directly could cause sync problems.

CaltopoSession._pause()

Internal method to manually pause the sync thread.

Sync is normally paused at the start of every call to _sendRequest; this method can be used to pause at any other time if needed.

After calling this method, sync will remain paused until a call to ._resume.

CaltopoSession._resume()

Internal method to resume the sync thread, following a call to ._pause.

CaltopoSession._syncLoop()

Internal method that calls _doSync at regular intervals, in a blocking loop.

This should only be called from ._start, which calls this method in a new thread, to avoid blocking of the main thread. Calling this method directly could cause sync problems.

CaltopoSession._sendRequest(method: str, apiUrlEnd: str, j: dict, id: str = '', returnJson: str = '', timeout: int = 0, domainAndPort: str = '', accountId: str = '', blocking=None, callbacks=[])

Send an HTTP request to the server.

Parameters:

  • method (str) – HTTP request action verb; currently, must be one of ‘GET’, ‘POST’, or ‘DELETE’

  • apiUrlEnd (str) –

    Text of the ‘final section’ of the request URL

    • typical values are ‘Folder’, ‘Shape’, ‘Marker’, etc.

    • any occurrances of ‘[MAPID]’ in apiUrlEnd will be replaced by the current map ID

    • can be the keyword ‘[NEW]’ which indicates that a new map should be created

    • can be a longer URL with multiple tokens and slashes

  • j (dict) – JSON structure to send with the request; only relevant for POST requests

  • id (str, optional) – Feature ID, when relevant; defaults to ‘’

  • returnJson (str, optional) – see ‘Returns’ section below; defaults to ‘’

  • timeout (int, optional) – request timeout in seconds; if specified as 0 here, uses the value of .syncTimeout; defaults to 0

  • domainAndPort (str, optional) – Domain and port to send the request to; if not specified here, uses the value of .domainAndPort; defaults to ‘’

  • accountId (str, optional) – account ID if the request should be made in regards to a different team account that the user has access to, such as new map creation in a team account; defaults to ‘’

  • blocking (bool or None, optional) – If True, the request is blocking: the request takes place in the main thread, and execution will stop until the response is available; if False, the request is non-blocking: the request takes place in a separate thread, and its response is handled by callbacks; if None, the value of .blockingByDefault is applied. See the blocking / non-blocking documentation for more detail; defaults to None

  • callbacks (list, optional) – optional list of callback specifications; see the callbacks documentation

Returns:

various, depending on request details:

  • False for any error or failure, whether queued or blocking

  • True for a non-blocking request successfully submitted to the queue

  • for blocking requests:

  • Entire response json structure (dict) if returnJson is ‘ALL’

  • ID only, if returnJson is ‘ID’

  • map ID of newly created map, if apiUrlEnd contains ‘[NEW]’

CaltopoSession._requestWorker(event)

Intrnal requestThread worker method. Waits for an event, then processes all requests in requestQueue, then resumes waiting. Calling this method directly could cause sync problems or crashes.

Parameters:

event – The threading event that the worker waits for; the event is set when a non-blocking request is enqueued in _sendRequest, and is cleared here.

CaltopoSession._handleResponse(r, newMap=False, returnJson='', callbacks=[])

Internal method to handle HTTP request responses, for both blocking and non-blocking requests. Calling this method directly could cause sync problems or crashes.

Parameters:

  • r (requests.Response) – The response object.

  • newMap (bool, optional) – Flag to indicate whether this response came from a new map creation request; defaults to False.

  • returnJson (str, optional) – see ‘Returns’ section below; defaults to ‘’

  • callbacks (list, optional) – optional list of callback specifications; see the callbacks documentation

Returns:

various, depending on request details:

  • False for any error or failure, whether queued or blocking

  • for blocking requests:

  • Entire response json structure (dict) if returnJson is ‘ALL’

  • ID only, if returnJson is ‘ID’

  • map ID of newly created map, if apiUrlEnd contains ‘[NEW]’

CaltopoSession._addFeature(className, j, returnJson='ID', callbacks=[], timeout=0, dataQueue=False, blocking=None)

Internal method holding the core functionality shared by the other add… methods. Calling this method directly could cause sync problems.

Parameters:

  • className (str) – Class name of the feature to add.

  • j (dict) – json parameters of the feature to add.

  • returnJson (str, optional) – see ‘Returns’ section below; defaults to ‘ID’

  • callbacks (list, optional) – optional list of callback specifications; see the callbacks documentation

  • timeout (int, optional) – Request timeout in seconds; if specified as 0 here, uses the value of .syncTimeout; defaults to 0

  • dataQueue (bool, optional) – If True, the folder creation will be endataQueued / deferred until a call to .flush; defaults to False

  • blocking (bool or None, optional) – If True, the request is blocking: the request takes place in the main thread, and execution will stop until the response is available; if False, the request is non-blocking: the request takes place in a separate thread, and its response is handled by callbacks; if None, the value of .blockingByDefault is applied. See the blocking / non-blocking documentation for more detail; defaults to None

Returns:

various, depending on request details:

  • False for any error or failure, whether queued or blocking

  • True for a non-blocking request successfully submitted to the queue

  • for blocking requests:

  • Entire response json structure (dict) if returnJson is ‘ALL’

  • ID only, if returnJson is ‘ID’

async CaltopoSession._delAsync(idAndClassList: list = [], timeout: int = 0)

Internal method to delete several features asynchronously, in a sepearate thread pool. This method should not be called directly. It is called by .delFeatures.

Parameters:

  • idAndClassList (list, optional) –

    list of dicts of features to delete; defaults to []

    • id -> the feature’s ID

    • class -> the feature’s class name

  • timeout (int, optional) – request timeout in seconds; if specified as 0 here, uses the value of .syncTimeout; defaults to 0

CaltopoSession._buffer2(boundaryGeom, beyond: float)

Return a copy of the original polygon, increased in size by the specified value.

This method does not modify the original geometry.

This method is used to oversize a Polygon; Shapely’s LineString.buffer method should be used to oversize a line.

Parameters:

  • boundaryGeom (shapely.geometry.Polygon) – Boundary geometry to be oversized

  • beyond (float) – Amount to oversize the boundary geometry (in degrees)

Returns:

Oversized geometry (the orignal geometry is not modified)

Return type:

shapely.geometry.Polygon or .MultiPolygon

CaltopoSession._intersection2(targetGeom, boundaryGeom)

Return the intersection of the targetGeom (a LineString) and the boundaryGeom (a Polygon).

For other geometry types, shapely.ops.intersection should be used.

This function will preseve complex (non-simple) lines, i.e. with internal crossovers, by walking through the input points (except for the last point) where ‘A’ signifies the current point and ‘B’ signifies the next point:

  • if A and B are both inside the boundary: append A to the output points list

  • if A is inside but B is outside: append A, then append the intestection of the current segment with the boundary

  • if A is outside but B is inside: append B, then append the intersection of the current segment with the boundary

  • if A and B are both ouside: don’t append either point; instead, append the intersection as a new line segment

Parameters:

  • targetGeom (shapely.geometry.LineString) – Target geometry

  • boundaryGeom (shapely.geometry.Polygon) – Boundary geometry

Returns:

Result of the intersection operation; could be one of various shapely.geometry classes

Internal helper methods

These methods are typically only called internally, from other class methods. They can be called from downstream code if needed, with caution. Not all internal helper methods are documented.

CaltopoSession._caseMatch(a: str, b: str) → bool

Compare two input strings to see if they are equal, based on the value of .caseSensitiveComparisons.

Parameters:

  • a (str) – First string to compare.

  • b (str) – Second string to compare.

Returns:

If .caseSensitiveComparisons is True, ‘ABC’ will not match ‘Abc’, and the return value will be False.

If .caseSensitiveComparisons is False, ‘ABC’ will match ‘Abc’, and the return value will be True.

Regardless of the value of .caseSensitiveComparisons, ‘ABC’ will match ‘ABC’, and the return value will be True.

Return type:

bool

CaltopoSession._twoify(points: list) → list

Internal method to turn four-element-vertex-data into two-element-vertex-data for use by the shapely methods.

Parameters:

points (list) – List of points, or a single point

Returns:

List of two-coordinate versions of the input point/s

CaltopoSession._fourify(points: list, origPoints: list) → list

Internal method to make a list of four-element points from a list of possibly-two-element points, by comparison with an original list of four-element points.

Used internally to make sure geometry operation results are compliant with subsequent operations.

Parameters:

  • points (list) – List of possibly-two-element points to be copied into a list of four-element points

  • origPoints (list) – List of four-element points that can be used to inform the copy operation as needed

Returns:

List of four-element points

CaltopoSession._removeDuplicatePoints(points: list) → list

Walk a list of points; if a given point is very close to the previous point (within 0.00001 degrees), delete it.

Parameters:

points (list) – List of [lon,lat] points

Returns:

The possibly-modified list of points; will be the same length as the input list, or shorter

CaltopoSession._removeSpurs(points: list) → list

Walk a list of points; if the points before and after a given point are identical, delete the given point.

Parameters:

points (list) – List of [lon,lat] points

Returns:

The possibly-modified list of points; will be the same length as the input list, or shorter

CaltopoSession._getUsedSuffixList(base: str)

Get a list of integers of all used suffixes for the specified base title.

Parameters:

base (str) – Base title to check

Returns:

List of integers of all used suffxies, or False if there was a failure prior to checking the cache

CaltopoSession._getNextAvailableSuffix(usedSuffixList: list) → int

Get the next available suffix, give a list of used suffixes.

In case the used suffix list is not contiguous, e.g. if an intermediate suffixed feature has been deleted, the lowest available suffix number will be returned.

Parameters:

usedSuffixList (list) – List of integer suffixes that are already used; does not need to be contiguous

Returns:

Lowest available suffix number

Return type:

int

CaltopoSession._validatePoints(geom: list, modify: bool = False)

Internal method to find any points from the specified geometry that are ‘obviously’ lon-lat-swapped.

Normally only called from _sendRequest.

The ‘correct’ sequence for each point, as expected by caltopo.com, is [lon,lat] i.e longitude then latitude.

The specified geometry is a possibly-nested list:

  • a single point: [lon,lat]

  • a single list of points, a.k.a. a line: [[lon1,lat1],[lon2,lat2],[lon3,lat3]]

  • a list of lists of points, a.k.a. a polygon that could have multiple segments: [[[lonA1,latA1],[lonA2,latA2]], [[lonB1,latB1],[lonB2,latB2]], [[lonC1,latC1],[lonC2,latC2]]]

First, each point in each list of points is categorized:

  • ‘obviously swapped’ : abs(lat)>90

  • ‘obviously valid’ : 90<=abs(lon)<=180 and abs(lat)<=90

  • ‘ambiguous’ - neither of the above; note that half of the world is ‘ambiguous’ by this definition (west half of east hemisphere, and east half of west hemisphere: all points where longitude is between 90 and -90)

If modify is True:

  • if there are obviously-swapped points but no obviously-valid points: swap lon and lat of all points in the list

  • if there are both obviously-swapped and obviously-valid points: flag an error; return the unmodified geom if modify is False, or return False if modify is True which will probably cause the feature to not generate

  • otherwise: do not modify any points; note, this includes the case where there are obviously-valid points but no obviously-swapped points

Log messages will be generated as needed, regardless of the value of modify.

Parameters:

  • geom (list) – point, list of points, or list of lists of points

  • modify (bool) – True to modify the points list before returning if needed as above; False to always return the unmodified list; defaults to False

Returns:

A modified or unmodified copy of the geom argument value, based on modify

CaltopoSession._getToken(data: str) → str

Internal method to get the token needed for signed requests.

Normally only called from _sendRequest.

Parameters:

data (str) – Data to be signed

Returns:

Signed token

Return type:

str