[docs] Update docs

Signed-off-by: x7z4w <x7z4w@noreply.codeberg.org>
2025-12-19 04:53:36 +00:00 · 2025-07-30 08:53:19 +00:00
parent d7ece38279
commit f88b0afa58
8 changed files with 59 additions and 57 deletions
--- a/INSTALL.md
+++ b/INSTALL.md
@@ -1 +1 @@
-See [docs/INSTALL.md](docs/INSTALL.md)
+See [docs/INSTALL.md](docs/INSTALL.md) 
--- a/README.md
+++ b/README.md
@@ -125,10 +125,8 @@ You can help by donating, contributing code, translating, or by telling others a

 - Build instructions: [docs/INSTALL.md](docs/INSTALL.md)  
 - Contribution guide: [docs/CONTRIBUTING.md](docs/CONTRIBUTING.md)
-> [!NOTE]  
-> Some docs might be outdated, contain broken links or old references to Organic Maps, etc. Its a work in progress and help is much appreciated!

-There is a dedicated Zulip chat for active contributors: [Zulip](https://comaps.zulipchat.com)
+There is a dedicated [Zulip](https://codeberg.org/comaps/Governance/src/branch/main/contribute.md#3-team-messaging) chat for active contributors.

 ---

--- a/docs/CONTRIBUTING.md
+++ b/docs/CONTRIBUTING.md
@@ -104,7 +104,11 @@ Git has a flag that can sign a commit for you. An example using it is:

    git commit -s -m 'An example commit message'

-You can sign-off using your pseudonym or real name.
+Or, if you're making edits using Codeberg UI, check "Add a Signed-off-by trailer
+by the committer at the end of the commit log message" before saving.
+
+You can sign-off using your pseudonym or real name, and using
+"somedev@noreply.codeberg.org" as an email instead of a real one.

 ## Team Messaging

--- a/docs/MAPS.md
+++ b/docs/MAPS.md
@@ -1 +1 @@
-Please refer to maps_generator tool [instructions](../tools/python/maps_generator/README.md).
+Please refer to maps_generator tool [instructions](../tools/python/maps_generator/README.md). 
--- a/docs/STYLES.md
+++ b/docs/STYLES.md
@@ -84,7 +84,7 @@ by rebuilding styles and symbols quickly, but it's broken as of now, please help
 To test on Android or iOS device either re-build the app or put
 the compiled style files (e.g. `drules_proto_default_light.bin`) into
 a `styles/` subfolder of maps directory on the device
-(e.g. `Android/data/app.organicmaps/files/styles/`).
+(e.g. `Android/data/app.comaps/files/styles/`).

 Changing display zoom level for features (e.g. from z16- to z14-) might
 not take effect until map's visibility/scale index is rebuilt:
--- a/docs/feature_structure.md
+++ b/docs/feature_structure.md
@@ -0,0 +1,48 @@
+[!NOTE]
+This info might be outdated.
+
+First byte:
+- 0 - Amount of types (1-8, write as 0-7, 3 bits)
+- 3 - Name
+- 4 - Layer
+- 5, 6 - Geometry type (point = 00, line = 01, area = 10)
+- 7 - Bit indicating the presence of additional information:
+  - Point - rank (1 byte as the logarithm of population base 1.1);
+  - Line - road number (string);
+  - Area - house number (string, optimized for storing a two-digit number);
+
+* Write types, name, layer, additional information, and point (for point type)
+
+1 or 2 bytes of the next header (only for line and/or area objects):
+* 4 bits for the number of internal points for a line object:
+  - 0 - geometry is extracted; read the offset mask and offsets;
+  - 2 - 0 bytes for the simplification mask;
+  - 3-6 - 1 byte for the simplification mask;
+  - 7-10 - 2 simplification mask bytes;
+  - 11-14 - 3 simplification mask bytes;
+* 4 bits for the number of internal triangles for an area object:
+  - 0 - geometry is extracted; read the offset mask and offsets;
+  - \>0 - number of triangles in one strip (for multiple strips, geometry is extracted);
+
+* 4 bits for the offset mask for line and area objects.
+The offset mask determines the presence of extracted geometry for the i-th scale row (out of 4, according to the corresponding bit).
+
+These 2 bytes may be located in one byte when the object is of one type or the geometry is not extracted.
+In reality, this will be 2 bytes when the object is both line and area and has extracted geometry.
+
+Following bytes:
+* Write geometry ...
+  - Simplification mask for a line object (1-3 bytes):
+    The 1-byte simplification mask encodes the visibility of 4 points in 4 scale rows (2 bits per point), i.e.
+    equal to the scale row value from which the point is already visible.
+  - Array of geometry points (triangle strip) according to the known amount VarInt64
+* ... or write the array of offsets to the extracted geometry (number taken from the offset mask)
+
+Extracted geometry for a scale is representing a block:
+- Size of the geometry in bytes
+- Serialized VarInt64s by the number of bytes
+
+For a line object, they represent an array of points.
+For an area object, they represent the following sequences:
+- Number of points on the strip
+- The strip itself (array of points)
--- a/docs/feature_structure.txt
+++ b/docs/feature_structure.txt
@@ -1,46 +0,0 @@
-1-й байт:
-0. кол-во типов (1-8, пишем 0-7, 3 бита)
-3. имя
-4. слой
-5, 6. - тип геометрии (точка = 00, линия = 01, площадной = 10)
-7. бит присутствия дополнительной информации:
-	- точка - ранг (1 байт как логарифм населения по основанию 1.1);
-	- линейный - № дороги (строка);
-	- площадной - № дома (строка, оптимизированная для хранения двузначного числа);
-
-* пишем типы, имя, слой, дополнительную информацию, точку (для точечного типа)
-
-1 или 2 байта следующего заголовка (только для линейного и\или площадного объекта):
-* 4 бита кол-ва внутренних точек для линейного объекта:
-	- 0 - геометрия вынесена, идем читать маску смещений и смещения;
-	- 2 - 0 байт на маску упрощения;
-	- 3-6 - 1 байт на маску упрощения;
-	- 7-10 - 2 бму;
-	- 11-14 - 3 бму;
-* 4 бита кол-ва внутренних треугольников для площадного объекта:
-	- 0 - геометрия вынесена, идем читать маску смещений и смещения;
-	- >0 - кол-во треугольников одного стрипа (для нескольких стрипов геометрия выносится);
-
-* по 4 бита для маски смещений для линейного и площадного объекта.
-Маска смещений опряделяет наличие вынесенной геометрии для i-го масштабного ряда (из 4-х по соотв. биту).
-
-Эти 2 байта актуально могут быть расположены в одном, когда объект одного типа или геометрия не вынесена.
-Реально это будет 2 байта когда объект сразу линейный и площадной и у него вынесена геометрия.
-
-Следующие байты:
-* пишем геометрию ...
-	- маска упрощения для линейного объекта (1-3 байта):
-	Маска упрощения в 1 байт кодирует видимость 4-х точек в 4-х масштабных рядах (по 2 бита), т.е.
-	равна значению масштабного ряда, с которого точка уже видна.
-	- массив точек геометрии (треугольников стрипа) по извесному количеству VarInt64
-* ... или пишем массив смещений на вынесенную геометрию (количество берем из маски смещений)
-
-
-Вынесенная геометрия для масштаба представляет собой блок:
- размер геометрии в байтах
- сериализованные VarInt64 по кол-ву байт
-
-Для линейного объекта они представляют собой массив точек.
-Для площадного представляют собой следующие последовательности:
- количество точек с стрипе
- сам стрип (массив точек)
--- a/tools/python/maps_generator/README.md
+++ b/tools/python/maps_generator/README.md
@@ -1,6 +1,6 @@
 # maps_generator

-`maps_generator` is the Python CLI for generating `.mwm` maps for the Organic Maps application. This tool functions as the driver for the `generator_tool` C++ executable.
+`maps_generator` is the Python CLI for generating `.mwm` maps for the CoMaps. This tool functions as the driver for the `generator_tool` C++ executable.

 **Use the `generator_tool` and application from the same release. The application does not support
 maps built by a generator_tool newer than the app.**
@@ -20,7 +20,7 @@ You must have Python version >= 3.7 and complete the following steps:
 git checkout 2023.06.04-13-android
 ```

-The app version can be found in the "About" section of Organic Maps app.
+The app version can be found in the "About" section of CoMaps.

 2. Build the `generator_tool` binary (run from the root of the repo):

@@ -75,8 +75,6 @@ To see other possible command-line options:
 python -m maps_generator -h
 ```

-If you are not from the Organic Maps team, then you do not need the `--production` option.
-
 ## Troubleshooting

 The general log file (by default its `maps_build/generation.log`) contains output of the `maps_generator` python script only. More detailed logs that include output of the `generator_tool` binary are located in the `logs/` subdir of a particular build directory, e.g. `maps_build/2023_06_04__20_05_07/logs/`.