Karto Files

README.TXT

Karto Version 2.0.22 (june 2021)
Geographic positioning software

0. Purpose of the Karto application
-------------------------

   at. Aim of Karto
   ---------------------
   Ever since its first version (year 2000), the aim of the Karto application has been to assist the management of topographic point files by automatically projecting them onto a calibrated map.
   The first users were speleologists from France (Alpes-Maritimes) who used it to control their database of inventoried caves (more than 3000 caves).
   Karto can however be used by any person or organisation with a need to check files of topographic points, or to generate maps by positioning specific elements. Karto can generate and control maps with complete independence and with very good security features, via importing procedures for point files which use very simple and standard formats (text file, Excel files, with a minimum of 5 columns).
   
   b. Aims of this new release
   --------------------------------------
   * Firstly: To make the program look "beautiful", with a good technical architecture, and with a well written and documented code, ...something that can be taken by other developers and which is of an excellent quality and without bugs (as much as possible), ...something that is very clean and not like the the programs full of bugs which can be found all too easily these days.
   * Secondly: To provide a truly free and open application as is emphasised by its GPL license; and which is in no way pecuniarily implicated or related to the pursuit of other monetary benefits; basically this is a true widely available application.
   * Thirdly: To create a useful application for all mankind, that is to say provide people with a data processing tool to service their needs and enable them to work and build their own creations which can be disseminated and shared for free, thereby incrasing the knowledge of humanity at large.

I. License
----------
GPL License v3.0
See doc / license_en.txt or https://www.gnu.org/licenses/gpl-3.0.html

II. Environment required:
--------------------------
* Java version 1.8 (minimum)
* Windows or Linux computer with 1 GB RAM (minimum)
* 100 MB of storage (minimum) for Karto, and its data. More storage will be required to manage "Big Data". Karto uses only a few MB to install, but the user data can potentially take up a lot of space, as will java (if it has not already been installed) which requires more than 150 MB of disk space.

III. Command line
----------------------

Syntax: karto.sh [--test | --ListFont | --invisible | --help | --aide ] [ -option <value> ]
  --test: Runs a series of automated unit tests. This function is only for developers who have installed a dev mode.
  --ListFont: Generates the ImageFontTxt.png image with all the fonts available on Karto. Image generated in the test / result folder or otherwise in the current directory.
  --invisible: Automatic Karto mode, without graphic interface, for the generation of pre-calibrated card reproduction
  --help or --help: Displays this online help
  
Options include:
  --country <country>: country code to set texts in multi-languages ​​(default: FR)
  --lang <language>: language code to set texts in multi-languages ​​(default: en)
  --option <file.ini>: opens the karto options file <file.ini> (default karto.ini or karto.xml).
  --carte <card.cto>: automatic opening of the card contained in the file passed as parameter. <card.cto> can be a calibrated kart file or an image that needs to be calibrated.
  - image <image.jpg>: same option card (compatility with old karto)
  --calque <file>: automatically opens the point file on the map (a calibrated map must be opened)
  --points <file>: same as layer option (old karto compatibility)
  --pt <code_pt>: automatically selects the topo point (of the active map) whose code is passed as parameter
  --registerImage <imageResult.jpg>: automatic saving of the open and automatically generated map. Image generated in PNG format JPEG JPG BMP WBMP
  --traceFile: save the traces in the text file 'trace.txt'. No trace is sent to the screen

III. Karto V 2.0
-----------------
1. Compatibility with Karto 0.9

* The user data (calibrated cards, point files, style files) which has been generated using the old version of Karto can be used without modification with the new version of Karto.
* The karto.ini configuration file is compatible with the new karto. When karto starts for the first time, it will be transformed into an xml file (karto.xml) and enriched with new parameters which are specific to this new version of the software.

2. What's new:

