p4tools

Tools for working with Planet Four data.

Installation

pip install p4tools

Features

Provide easy access to the Planet Four catalog data.
- Data will be automatically downloaded and cached by the pooch library.
- The first time it will take a few seconds to download the data, the next time it will be using the cache.
Provide automatic downloading of the png tiles of the catalog.
Provide plotting tools

Note: The original data for input to the Planet Four projects were these _COLOR products like this one: https://hirise-pds.lpl.arizona.edu/PDS/EXTRAS/RDR/ESP/ORB_011400_011499/ESP_011486_0980/ESP_011486_0980_IRB.NOMAP.browse.jpg (not the browse product though, but the full size of course)

Paper

The underlying paper for this work is:

Aye, K.-M., Schwamb, M.E., Portyankina, G., Hansen, C.J., McMaster, A., Miller, G.R.M., Carstensen, B., Snyder, C., Parrish, M., Lynn, S., Mai, C., Miller, D., Simpson, R.J., Smith, A.M., 2019. Planet Four: Probing springtime winds on Mars by mapping the southern polar CO2 jet deposits. Icarus 319, 558–598. https://doi.org/10.1016/j.icarus.2018.08.018

from p4tools import io

# get the catalogs
fans = io.get_fan_catalog()
blotches = io.get_blotch_catalog()
fans.head()

	marking_id	angle	distance	tile_id	image_x	image_y	n_votes	obsid	spread	version	...	y_angle	l_s	map_scale	north_azimuth	BodyFixedCoordinateX	BodyFixedCoordinateY	BodyFixedCoordinateZ	PlanetocentricLatitude	PlanetographicLatitude	Longitude
0	F000000	205.56	179.71	APF0000ci9	2270.76	24336.16	35	ESP_012079_0945	88.03	1	...	-0.43	214.785	0.25	126.856883	-65.804336	261.407884	-3370.504345	-85.427383	-85.480829	104.129523
1	F000001	185.39	179.62	APF0000cia	3391.21	5640.60	15	ESP_012079_0945	21.35	1	...	-0.09	214.785	0.25	126.856883	-67.219114	257.011589	-3370.631413	-85.493546	-85.546226	104.656897
2	F000002	184.98	500.27	APF0000cia	3509.96	5876.70	10	ESP_012079_0945	18.91	1	...	-0.09	214.785	0.25	126.856883	-67.170611	257.055226	-3370.630794	-85.493039	-85.545725	104.644396
3	F000004	184.29	105.43	APF0000cia	3716.27	5824.50	6	ESP_012079_0945	26.41	1	...	-0.07	214.785	0.25	126.856883	-67.127761	257.024926	-3370.635002	-85.493723	-85.546401	104.637107
4	F000005	189.42	109.50	APF0000cia	3452.17	6033.00	3	ESP_012079_0945	22.58	1	...	-0.16	214.785	0.25	126.856883	-67.169940	257.096267	-3370.628302	-85.492368	-85.545061	104.642019

5 rows × 24 columns

# get fans for a given tile_id
fans_for_tile = io.get_fans_for_tile("APF0000cro")
fans_for_tile.head()

	marking_id	angle	distance	tile_id	image_x	image_y	n_votes	obsid	spread	version	...	y_angle	l_s	map_scale	north_azimuth	BodyFixedCoordinateX	BodyFixedCoordinateY	BodyFixedCoordinateZ	PlanetocentricLatitude	PlanetographicLatitude	Longitude
639	F00028e	176.82	357.51	APF0000cro	1904.17	469.07	30	ESP_012079_0945	29.52	1	...	0.06	214.785	0.25	126.856883	-68.025795	255.956937	-3370.658673	-85.507336	-85.559856	104.883467
640	F00028f	177.09	122.21	APF0000cro	1948.37	602.24	25	ESP_012079_0945	22.86	1	...	0.05	214.785	0.25	126.856883	-68.003644	255.983513	-3370.657733	-85.506997	-85.559521	104.877359
641	F000290	177.02	137.73	APF0000cro	1666.29	290.83	24	ESP_012079_0945	19.18	1	...	0.05	214.785	0.25	126.856883	-68.096623	255.937481	-3370.658914	-85.507347	-85.559867	104.899357
642	F000291	178.83	97.55	APF0000cro	1875.95	400.38	16	ESP_012079_0945	35.51	1	...	0.02	214.785	0.25	126.856883	-68.038458	255.943748	-3370.659367	-85.507498	-85.560016	104.886848
643	F000292	178.56	108.57	APF0000cro	2316.12	491.00	4	ESP_012079_0945	52.76	1	...	0.03	214.785	0.25	126.856883	-67.928961	255.925385	-3370.666710	-85.508282	-85.560791	104.864970

