====== Waypoint Calculator ======
**TODO - screenshots to take (remove this box before publishing)**
{{anchor:waypoint_calculator}}
{{ :en:calculator_overview.png?nolink&400 |}}
c:geo offers a calculator for waypoints, which allows to make use of variables and formulas to calculate coordinates based on the result.
Once you tapped on ''Calculate Coordinates'' in the [[coordinatedialog#waypoint_sources|coordinate input dialog]] the calculator will be shown.
The {{:ic_menu_cancel.svg?nolink&30|}} button will close the calculator without changes, the {{:ic_menu_done.svg?nolink&30|}} (or the ''Done'' button at the bottom, depending on your device) will close it, take over the changes and return to the waypoint editor.
Closing the calculator does not yet persist the calculator state. Be sure to also save the waypoint afterwards if you want to keep the state of the calculator.
You can use the calculator also for preparing your field trip by entering the needed formulas but not yet entering values for your variables.\\
This will of course not yet provide a valid result, but you can still save the current state at any time by closing the calculator and afterwards saving the waypoint. You can return later to enter the missing values as soon as you found them.
The calculator consists of the following sections (from top to bottom):
* **Coordinate input** - the latitude and longitude formulas, either in //Guided mode// or in //Plain mode//
* **Variables** - the variables used in the formulas and their values / formulas
* **Result** - the currently calculated coordinates
* **Notes** - free text notes
* **Buttons** - ''Convert to plain Coordinate'', ''Generate Waypoints'' and ''Done''
===== Guided and Plain mode =====
{{anchor:guided_and_plain_mode}}
{{ :en:calculator_guided_mode.png?nolink&400 |}}
The switch ''Guided Mode'' at the top selects how the coordinate formulas are entered:
* **Guided Mode** (default) - shows the coordinate as a grid with one button per digit. Use the drop down next to the switch to select the coordinate format (''DDD.DDDDD°'', ''%%DDD°MM.MMM'%%'' or ''%%DDD°MM'SS.SSS"%%'').
* **Plain Mode** - shows two free text fields for the latitude and longitude. This allows to take over coordinate formulas "as is" from a cache listing. See [[#using_plain_coordinate_format|Using Plain Coordinate Format]].
When switching between the modes c:geo tries to keep your input. If the formulas can't be represented in a guided format, the calculator stays in Plain mode.
===== Guided mode =====
{{anchor:guided_mode}}
By default the guided mode starts with the coordinates of the waypoint (or the cache) as a starting point. Each digit is represented by a button. The hemisphere buttons (N/S and E/W) can be tapped to toggle between the two values.
* __Tap__ a digit to select it. Below the grid a ''Value'' field appears in which you can enter a fixed digit, a variable (e.g. ''A'') or even a complete formula (e.g. ''A+B'') for this digit. Entering more than one digit as a value allows solutions where one variable results in several digits.
* __Long tap__ a digit to open the ''Select Variable'' dialog. It offers to:
* clear the digit (restore an empty value),
* use the next unused variable (shown as //(New)//), or
* use one of the already existing variables (shown together with their current value).
Digits to which a variable or formula is assigned are shown with a variable icon.
{{ :en:calculator_guided_variables.png?nolink&400 |}}
===== Variables =====
{{anchor:variables}}
{{ :en:calculator_variables.png?nolink&400 |}}
All variables used in the coordinate formulas are listed below the coordinate input. They are listed automatically as soon as they are used. The variables are shared with the ''Variables'' tab of the cache, so values entered here are also available there (and vice versa) and can be used by all waypoints of the cache.
For each variable you can enter either
* a **value** (e.g. ''5'' or a text), or
* a **formula** (e.g. ''A+B*2'') calculating the value from other variables.
The result of each variable is shown next to it. A formula button next to the input field lets you pick a function (see below) from a list.
Further buttons:
* ''Tidy Up'' - cleans up the variable list: it adds all variables missing for the current formulas, removes empty variables which nobody needs, adds empty entries for variables still missing and finally sorts all variables.
Variable names are **case sensitive**. ''A'' and ''a'' are different variables. Variables used in the coordinate formulas typically are single letters. Variables with longer names can be referenced with a leading ''$'' (e.g. ''$Name'' or ''${Name}'').
==== Formulas ====
{{anchor:formulas}}
{{ :en:calculator_functions.png?nolink&400 |}}
Formulas may use the following operators:
^ Operator ^ Function ^ Example ^
|+|Addition|A+B|
|-|Subtraction|A-B|
|*|Multiplication (also ''×'', ''•'', ''⋅'')|A*B|
|/|Division (also '':'' and ''÷'')|A/B|
|%|Modulo|A%10|
|%%^%%|Power (also ''²'' and ''³'')|A%%^%%B|
|!|Factorial|A!|
|( ) or [ ]|Parenthesis|(A+B)*C|
|<, >, <=, >=, ==, <>|Comparison (result is 1 for true, 0 for false)|A>B|
|' ' or " "|Text constant|'abc'|
|_|Marks an "overflow" digit (no value)|_5|
|#...#|Comment, ignored by the calculation|A+B #my note#|
Several variables or numbers directly written next to each other are //concatenated//: ''AB'' with A=1 and B=2 results in ''12''.
The following functions are available (several have alternative short names):
^ Group ^ Function ^ Description ^
|Simple Numeric|sqrt(x)|Square root|
| |sin(x), cos(x), tan(x)|Trigonometric functions (in degree)|
| |abs(x)|Absolute value|
| |round(x) / rd(x)|Round|
| |trunc(x) / tr(x) / floor(x) / fl(x)|Remove decimal places|
|Complex Numeric|if(cond; then; else)|Conditional|
| |checksum(x) / cs(x)|Sum of digits|
| |ichecksum(x) / ics(x)|Iterative sum of digits until one digit remains|
|Aggregate Numeric|add(...) / sum(...)|Sum of the given values or range, e.g. ''add(A-C)''|
| |multiply(...) / product(...) / prod(...)|Product|
| |min(...) / max(...)|Smallest / largest value|
| |count(...) / cnt(...)|Number of values|
| |average(...) / avg(...)|Average|
|Simple String|length(s) / len(s)|Number of characters|
| |substring(s;start;length) / substr / sub|Part of a text|
| |chars(s;from;to) / ch|Selected characters|
|Complex String|rot13(s)|Rotate characters by 13|
| |rot(s;n)|Rotate characters by n|
| |lettervalue(s) / lv / wordvalue / wv / bww|Sum of letter values (A=1, B=2, ...)|
| |roman(s)|Convert a roman number to decimal|
| |vanity(s) / vanitycode / vc|Phone keypad (vanity) code|
Function parameters are separated by '';''.
==== Ranges ====
{{anchor:ranges}}
Inside a formula a range can be given as ''[:0-9]'' or as a list ''[:0,2,7]'' (combinations like ''[:1-3,7]'' are possible). This is used by the ''Generate Waypoints'' function described below.
===== Result =====
{{anchor:result}}
{{ :en:calculator_result.png?nolink&400 |}}
While you enter formulas and variable values, the resulting latitude and longitude are shown on the fly in the result section below the variables.
Digits that can't be calculated yet (e.g. due to missing values) are replaced by ''*'' and greyed out. Once the result produces valid coordinates the result is shown with all white characters.
===== Calculator notes =====
{{anchor:calculator_notes}}
{{ :en:calculator_notes.png?nolink&400 |}}
The notes section at the end of the calculator can be used to enter or paste notes, which can be helpful to e.g. copy parts of the cache description containing the calculations required to find the cache.
The content of the calculator note will be synchronized to the note of the waypoint used to calculate.
===== Convert to plain Coordinate =====
{{anchor:convert_to_plain}}
{{ :en:calculator_convert_to_plain.png?nolink&400 |}}
''Convert to plain Coordinate'' replaces the calculation by the currently calculated, fixed coordinates and closes the calculator. The waypoint will no longer be a calculated waypoint.
If the formulas do not yet evaluate to valid coordinates you will be asked for confirmation, as converting will then reset the waypoint to empty coordinates.
===== Generate Waypoints =====
{{anchor:generate_waypoints}}
{{ :en:calculator_generate.png?nolink&400 |}}
If you do not know the exact value of one or several variables, but only a range of possible values, you can use ranges in the variables (e.g. ''[:0-9]'' or ''[:0,2,7]'') and tap ''Generate Waypoints''. c:geo will calculate all combinations, drop those which do not result in valid coordinates and show the rest in a list.
You can then select the coordinates which should be added as new waypoints (type //Generated//, name prefix "Generated") to your cache or show them on the map.
If no variable with a valid range is found or no combination results in valid coordinates, a corresponding message will be shown.
===== Using Plain Coordinate Format =====
{{anchor:using_plain_coordinate_format}}
{{ :en:calculator_plain.png?nolink&400 |}}
In //Plain// mode there are two free text fields to enter the latitude and longitude part of a coordinate.
A single digit or a group of digits can be replaced by a formula surrounded with parenthesis. The variables used in the formulas must consist of single letters (typically CAPITAL letters).
Often cache listings provide their waypoint coordinates already in this expected format. Therefore the plain mode is best suited when coordinates should be taken over "as is" from the listings.
Useful helpers in plain mode:
* ''Paste from clipboard'' - scans the clipboard for a coordinate (with or without formulas) and fills both fields. The button is only enabled if the clipboard contains a recognizable coordinate.
* ''Plain Tools'' (magic wand) - offers ''Remove spaces'' and ''%%Replace 'x' with '*'%%'' to fix typical problems of coordinates copied from listings.
The Plain mode works best with coordinates in [[coordformat|MinDeg format]] ''%%DDD° MM.MMM'%%''.
Taking an example like ''N 45° 5.(K)(I/N)(K+L+M+N)'', copy the latitude (N/S) part of the coordinate into the first input field and the longitude (E/W) part into the second. If the coordinate contains formulas with variables the corresponding variable input fields appear below. You can fill them in the same way as described in [[#variables|Variables]].
As soon as the input for all variable fields is complete the result turns white and shows the calculated coordinate.
In some cases the result stays grey because the coordinate parser could not interpret the initial coordinate input correctly, e.g. because of a misplaced SPACE character between two digits of the same group.
Typical problems with coordinates copied from listings are:
* Space between digits within a group ''N45° 5.(K) (I/N)(K+L+M+N)''
* Space before the degree sign ''N45 ° 5.(K)(I/N)(K+L+M+N)''
* Space before the decimal point ''N45° 5 .(K)(I/N)(K+L+M+N)''
* Space after the decimal point ''N45° 5. (K)(I/N)(K+L+M+N)''
* Wrong minus sign: There are many [[https://en.wikipedia.org/wiki/Dash|different dash signs]] - only the standard hyphen/minus sign (''-'') and a few common alternatives are accepted
* Wrong multiplication sign: sometimes an ''x'' is taken as multiplier sign instead of an asterisk (''*'') - use the ''Plain Tools'' to replace it
As with the guided mode, the state of the calculator can be saved at any time.
===== Migration of old calculator data =====
{{anchor:migration}}
{{ :en:calculator_migration.png?nolink&400 |}}
Waypoints calculated with the calculator of older c:geo versions are migrated to the new calculator. When you edit such a waypoint, c:geo shows a ''Waypoint Migration'' dialog explaining the suggested new formula and variables. You can
* ''Migrate'' - take over the suggested migration,
* ''Dismiss data'' - drop the old calculation data for good, or
* ''Cancel'' - continue without migration. You will be asked again the next time. Note that editing the waypoint coordinates might delete the local calculation data.
Migrated or dismissed data is documented in the user note of the waypoint.
===== Further information =====
{{anchor:further_information}}
The contributor of the original calculator code published some videos presenting different usage examples. Note that the appearance of the calculator has changed since then, but the principles remain the same:
{{youtube>eN2y5mvJul4?medium}}
{{youtube>NlW2BfF-tu0?medium}}
{{youtube>F-ZNAKbLCJ0?medium}}
{{youtube>6_BALG5192A?medium}}