Package: terran
Terranis a human perception library that provides computer vision
techniques and algorithms in order to facilitate building systems that interact
with people.The philosophy behind the library is to focus on tasks and problems instead of
models and algorithms. That is, it aims to always have the best possible
algorithm for the job given its constraints, and to take the burden of finding
which model performs best off you.The library strives to be friendly and easy-to-use. It's written fully in
Python and Pytorch, avoiding C++ extensions as much as possible, in order to
avoid difficulties in installation. Justpip installand you're good to go!We (currently) provide models for:face detection,face recognitionandpose estimation. We also offer several utility functions for efficiently
reading and visualizing results, which should simplify work a bit.Example of Terran's face detection and pose estimation capabilities.FeaturesEfficient I/Outilities to read and write videosthroughffmpeg. Frames
are pre-fetched in a background thread, allowing you to maximize GPU usage
when processing videos.Utilities toopen remote images, recursively find images, and (prettily)visualize results. We also allow reading fromvideo streamsand even
videos fromvideo platformssupported byYoutube-DL.Checkpoint management tool, so you don't have to manually download
pre-trained model files.Face detectionprovided through theRetinaFacemodel.Face recognitionprovided through theArcFacemodel.Pose estimationprovided through theOpenPosemodel (2017 version).Getting startedBe sure to read thefull documentationhere.InstallationTerran requires Python 3.6 or above, and Pytorch 1.3 or above. It can be used
with or without a GPU, though the current available algorithms require GPUs in
order to run under a reasonable time.To install, run:pipinstallterranOr, if you want better-looking visualizations and haveCairoinstalled, you can go with:pipinstallterran[cairo]If you require a particular Pytorch version (e.g. you're using a specific CUDA
version), be sure to install it beforehand.For more information, see theInstallationsection in the
documentation.UsageSee theGetting startedsection in
the documentation, and theExamplessection for more in-depth examples.You can use the functions underterran.io.*for easy reading of media files,
and the appropriate algorithm function under the top-level module. If you don't
needany customization, just issue the following
in an interactive console:>>>fromterran.ioimportopen_image>>>fromterran.visimportdisplay_image,vis_faces>>>fromterran.faceimportface_detection>>>>>>image=open_image('examples/readme/many-faces-raw.jpg')>>>detections=face_detection(image)>>>display_image(vis_faces(image,detections))If it's the first use, you should be prompted to download the model files. You
can also do it manually, by runningterran checkpoint listand thenterran checkpoint download <checkpoint-id>in a terminal.Or maybe:>>>fromterran.visimportvis_poses>>>fromterran.poseimportpose_estimation>>>>>>image=open_image('examples/readme/many-poses-raw.jpg')>>>display_image(vis_poses(image,pose_estimation(image)))ExamplesFinding a person in a group of imagesYou can use Terran's I/O utilities to quickly find a person within all the
images present in a directory, in aGoogle Photos-like functionality. The
code is present atexamples/match.py.pythonexamples/match.pyreference.pngimages/Herereference.pngis the path to the reference person, which should contain
only one person, whileimages/is the directory containing the images to
search in.Face detection over a videoTerran also provides functions to perform I/O over videos, in order to read
them efficiently and in a background thread, as well as to write them. Seeexamples/video.pyto see a short example of running face
detection over a video.pythonexamples/video.pyvideo.mp4out.mp4Herevideo.mp4is the video to run the face detection over, andout.mp4the
output location.Note thatvideo.mp4could be a Youtube video or the path to your webcam. For
instance:pythonexamples/video.py'https://www.youtube.com/watch?v=oHg5SJYRHA0'out.mp4--duration=30You could also mix this example and the one above to search for a person within
a video. We leave it as an exercise for the reader.Customizing model settingsYou might want to customize any of the detection functions (such asface_detection) in order to change e.g. the size images are resized to (in
order to make it run faster). You can do it like so:fromterran.faceimportDetectionface_detection=Detection(short_side=208)image=open_image(...)detections=face_detection(image)ReferencesTerran doesn't provide training code for the models. As such, pre-trained
weights are taken, adapted and re-packaged from the official model repositories
of the respective models.For OpenPose, theofficial Pytorch versionweights are used.For ArcFace and RetinaFace,Insightface'sweights are used (in mxnet, translated to Pytorch by us).LicenseTerran is released under theBSD 3-Clauselicense.