Skip to content

Commit 946da5f

Browse files
markolbertmarkolbert
committed
update docs
1 parent 6217794 commit 946da5f

File tree

14 files changed

+288
-55
lines changed

14 files changed

+288
-55
lines changed

‎J4JMapLibrary/docs/authentication.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -23,4 +23,4 @@ The authentication methods return true if they succeed, false if they don't.
2323

2424
The only service where authentication might fail is Bing Maps, because Bing Maps requires interaction with the web to complete authentication and acquire various pieces of information required to access the service. That can fail for many reasons, including inability to access the web.
2525

26-
[return to table of contents](usage.md#overview)
26+
[return to usage](usage.md)

‎J4JMapLibrary/docs/caching.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -42,3 +42,5 @@ var tileMemCache = new MemoryCache(LoggerFactory)
4242
RetentionPeriod = memRetention
4343
};
4444
```
45+
46+
[return to usage](usage.md)

‎J4JMapLibrary/docs/changes.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,4 +2,4 @@
22

33
|Version|Comments|
44
|:-----:|--------|
5-
|1.0|Initial release|
5+
|0.8|Initial release|

‎J4JMapLibrary/docs/creating-a-projection.md‎

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
# J4JMapLibrary: Creating a Projection Instance
22

3-
To simplify obtaining a `Projection` instance I incorporated a factory method in the library. However, you can also obtain an instance by instantiating the projection yourself. These first few sections describe how to do that. To see how to use the factory approach, [jump to this section](usage.md#using-the-projection-factory).
3+
To simplify obtaining a `Projection` instance I incorporated a factory method in the library. However, you can also obtain an instance by instantiating the projection yourself. These first few sections describe how to do that. To see how to use the factory approach, [jump to this section](factory.md).
44

55
Each service has its own unique projection class:
66

@@ -17,4 +17,6 @@ Three of the projections accept optional instances of `ITileCache` and `ILoggerF
1717

1818
`ITileCache` is an instance of one or more classes that implement caching. For details, [consult the caching documentation](caching.md).
1919

