A Python package for processing 3D landmarks
Project description
Scyland3D: Processing 3D landmarks
Scyland3D
is a Python tool for converting 3D raw landmark and semilandmark coordinates exported from landmark acquisition software (e.g. Landmark Editor 3.6 from IDAV, UC Davis) to a csv format best suited for geometric morphometric analyses.
Processing schemes to mirror and reorder these points are provided to address further symmetry issues.
By:
- Fidji Berio (GitHub) from ISEM and IGFL,
- Yann Bayle (Website, GitHub) from LaBRI, Univ. Bordeaux, CNRS, and SCRIME.
Installation
Install and update using pip:
pip install -U Scyland3D
Dependencies:
- Python 2 or 3. Scyland3D has been tested with Python 2.7.16 and 3.6.3 and should work with older versions of Python.
- Numpy >= 1.13.3. Scyland3D has been tested with Numpy 1.13.3 and 1.16.2 and should work with older versions of Numpy.
If you encounter an error with other versions, please submit an issue.
Use-case example
To quickly process landmarks files, you can give Scyland3D the path to the folder containing the .pts
files (format defined on page 37 in http://www.idav.ucdavis.edu/research/projects/EvoMorph/supplement/LandmarkDoc_v3_b6.pdf), as shown in the example files provided:
import Scyland3D
Scyland3D.pts2csv("example/")
This will create a file named landmarks.csv
that you can use for statistical analyses in any language/software you want.
The example files provided come from a subset of our dataset for studying teeth of the small-spotted catshark Scyliorhinus canicula.
We provide 7 landmark and 31 semilandmark coordinates for 2 upper teeth and for 3 lower ones, stored in two folders that describe the specimens they belong to.
A landmark is a point set up by hand as opposed to a semilandmark that is interpolated by the computer between two landmarks by following the curvature of the studied form.
API documentation
The function pts2csv()
is the core of Scyland3D and is also called when using the script from the terminal with the following arguments:
- indir (required)
- A string containing the input directory where the files are stored. File names can specify the feature modalities separated by
_
(e.g. speciesA_ageX_sex1.pts). - Default: Use the "example/" folder
- Example:
Scyland3D.pts2csv("path/")
- Command line:
python -m Scyland3D.Scyland3D -i "path/"
- A string containing the input directory where the files are stored. File names can specify the feature modalities separated by
- outdir (optional)
- A string containing the output directory where the files will be generated.
- Default: Use the current folder.
- Example:
Scyland3D.pts2csv(outdir="path/")
- Command line:
python -m Scyland3D.Scyland3D -o "path/"
- order (optional)
- A list of integer indicating the new order to apply to the landmarks. The order_factor argument must also be supplied.
- Default: None
- Example:
Scyland3D.pts2csv(order_factor="upper", order=[36, 35, 34, 33, 32, 31, 30, 29, 28, 27, 26, 25, 24, 23, 22, 21, 20, 19, 18, 17, 16, 15, 14, 13, 12, 11, 10, 9, 8, 7, 6, 5, 4, 3, 2, 1, 0, 37])
- Command line:
python -m Scyland3D.Scyland3D -f "upper" -r "36, 35, 34, 33, 32, 31, 30, 29, 28, 27, 26, 25, 24, 23, 22, 21, 20, 19, 18, 17, 16, 15, 14, 13, 12, 11, 10, 9, 8, 7, 6, 5, 4, 3, 2, 1, 0, 37"
- order_factor (optional)
- A string containing the keyword for items that need their landmarks and semilandmarks to be reordered. The order argument must also be supplied.
- Default: None
- Example: if the dataset contains lower and upper teeth where only the upper teeth need to be reordered, one can use:
Scyland3D.pts2csv(order_factor="upper", order=[36, 35, 34, 33, 32, 31, 30, 29, 28, 27, 26, 25, 24, 23, 22, 21, 20, 19, 18, 17, 16, 15, 14, 13, 12, 11, 10, 9, 8, 7, 6, 5, 4, 3, 2, 1, 0, 37])
- Command line:
python -m Scyland3D.Scyland3D -f "upper" -o "36, 35, 34, 33, 32, 31, 30, 29, 28, 27, 26, 25, 24, 23, 22, 21, 20, 19, 18, 17, 16, 15, 14, 13, 12, 11, 10, 9, 8, 7, 6, 5, 4, 3, 2, 1, 0, 37"
. This is only valid if the keywordupper
is present in the file name.
- feature_names (optional)
- A list of string containing the feature names.
- Default: None
- Example:
Scyland3D.pts2csv(feature_names=["identifier", "species", "location", "length", "sex", "stage", "jaw", "position", "generation"])
- Command line:
python -m Scyland3D.Scyland3D -n "identifier,species,location,length,sex,stage,jaw,position,generation"
- verbose (optional)
- A boolean indicating if information should be printed on the console by the process.
- Default: True
- Example:
Scyland3D.pts2csv(verbose=False)
- Command line:
python -m Scyland3D.Scyland3D -v False
for removing the display of information to the console.
- mirror_factor (optional)
- A string containing the keyword for items to be mirrored in the 3D space.
- Default: None
- Example:
Scyland3D.pts2csv(mirror_factor="upper")
- Command line:
python -m Scyland3D.Scyland3D -m "upper"
will mirror in 3D the files containing the keywordupper
before processing them with the remaininglower
items as depicted in the figure below:
More information can be found on the related article.
How To Contribute
Contributions are welcome! Please refer to the CONTRIBUTING.md file.
License
Scyland3D is licensed under the MIT License as described in the license file. Please use the following citation:
@article{Berio2019,
author = {Berio, Fidji and Bayle, Yann},
title = {{Scyland3D: Processing 3D landmarks}},
journal = {{The Journal of Open Source Software}},
page = {1153--1155},
volume = {4},
issue = {33},
doi = {10.21105/joss.01153},
note = {Review pending}
}
Acknowledgements
We acknowledge the contribution of SFR Biosciences (UMS3444/CNRS, US8/Inserm, ENS de Lyon, UCBL) facilities: AniRA-ImmOs and Mathilde Bouchet for her help with X-ray microtomography.
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for Scyland3D-1.0.16-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | d7e5a5f65464dcc7cf1ad030484b4a3fe8ebe601b4644affd027fa7b6bbf0071 |
|
MD5 | e41576d58a70d02ee81b505f7ef44e9d |
|
BLAKE2b-256 | 766bc3f43b5ab0a0f435307894e29a329563c42f1b20f0c574f6f79622727cc2 |