* The new version of Karto is compatible with the latest versions of Java (Java 1.8 / 1.9 / 1.10).
* On maps, there is no limit to the number of open layers (10 layers was the limit on the old version, the new version limit is only the memory capacity of the machine). The same applies to the topographic points in a layer, that is to say The limit is only the processing power of the machine, and its available memory.
* From the command line, when launching Karto:
** new options are available on the command line and it is now possible to not only open a calibrated map, but to also open a specific point file, and even to automatically select a topo point. Please refer to the online help (--help option), or to the documentation for more information.
** via the command line options, it is possible to automatically generate a map with a point file, without opening the interface. This allows the scripting (at the command line) of certain processes and the generating (or updating) of images automatically, without any human intervention.
* the layers:
** ability to create new java classes to handle other types of layers on the map. As for point styles, there is the class abstract Obj_Graph. This is of course reserved for developers. Please see the doc karto_expert.odt for more information.
** Planar (or topographic) image files used for map reports no longer need to be saved in "transparent mode" GIF, as Karto automatically identifies the dominant color (the one with the most pixels) and puts it in transparency. So with any basic drawing software (even Windows Paint) the plans can be saved as gif or png for posting on karto.
** style options allow you to force a minimum width to the paths, as well as a color for the entire path (to make it more visible on the map background). These styles can be defined for each plan layer, and for each map.
** management of a new layer: VTOPO files
** management of point files and GPS tracks in GPX format (garmin)
** management of point files and GPS tracks in Google Map format (.kml and .kmz files)
* the styles of points:
** Add new topo point styles, especially UIS symbols from 1999 and 2016. Please refer to the documentation.
** ability to define an image as a graphical representation of the point. The symbol can be drawn as GIF or PNG images, and can be configured in a style file. New symbols can be therefore defined this way without needing to be programmed, but simply by providing image files, and by configuring the point style. Please refer to the topographic point style documentation for more information.
** Hierarchical management of point styles with notion of property inheritance. In this way, a style does not redefine all its properties (size, shape, color, ...) but only the specific properties which differ from those of the style from which it "inherits".
** The complete rewrite of the program under a new architecture, allows IT developers to add new java code classes to draw topo points. There is no need to recompile the entire program, as it is sufficient to just compile the classes by setting the jar or .class in the program's classpath. In order to write classes, it is enough to implement the methods of the abstract Obj_Graph class, or to derive an existing class.
** ability to set your own colors in "kart options". These colors can then be used to define styles and point colors.
* possibility to view the list of character fonts available on layers (via the option --ListFont) which generate an image with all fonts known on the computer, and therefore usable.
* Annexes :
** the ancillary documents associated with the topographic points can be images (GIF, PNG, JPG, BMP), or documents (TXT, RTF, HTML), present on the hard drive of the computer, or on a website (URLs are acceptable)
** possibility for developers to add new java classes managing other types of files by integrating these new classes in karto, without needing to recompile the application. Please see the Karto_Expert documentation for more information.
* Automatic exporting of a small image centered on each point topo (or map) reported on the map. This image integrates the point and all its environment (visible on the map). The size and format of the image are configurable. Ability to launch the export command line.
* Management of the multi-processor: for computations requiring lots of processing power (large number of points on the same layer, big topo VTOPO with many sights), the calculations are launched on several processors in parallel. The number of usable processors is set in the kart options. This function can be activated or not by a Karto parameter. This multi-processor mode is also useful for very large basemaps (> 3000 pixels of sides)
* Display a ruler at the top left of the map with the kilometer grid of the map

3. Performance and Big Data

When it comes to managing very large amounts of data (point files with several thousand or tens of thousands of points, topographies with several thousand shots), or a very large base map (map of several tens of MB, more than 3 or 4.000 pixels of sides), the computation and refresh times can be quite slow.
Similarly, and to people having used the first version of Karto (Karto v0.9) on an old computer (say, before 2015) the performance losses (with the same cards and running on the same computer) might appear considerable (the old Karto being "faster" than the new one).
Optimization options are available in the kart configuration (display optimization, multi-processor calculation). It is advisable to activate and to configure them in accordance with the settings of the computer being used.
When using the image transfer function (image layer transfer), please pay attention to the size of the layers which are being used. An image (a plane) of more than 1,000 or 2,000 pixels of dimensions reported on kart can quickly result in tenths of seconds to materialise, and the total time can therefore be quite significant where there exists a lot of plan reports. Do try to reduce the size of the images to make it as close as possible tothe scale of the map (e.g. it is useful to have a plan at 1/1000 ° for a report on a map at 1/25000 °). This will significantly improve the performance of the computer (and of Karto) without resulting in the loss of information (remember that there will in any case be a loss when Karto performs its scaling).


4. Remain the master and owner of your data