20-
[return to table of contentes](usage.md#overview)
20+
[return to creating a projection](creating-a-projection.md)
21+
22+
[return to using the map factory](factory.md)

‎J4JMapLibrary/docs/custom-projection.md‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
# J4JMapLibrary: Writing Your Own Projection Class
2+
3+
coming soon

‎J4JMapLibrary/docs/custom-projections.md‎

Lines changed: 0 additions & 11 deletions
This file was deleted.

J4JMapLibrary/docs/background.md renamed to J4JMapLibrary/docs/deprecated/background.md

File renamed without changes.

‎J4JMapLibrary/docs/development.md‎

Lines changed: 0 additions & 3 deletions
This file was deleted.

‎J4JMapLibrary/docs/maptile.md‎

Lines changed: 29 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -2,11 +2,24 @@
22

33
## Overview
44

5-
`MapTile` is the class used to return image data in the library. This is true even for **static** projections, like Google Maps, which only ever return one 'tile' (whose size depends on the request being made).
5+
- [Interface](#interface)
6+
- [The Constructor and Contextual Properties](#the-constructor-and-contextual-properties)
7+
- [Positioning and Sizing MapTiles](#positioning-and-sizing-maptiles)
68

7-
`MapTile` is a fairly complex object, offering a lot of information about the map area it represents, in addition to the actual image data. It's also one of the ways -- and arguably the best way -- to retrieve image data, from either the cache (if one is being used) or the underlying online map service.
9+
`MapTile` is the class used to hold image data in the library. This is true even for **static** projections, like Google Maps, which only have one 'tile' (whose size depends on the request being made).
810

9-
`MapTile`s always exist in relation to some `MapRegion`. There are no independent `MapTile`s. That's because a `MapRegion` defines certain essential features of multiple `MapTile`s. This includes the projection the `MapTile` is drawn from and the map scale it embodies.
11+
MapTiles always exist in relation to some `MapRegion`. There are no independent `MapTile`s. That's because a `MapRegion` defines certain essential features of multiple `MapTile`s. This includes the projection the `MapTile` is drawn from and the map scale it embodies.
12+
13+
`MapTile` is a fairly complex object, offering a lot of information about the map area it represents, in addition to the actual image data. However, it itself does not retrieve image data -- it merely holds it. There are two properties directly associated with the image data:
14+
15+
|Property|Type|Description|
16+
|--------|----|-----------|
17+
|`ImageData`|`byte[]?`|a byte array of the actual image data|
18+
|`ImageBytes`|`long`|the number of image data bytes, or -1 if there is none|
19+
20+
Consult the [documentation on `Projection`](projection.md) to learn about the library's image retrieval methods.
21+
22+
## Interface
1023

1124
Here's what the `MapTile` interface looks like:
1225

@@ -32,12 +45,17 @@ string QuadKey { get; }
3245

3346
byte[]? ImageData { get; set; }
3447
long ImageBytes { get; }
48+
3549
byte[]? GetImage();
3650
Task<byte[]?> GetImageAsync( CancellationToken ctx = default );
3751
Task<bool> LoadImageAsync( CancellationToken ctx = default );
3852
Task<bool> LoadFromCacheAsync( ITileCache? cache, CancellationToken ctx = default );
3953
```
4054

55+
[return to overview](#overview)
56+
57+
[return to usage table of contents](usage.md)
58+
4159
## The Constructor and Contextual Properties
4260

4361
`Region` and `InProjection` are properties that relate to the context in which a `MapTile` exists.
@@ -68,6 +86,10 @@ In this context, the row number can be any integer; it doesn't have to correspon
6886

6987
The `Tile` constructor requires both a row number and a column (horizontal, *X*) number. The column number can be any value, but values below 0 or above the maximum number of tiles at the current map scale imply wraparound. When a `MapTile` is created its `X` property is set to -1.
7088

89+
[return to overview](#overview)
90+
91+
[return to usage table of contents](usage.md)
92+
7193
## Positioning and Sizing MapTiles
7294

7395
MapTiles have both a position and a size. In fact -- and this complicates using them -- MapTiles have multiple *kinds* of positions associated with them:
@@ -102,3 +124,7 @@ The `Height` and `Width` properties allow the `MapTile` to be sized. They can ac
102124
|`FragmentId`|`string`|a string which uniquely define's a MapTile in a way which can be incorporated into a file name for caching purposes|
103125

104126
Both of these properties are updated automatically whenever the `X` coordinate changes.
127+
128+
[return to overview](#overview)
129+
130+
[return to usage table of contents](usage.md)

‎J4JMapLibrary/docs/projection.md‎

Lines changed: 220 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,220 @@
1+
# J4JMapLibrary: Projection
2+
3+
## Overview
4+
5+
- [Interface](#interface)
6+
- [Meta Information](#meta-information)
7+
- [Map Scale](#map-scale)
8+
- [Authentication](#authentication)
9+
- [Retrieving Imagery](#retrieving-imagery)
10+
11+
`Projection` and its subclasses define how the library interfaces with various mapping services. They handle the processes of authentication and image retrieval, and provide information about a particular service's capabilities.
12+
13+
There is a subclass for each mapping service. They derive from two general-purpose subclasses, one for *static* map services which only ever return single images (e.g., Google Maps), and one for *tiled* map services, which return imagery organized around multiple tiles (e.g., Bing Maps). `StaticProjection` does not support caching. Projection classes derived from `TiledProjection` do.
14+
15+
Here is the class hierarchy with their corresponding named interfaces:
16+
17+
- `Projection` (`IProjection`)
18+
- `StaticProjection` (`IStaticProjection`)
19+
- `GoogleMapsProjection`
20+
- `TiledProjection` (`ITiledProjection`)
21+
- `BingMapsProjection`
22+
- `OpenStreetMapsProjection`
23+
- `OpenTopoMapsProjection`
24+
25+
## Interface
26+
27+
Here is the `IProjection` interface:
28+
29+
```csharp
30+
event EventHandler<bool>? LoadComplete;
31+
32+
string Name { get; }
33+
string Copyright { get; }
34+
Uri? CopyrightUri { get; }
35+
bool Initialized { get; }
36+
37+
float MaxLatitude { get; }
38+
float MinLatitude { get; }
39+
MinMax<float> LatitudeRange { get; }
40+
41+
float MaxLongitude { get; }
42+
float MinLongitude { get; }
43+
MinMax<float> LongitudeRange { get; }
44+
45+
int MaxRequestLatency { get; set; }
46+
int TileHeightWidth { get; }
47+
string ImageFileExtension { get; }
48+
49+
int MinScale { get; }
50+
int MaxScale { get; }
51+
MinMax<int> ScaleRange { get; }
52+
int GetHeightWidth( int scale );
53+
MinMax<float> GetXYRange( int scale );
54+
MinMax<int> GetTileRange( int scale );
55+
int GetNumTiles( int scale );
56+
57+
bool SetCredentials( object credentials );
58+
59+
Task<bool> SetCredentialsAsync(
60+
object credentials,
61+
CancellationToken ctx = default );
62+
63+
byte[]? GetImage( MapTile mapTile );
64+
Task<byte[]?> GetImageAsync( MapTile mapTile, CancellationToken ctx = default );
65+
66+
Task<MapTile> GetMapTileWraparoundAsync(
67+
int xTile,
68+
int yTile,
69+
int scale,
70+
CancellationToken ctx = default );
71+
72+
Task<MapTile> GetMapTileAbsoluteAsync(
73+
int xTile,
74+
int yTile,
75+
int scale,
76+
CancellationToken ctx = default );
77+
78+
Task<bool> LoadImageAsync( MapTile mapTile, CancellationToken ctx = default );
79+
80+
Task<bool> LoadRegionAsync(
81+
MapRegion.MapRegion region,
82+
CancellationToken ctx = default
83+
);
84+
```
85+
86+
[return to top](#overview)
87+
88+
[return to usage table of contents](usage.md)
89+
90+
## Meta Information
91+
92+
`Projection` defines a number of properties which simply describe a mapping service:
93+
94+
|Property|Type|Description|
95+
|--------|----|-----------|
96+
|`Name`|`string`|the unique name of the projection/mapping service|
97+
|`Copyright`|`string`|holds the copyright notice most services require you to display a copyright notice when you display their imagery. Set when the projection is authenticated.|
98+
|`CopyrightUri`|`Uri?`|holds the copyright Uri some services require you to display when you display their imagery. Set when the projection is authenticated.|
99+
|`Initialized`|`bool`|`true` after the projection is initialized and authenticated, `false` otherwise|
100+
|`MaxLatitude`|float|the maximum latitude supported by the projection|
101+
|`MinLatitude`|float|the minimum latitude supported by the projection|
102+
|`LatitudeRange`|`MinMax<float>`|used to conform latitude values to the allowable range of latitude values|
103+
|`MaxLongitude`|float|the maximum longitude supported by the projection|
104+
|`MinLongitude`|float|the minimum longitude supported by the projection|
105+
|`LongitudeRange`|`MinMax<float>`|used to conform longitude values to the allowable range of longitude values|
106+
|`MaxRequestLatency`|`int`|the maximum number of milliseconds a web request will wait to complete. Negative values mean 'wait forever'.|
107+
|`TileHeightWidth`|`int`|the height and width of the map service's tiles. Generally 256. Even *static* projections, like Google Maps, which do not return tiles use tiles internally.|
108+
|`ImageFileExtension`|`string`|defines the nature of the image data returned by a mapping service. Used when creating cached files by `FileSystemCache`.|
109+
110+
`Name` is used by other parts of the library to identify a particular projection class. The value of `Name` should be unique within an application (and, ideally, throughout the world so that any custom projection classes you write won't collide with someone else's).
111+
112+
[return to top](#overview)
113+
114+
[return to usage table of contents](usage.md)
115+
116+
## Map Scale
117+
118+
While a `Projection` defines the interaction with a mapping service, it does not define the details of the map service's underlying map. That's because the underlying map changes depending upon the *scale* at which it is viewed or used. `Projection` defines a number of properties and methods to work with map scaling.
119+
120+
|Property|Type|Description|
121+
|--------|----|-----------|
122+
|`MinScale`|`int`|the minimum scale factor supported by the map service. Usually, but not always, 0 (Bing Maps' minimum is 1)|
123+
|`MaxScale`|`int`|the maximum scale factor supported by the map service|
124+
|`ScaleRange`|`MinMax<int>`|used to conform map scale values to the allowable range of map scale values|
125+
126+
|Method|Return Value|Arguments|Description|
127+
|------|------------|---------|-----------|
128+
|`GetHeightWidth`|`int`|`int` scale|gets the height and width of the map service's underlying map at a given map scale (the underlying maps are square)|
129+
|`GetXYRange`|`MinMax<float>`|`int` scale|gets the allowable range of X and Y Cartesian coordinates of the map service's underlying map at a given map scale|
130+
|`GetTileRange`|`MinMax<int>`|`int` scale|gets the allowable range of horizontal/vertical *tile coordinates* of the map service's underlying map at a given map scale|
131+
|`GetNumTiles`|`int`|`int` scale|gets the total number of tiles in the map service's underlying map at a given map scale|
132+
133+
[return to top](#overview)
134+
135+
[return to usage table of contents](usage.md)
136+
137+
## Authentication
138+
139+
Authenticating a `Projection` relies on processing a *credentials* object. There are two methods for doing so:
140+
141+
```csharp
142+
bool SetCredentials( object credentials );
143+
144+
Task<bool> SetCredentialsAsync(
145+
object credentials,
146+
CancellationToken ctx = default );
147+
```
148+
149+
The *credentials* object is projection-specific. If you supply the wrong kind of object authentication will fail. Here are the credentials objects for each of the supported projections:
150+
151+
|Projection Type|Credentials Type|
152+
|---------------|----------------|
153+
|`BingMapsProjection`|`BingCredentials`|
154+
|`GoogleMapsProjection`|`GoogleCredentials`|
155+
|`OpenStreetMapsProjection`|`OpenStreetCredentials`|
156+
|`OpenTopoMapsProjection`|`OpenTopoCredentials`|
157+
158+
The structure of a credential type reflects the information needed to authenticate with its mapping service:
159+
160+
|Credentials Type|Property|Property Type|Comments|
161+
|----------------|--------|-------------|-----------|
162+
|`BingCredentials`|`ApiKey`|`string`||
163+
|`GoogleCredentials`|`ApiKey`|`string`||
164+
||`SignatureSecret`|`string`|used to encrypt each web request|
165+
|`OpenStreetCredentials`|`UserAgent`|chosen by you, but must uniquely identify your application. Consult the online documentation for details|
166+
|`OpenTopoCredentials`|`UserAgent`|chosen by you, but must uniquely identify your application. Consult the online documentation for details|
167+
168+
[return to top](#overview)
169+
170+
[return to usage table of contents](usage.md)
171+
172+
## Retrieving Imagery
173+
174+
There are five methods defined for retrieving map imagery from a `Projection`. All of them are asynchronous, because they deal with web-based services:
175+
176+
```csharp
177+
Task<byte[]?> GetImageAsync( MapTile mapTile, CancellationToken ctx = default );
178+
179+
Task<MapTile> GetMapTileWraparoundAsync(
180+
int xTile,
181+
int yTile,
182+
int scale,
183+
CancellationToken ctx = default );
184+
185+
Task<MapTile> GetMapTileAbsoluteAsync(
186+
int xTile,
187+
int yTile,
188+
int scale,
189+
CancellationToken ctx = default );
190+
191+
Task<bool> LoadImageAsync( MapTile mapTile, CancellationToken ctx = default );
192+
193+
Task<bool> LoadRegionAsync(
194+
MapRegion.MapRegion region,
195+
CancellationToken ctx = default
196+
);
197+
```
198+
199+
They differ in whether they simply return `byte[]` data or load an object (i.e., `MapTile`, `MapRegion`) with `byte[]` data:
200+
201+
|Method|Arguments|Comments|
202+
|------|---------|--------|
203+
|`GetImageAsync`|`MapTile` mapTile|gets the image data associated with a map service tile described by `mapTile`|
204+
||`CancellationToken` ctx||
205+
|`GetMapTileWraparoundAsync`|`int` xTile|creates and loads a `MapTile` based on the supplied `scale`, `xTile` and `yTile` values. Wraparound is supported.|
206+
||`int` yTile||
207+
||`int` scale|the map scale factor to use in defining the `MapTile`|
208+
||`CancellationToken` ctx||
209+
|`GetMapTileAbsoluteAsync`|`int` xTile|creates and loads a `MapTile` based on the supplied `scale`, `xTile` and `yTile` values. Wraparound is *not* supported.|
210+
||`int` yTile||
211+
||`int` scale|the map scale factor to use in defining the `MapTile`|
212+
||`CancellationToken` ctx||
213+
|`LoadImageAsync`|`MapTile` mapTile|loads image data into `mapTile`, getting it either from the cache (if one is defined) or the mapping service.|
214+
||`CancellationToken` ctx||
215+
|`LoadRegionAsync`|`MapRegion` region|loads image data into all the MapTiles defined for `region`, getting it either from the cache (if one is defined) or the mapping service.|
216+
||`CancellationToken` ctx||
217+
218+
[return to top](#overview)
219+
220+
[return to usage table of contents](usage.md)

0 commit comments

Comments
 (0)