An R package to derive outline shapes from (multiple) artefacts on JPEG images.
outlineR: An R package to derive outline shapes from (multiple) artefacts on JPEG images
This package is a helpful wrapper around functions from mainly the Momocs (Bonhomme et al. 2014), EBImage (Pau et al. 2010), and imager (Barthelme et al. 2020) packages. It is designed for the fast and easy extraction of single outline shapes of, for example, stone tools from images containing multiple thereof, such as the ones present in archaeological publications.
The raw data should have a sufficiently high resolution.
|Raw data (here: Morar Quartz Industry) as it can be found in archaeological publications. Credit: Wellcome Collection (CC BY 4.0).|
Manual image preparation
The raw images have to be converted to JPEG format and manually prepared in an image manipulation software. Numberings, descriptions, etc. (everything we do not want an outline of) have to be removed by hand. If the image is a picture taken of the artefacts, make sure to remove any cast shadows.
With the images cleaned, they now have to be thresholed/binarized[^1]. If not, the binarization happens inside the outlineR-package. However, it is not very robust and I advise you to do it manually beforehand.
|Manually prepared JPEG image with numberings etc. removed and thresholded using GIMP. It is suited to be used as input file for the `separate_single_artefacts` function and should therefore be saved in the `inpath`-folder (see below).|
0. Load the package
1. Path settings
inpath as the pathname to out manually prepared image (see above).
outpath defines the path to an empty folder where all prepared and singled-out artefacts should be saved to.```
Define where the images containing multiple artefacts are right now.
inpath <- "./testdata/inputdata"
Define where the separate images should be saved.
outpath <- "./testdata/deriveddata" ```
2. Separation of single artefacts
separate_single_artefacts separates single artefacts from pictures with multiple artefacts on it.
separate_single_artefacts(inpath = inpath, outpath = outpath)
Afterwards, the JPEGs of the single artefacts should be saved in the folder which you defined under
outpath. If there is just plain white images in your
outpath folder, re-check the images you prepared in
inpath for single outlier pixels or open outlines. If necessary, delete all JPEGS in
outpath. Then, re-run this command.
|The single, separated artefacts from our input file generated using `separate_single_artefacts`, now located in `outpath`.|
3. Outline extraction
Momocs::import_jpg(), this function extracts the outlines of the images, while at the same time preserving the images' names. This function only needs the files in your
outpath folder, so you do not (necessarily) have to run all of the code above again.
single_outlines_list <- get_outlines(outpath = outpath, tps_file_rescale = NULL)
If a .tps file with scaling factor is available, it can be transformed into a dataframe using the
tps_to_df() function and forwarded into
```tpsdf <- tpsto_df("path/to/tps/file.tps")
singleoutlineslist <- getoutlines(outpath = outpath, tpsfilerescale = tpsdf)```
4. Outline combination
The list of single outlines is combined into a single Out/Opn (Momocs) file.
outlines_combined <- combine_outlines(single_outlines_list = single_outlines_list)
5. Outline inspection
In a last step before starting to work with your outlines, you should inspect the just created outlines for validity and possible errors.
length(outlines_combined) #how many outlines do you have?stack(outlines_combined) # shows all outlines above one another(you might want to center and scale them first using Momocs)Momocs::panel(outlines_combined) # shows all outlines next to each otherMomocs::inspect(outlines_combined) # shows only a single outline at a time.
|Stacked outlines.||Panel of outlines.|
Barthelme et al. 2020: Barthelme, S., Tschumperle, D., Wijffels, J., Assemlal, H. E., & Ochi, S. (2020). imager: Image Processing Library Based on “CImg” (0.42.3) [Computer software]. https://CRAN.R-project.org/package=imager
Bonhomme et al. 2014: Bonhomme, V., Picq, S., Gaucherel, C., & Claude, J. (2014). Momocs: Outline Analysis Using R. Journal of Statistical Software, 56(13). https://doi.org/10.18637/jss.v056.i13
Pau et al. 2010: Pau, G., Fuchs, F., Sklyar, O., Boutros, M., & Huber, W. (2010). EBImage—An R package for image processing with applications to cellular phenotypes. Bioinformatics, 26(7), 979–981. https://doi.org/10.1093/bioinformatics/btq046
To restore the repository download the bundle
git clone yesdavid-outlineR_-_2021-06-18_18-20-24.bundle
Upload date: 2021-06-18
- 2021-07-06 16:33:13
- 2021-06-18 18:20:24
- Internet Archive Python library 1.9.9
- iagitup - v1.6.2