5 rows × 24 columns

Metadata

Metadata for the HiRISE observions that were used for the input data to the project:

# get the metadata of the HiRISE images
metadata = io.get_meta_data()

metadata.head()

	OBSERVATION_ID	IMAGE_CENTER_LATITUDE	IMAGE_CENTER_LONGITUDE	SOLAR_LONGITUDE	START_TIME	map_scale	north_azimuth	# of tiles
0	ESP_011296_0975	-82.1965	225.2530	178.833	2008-12-23 16:15:26	1.0	110.600107	91
1	ESP_011341_0980	-81.7969	76.1304	180.809	2008-12-27 04:25:02	0.5	110.208923	126
2	ESP_011348_0950	-85.0427	259.0940	181.117	2008-12-27 17:29:17	1.0	123.624057	91
3	ESP_011350_0945	-85.2160	181.4150	181.205	2008-12-27 21:14:01	0.5	99.672793	126
4	ESP_011351_0945	-85.2157	181.5480	181.249	2008-12-27 23:05:54	1.0	127.960688	91

# get the lat/lon or BodyFixedcoordinates of the tiles
coords = io.get_tile_coords()
coords.head()

	x_tile	y_tile	x_hirise	y_hirise	PlanetocentricLatitude	PlanetographicLatitude	PositiveEast360Longitude	BodyFixedCoordinateX	BodyFixedCoordinateY	BodyFixedCoordinateZ	tile_id	obsid
0	1	1	420.0	324.0	-85.504144	-85.556701	104.952104	-68.380674	256.056147	-3370.636698	APF0000cwz	ESP_012079_0945
1	1	2	420.0	872.0	-85.502300	-85.554878	104.934805	-68.331337	256.181661	-3370.628630	APF0000ck9	ESP_012079_0945
2	1	3	420.0	1420.0	-85.500454	-85.553054	104.917486	-68.281853	256.307249	-3370.620295	APF0000cty	ESP_012079_0945
3	1	4	420.0	1968.0	-85.498607	-85.551228	104.900198	-68.232522	256.433112	-3370.615690	APF0000ciy	ESP_012079_0945
4	1	5	420.0	2516.0	-85.496762	-85.549404	104.882968	-68.183281	256.558509	-3370.606455	APF0000cwp	ESP_012079_0945

Image tiles

The png tiles of the HiRISE images are automatically downloaded and cached by the pooch library.

# get the urls of the tiles
tile_urls = io.get_tile_urls()
tile_urls.head()

	tile_id	tile_url
0	APF0000coq	http://www.planetfour.org/subjects/standard/50...
1	APF0000cro	http://www.planetfour.org/subjects/standard/50...
2	APF0000cs6	http://www.planetfour.org/subjects/standard/50...
3	APF0000co1	http://www.planetfour.org/subjects/standard/50...
4	APF0000cpd	http://www.planetfour.org/subjects/standard/50...

# or get the url for a tile id
io.get_url_for_tile("APF0000cro")

'http://www.planetfour.org/subjects/standard/50e742bf5e2ed212400040a4.jpg'

# get the png as numpy array:
img = io.get_subframe_for_tile("APF0000cro")
img

array([[[146,   1,   8],
        [146,   1,   6],
        [145,   0,   5],
        ...,
        [116,   3,   0],
        [115,   1,   0],
        [115,   3,   1]],

       [[147,   2,   7],
        [146,   1,   6],
        [145,   0,   2],
        ...,
        [119,   1,   0],
        [119,   1,   0],
        [117,   2,   0]],

       [[145,   3,   2],
        [145,   1,   1],
        [147,   0,   0],
        ...,
        [125,   0,   0],
        [124,   0,   0],
        [125,   0,   0]],

       ...,

       [[121,  96,  76],
        [126,  99,  80],
        [127,  99,  78],
        ...,
        [125,  93,  72],
        [124,  92,  71],
        [130,  98,  77]],

       [[118,  91,  70],
        [124,  97,  76],
        [123,  95,  74],
        ...,
        [130,  98,  77],
        [125,  93,  72],
        [130,  98,  75]],

       [[111,  84,  63],
        [116,  89,  68],
        [114,  83,  63],
        ...,
        [132, 100,  79],
        [127,  95,  72],
        [133, 101,  78]]], dtype=uint8)

io.get_hirise_id_for_tile("APF0000cro")

'ESP_012079_0945'

License

MIT license

Credits

Developer and Maintainer

K.-Michael Aye kmichael.aye@gmail.com

Contributors

Some ideas and concepts came from Meg Schwamb