R/looming_animation_calib.R
looming_animation_calib.RdAll screens are different, so an object of a hypothetical size
may be displayed at a different size on a different screen, due to
differences in resolution or the physical size of the pixels that make up
the screen. looming_animation_calib is a utility to help calibrate
the looming_animation function for a particular screen.
looming_animation_calib(
correction_range = c(0.02, 0.03),
width = 1920,
height = 1080,
ruler = 10,
save_images = FALSE
)numeric vector of length = 2. Upper and lower range of
the correction factors to be tested. Defaults to c(0.02, 0.03).
Larger screens require lower values.
integer. Width resolution of the display. E.g. for a display set
at 1080p resolution (1920x1080), this is width = 1920. Note: this is
NOT the native resolution, but the display resolution as set in the
operating system settings. Visit https://whatismyscreenresolution.com
on the playback display to check.
integer. Height resolution of the display. E.g. for a display
set at 1080p resolution (1920x1080), this is height = 1080. Note:
this is NOT the native resolution, but the display resolution as set in the
operating system settings. Visit https://whatismyscreenresolution.com
on the playback display to check.
numeric. Width in cm to check onscreen with your ruler. Should be less than the physical horizontal width of the screen, or - obviously - it will be too large to display.
logical. If =TRUE, does not delete image files
after the animation video is created.
IMPORTANT: The function works by saving an image
(loom_img_01.png etc.) for every frame of the animation to the
current working directory. It then uses ffmpeg to encode these images
to an .mp4 file (saved as animation_calib.mp4). It then
deletes the .png files from the working directory. It will overwrite
any .png or .mp4 file it encounters which has an identical
name.
The function helps determine the correction value used in
looming_animation to ensure screen diameters are correctly
displayed. Typically this is in the range 0.01 - 0.06, with the larger the
screen the lower the value. It requires access to the screen you intend to
display the animation on, and a ruler or other method of physically
measuring lengths on the screen. The output is a short 2 second, 60 frame
video containing a static image of 10 horizontal bars (it is not an image
file to ensure software rendering onscreen is consistent). This video should
be opened in the playback application, paused, made fullscreen and the bar
closest in length to the entered ruler value used to estimate an
appropriate correction value. If the ruler width falls between
two values, these can be entered as the correction_range, and the
function run again to further refine estimates of the correction
value. The ruler value should be less than the physical horizontal
width of the screen, or - obviously - the bars will be too wide to display.
The display resolution of the screen you will use to play the animation
should be entered as width and height. NOTE - This is the
current DISPLAY resolution, which is not necessarily the native resolution
of the screen, but determined in the Displays preferences of your operating
system. If you are unsure, visit https://whatismyscreenresolution.com
on the device. These settings ensure the animation is in the correct aspect
ratio and uses the full screen.
Note that if you are creating multiple animations, the correction
value used in looming_animation will be the same for a
particular screen as long as the display resolution remains the same.
The function should work with both Windows and macOS (Linux coming soon),
however it requires ffmpeg (http://ffmpeg.org), an external,
cross-platform, command line utility for encoding video, to be installed on
your system. For installation instructions see
http://adaptivesamples.com/how-to-install-ffmpeg-on-windows/ (may need
to restart) or
https://github.com/fluent-ffmpeg/node-fluent-ffmpeg/wiki/Installing-ffmpeg-on-Mac-OS-X
If you are using the function to
calibrate for a small screen, for example a phone or tablet, the resulting
video might look strange: low resolution, blurry, bad spacing, etc. This is
normal, and a result of having to scale the text size to display properly.
It should not affect the estimation of the calibration value, or the
animation you eventually create in looming_animation. Please
do let me know if you have any issues however.
The function requires the following packages:
glue.
## Uncomment to run
## Create a calibration video for checking a 10cm width
# looming_animation_calib(correction_range = c(0.02, 0.03),
# width = 1920,
# height = 1080,
# ruler = 10)