With Karto, the data is managed directly by the owner, and remains the owner property. No piracy and resale of the date can be undertaken without your knowledge because when "free online tools" such as "Google Maps" (for example) are used, it is you who decide to automatically grant the rights for your hosts to use your data.
Example: The Google license (which you have probably never read) on https://policies.google.com/terms?hl=en:
   Your content and services

   Some of our Services allow you to import, submit, store, send or receive content. You keep all your intellectual property rights on these contents. In short, what is yours remains yours.

   When you upload, submit, store, send or receive content to or through our Services, you grant to Google (and to anyone working with Google) a license, worldwide, for use, hosting, storage, reproduction, modification, creation of derivative works (translations, adaptations or other modifications intended to improve the functioning of your content through our Services), communication, publication, representation public display or public distribution of such content. Your rights under this license are limited to the operation, promotion or enhancement of our Services, or the development of new Services. This permission remains for the full legal term of protection of your content, even if you stop using our Services (for example, for a business listing that you have added to Google Maps). Some Services offer you the means to access and delete content that you have submitted to this Service. Some Services also provide conditions or settings restricting the scope of our right to use content that you have submitted to the Services in question. Make sure that you have all the rights to grant us this license for the content you submit to our Services.

With Karto, there is no problem: your data is on your computer, and it stays there with you remaining the mastery. There is not broadcasting of the data on the net, and your computer does not even need to be connected to the network! This thus allows you to preserve the confidentiality of your data.
 
IV. Bugs and planned evolutions
------------------------------
1. Evolutions since release 2.0
V 2.0.12  :
==========
- Bug : error on calibrating new map. Impossible to calibrate the image.

V 2.0.10 (january 2020)
--------
- Export topographic maps (plan maps) to the SIG software QGIS (format .shp) : export in .shp file in the MultiPatch format 

V 2.0.8 :
---------
- interface with QGIS GIS software (.shp format). Read and Write QGIS files with points and GPS tracks.

V 2.0.6 :
---------
- selecting points with the mouse select only the visible points, not the points hidden (hidden style)

V 2.0.5 :
---------
Bugs fixed :
- default style for image layers set to NONE color and 0 default thickness
- fixed: random lock when manually adding a points layer

V 2.0.4:
---------
Evolutions made in the release:
- put the numbering of km in the center of the grid

Bugs fixed:
- sorting of labels: repositioned labels are no longer displayed

V 2.0.2:
--------
Evolutions made in the release:
- optimization of the displays by the treatment of the object layers via transparent mini-layers, and printing on the background map via the paint method for each of the objects. multitask management of all calculations and drawings (up to paint).
- display the list of problems (point topo) on the layer (with the possibility of printing it): lack coord, etc => Menu Poster / List of points / With wrong coordinates

Bugs fixed:
- corrected automatic style test procedure (error in symbol generation)
- text correction "color selected" in "color of selection" for config styles.
- selection rectangle. there is sometimes a white rectangle (after a mouse selection of a single point), or the old rectangle reappears after a new rectangle has been displayed after a multiple selection.

2. Known bugs
- in the layer edit, if there are very few points on the map, the search for a zone may fail => center the map thumbnail on the first point of the list on the map
- When the grid of a map is tilted, the alignment of the rule does not follow the grid when moving within the map, it creates a shift between the rule and the map displayed
- in VTopo layer management: in T junctions, width management can be reversed in junction view.
- java bug: when zooming at the edge of the map (bigger zoom), the center of the image is not preserved and slides to the top left: this results in the magnification of the image not being taken into account (still) by java object blocking the movement of lifts ??
- selection rectangle. there is sometimes a white rectangle (after a mouse selection of a single point), or the old rectangle reappears after the display of a new rectangle following a multiple selection.

3. Foreseen developments

Complementary ideas, depending on time, technical possibilities, emergencies, and ... requests ...

- Card printing
- management of "mega cards" (assembly in any checkerboard)
- see the Topo reports from Therion and import these traces.

V. Acknowledgments
----------------

Thanks to Thierry VIEVILLE (INRIA Sophia) who gave me permission to use his mathematical library for solving equations.
Thanks to François GASPARD (CEA Paris) who provided the matrix calibration computations and who let me profit from all his reflections on this subject.
Thanks to Michel RADECKI for all the english translations
Thanks to Yolanda RAZO for the spanish translation