From f9e802778711068c9abdae5a5e94b06e3738112a Mon Sep 17 00:00:00 2001 From: Emmanouil Papadeas <35376950+OverloadedOrama@users.noreply.github.com> Date: Mon, 29 Jul 2024 19:15:52 +0300 Subject: [PATCH] Update docs for v1.0 (#81) * Change the favicon to the new icon * Update some info in the timeline * Move z-index to the cel page * Document blend modes and clipping masks * Mention the palette file extension change * Document layer effects and add Palettize and Pixelize in the list of image effects * Create cli.md Should add more info, such as use cases examples, how to use on each OS and an example of a .bat/.sh script that automates exporting. * Update project.md * Clarify the description of palettize effect * Fix typo in cli.md --- docs/concepts/cel.md | 5 ++- docs/concepts/layer.md | 42 +++++++++++++++++++- docs/concepts/project.md | 21 +++++----- docs/user_manual/cli.md | 39 ++++++++++++++++++ docs/user_manual/image_effects.md | 8 +++- docs/user_manual/palettes.md | 7 ++-- docs/user_manual/user_interface/timeline.md | 20 ++++------ static/img/favicon.ico | Bin 18810 -> 21819 bytes static/img/frame_tag_window.png | Bin 7770 -> 0 bytes 9 files changed, 111 insertions(+), 31 deletions(-) create mode 100644 docs/user_manual/cli.md delete mode 100644 static/img/frame_tag_window.png diff --git a/docs/concepts/cel.md b/docs/concepts/cel.md index 68b84eaa..4023b498 100644 --- a/docs/concepts/cel.md +++ b/docs/concepts/cel.md @@ -11,4 +11,7 @@ In Pixelorama, the term "Cel" (from [celluloid](http://en.wikipedia.org/wiki/Cel Cels can be found in the timeline. They are the square buttons you can click to edit. You can select/deselect multiple by holding the Control key and left-clicking individual cels, or hold the Shift key and left-click a cel to also select all of the cels between the one that was clicked and the one that has been selected last. ## Linked cels -You can also right-click cels to link them together. Linked cels share the same image data, meaning that if you make changes to one linked cel, the changes are shared with all other linked cels. Keep in mind that, as of right now, linked cels are layer-local. You cannot have cels linked that belong to different layers, only different frames. Linked cels are marked with a green outline. +You can also right-click cels, that belong to a pixel layer, to link them together. Linked cels share the same image data, meaning that if you make changes to one linked cel, the changes are shared with all other linked cels. Keep in mind that, as of right now, linked cels are layer-local. You cannot have cels linked that belong to different layers, only different frames. Linked cels are marked with a colored rectangle behind their preview. + +## Z-Index +Z-index can be edited through the cel properties, and it is used to change the ordering of individual cels independently of the layer they are in, making them appear behind, or in front of other cels in different layers. The default value of 0 means that the cel's ordering is the same as its layer's. Positive values move it to the front, and negative values move it to the back. diff --git a/docs/concepts/layer.md b/docs/concepts/layer.md index 3a242804..e2b7333b 100644 --- a/docs/concepts/layer.md +++ b/docs/concepts/layer.md @@ -13,7 +13,45 @@ Right now, there are three types of layers. Pixel layers, group layers, and 3D l Pixel layers are the default and most straight forward type of layer. Their cels contain regular raster image data, in which you can normally draw and manipulate pixels. Pixel cels are the only types of cels that can be linked right now. ### Group layers -Group layers are used solely for organization and their cels are empty and do not hold any actual data. They can be used to group common layers together, and they can expanded and collapsed from view in the timeline. +Group layers are used solely for organization and their cels are empty and do not hold any actual data. They can be used to group common layers together, and they can expanded and collapsed from view in the timeline. Right now, they do not affect blending or masking. ### 3D layers -The cels of 3D layers contain 3D mesh, lighting, camera and environment data, that are being rasterized based on the size of the canvas. They can contain lights, such as directional lights, spot lights and point lights, and a variety of primitive meshes, including boxes, capsules, spheres, cylinders, prisms, planes and even text. Importing custom .obj models is also possible. +The cels of 3D layers contain 3D mesh, lighting, camera and environment data, that are being rasterized based on the size of the canvas. They can contain lights, such as directional lights, spot lights and point lights, and a variety of primitive meshes, including boxes, capsules, spheres, cylinders, prisms, toruses, planes and even text. Importing custom .obj models is also possible. + +## Blend modes +The blend mode of each layer determines how its colors blend with the colors of the layer directly below it. Pixelorama supports the following blend modes: + +| Name | Category | Description | +| ----------- | ----------- | ----------- | +| Normal | Normal | The blend layer colors are simply placed on top of the base colors. | +| Darken | Darken | Keeps the darker colors between the blend and the base layers. | +| Multiply | Darken | Multiplies the numerical values of the two colors, giving a darker result. | +| Color burn | Darken | Darkens by increasing the contrast between the blend and base colors. | +| Linear burn | Darken | Darkens the base colors based on the value of the blend colors. | +| Lighten | Lighten | Keeps the lighter colors between the blend and the base layers. | +| Screen | Lighten | Lightens the colors by multiplying the inverse of the blend and base colors. | +| Color dodge | Lighten | Lightens by decreasing the contrast between the blend and base colors. | +| Add | Lighten | Lightens by adding the numerical values of the two colors. Also known as linear dodge. | +| Overlay | Contrast | Like Screen mode in bright base colors and Multiply mode in darker base colors. | +| Soft light | Contrast | Similar to Overlay, but more subtle. | +| Hard light | Contrast | Like Screen mode in bright blending colors and Multiply mode in darker colors. | +| Difference | Inversion | Subtracts the blend color from the base or vice versa, depending on the brightness. | +| Exclusion | Inversion | Similar to Difference mode, but with less contrast between the colors. | +| Subtract | Inversion | Darkens by subtracting the numerical values of the blend colors from the base. | +| Divide | Inversion | Divides the numerical values of the base colors by the blend. | +| Hue | Component | Uses the blend hue while preserving the base saturation and luminosity. | +| Saturation | Component | Uses the blend saturation while preserving the base hue and luminosity. | +| Color | Component | Uses the blend hue and saturation while preserving the base luminosity. | +| Luminosity | Component | Uses the blend luminosity while preserving the base hue and saturation. | + +## Layer effects +Layer effects are image effects that are being applied to the layer in a non-destructive way. This means that they do not directly modify the image data, which allows artists to disable and enable them at will, without having to worry that their work will be modified in a permanent way. They are only being applied on [export](../user_manual/save_and_export), and they can be previewed in the canvas, if "Display Layer Effects" is enabled, under the View menu. Each layer can contain multiple layer effects. + +To add a layer effect, you can click on the "FX" button in the layer area of the timeline. A window will appear, that lets you add, remove and change the order of layer effects. You can also change the properties of each effect. For a list of all available layer effects, see [image effects](../user_manual/image_effects#list-of-image-effects). + +:::info Layer vs image effects +The difference between layer effects and image effects, is that layer effects can only be **applied per-layer** and are **non-destructive**, while image effects can be applied to **multiple cels** at the same time, and are **destructive**. Also, as of right now, layer effects cannot be animated. +::: + +## Clipping mask +Clipping masks can be used to draw the content of the layer only on top of the non-transparent pixels of the layer directly below. In other words, the layer below the clipping mask is what controls the visibility of the content of the clipping mask. You can make a layer be a clipping mask by right-clicking the layer button in the timeline, and toggling "Clipping mask". \ No newline at end of file diff --git a/docs/concepts/project.md b/docs/concepts/project.md index 90079829..8841a909 100644 --- a/docs/concepts/project.md +++ b/docs/concepts/project.md @@ -4,14 +4,13 @@ title: Project sidebar_label: Project --- -In Pixelorama, the term "Project" refers to the entire sprite, which contains all of the frames it might have. Each project can be saved as a `.pxo` file. Multiple projects can be opened in Pixelorama at the same time, with each one having its own tab. +In Pixelorama, the term "Project" refers to the entire sprite, which contains all of the frames and layers it might have. Each project can be saved as a `.pxo` file. Multiple projects can be opened in Pixelorama at the same time, with each one having its own tab. -A Project contains the following properties: -- A set of frames for animations, along with their duration, animation tags and FPS, as well as multiple layers. Frames and layers intersect and create [cels](cel), which are the editable images themselves of the project. -- A [size](../user_manual/transforming/#scale) - width and height - in pixels. -- A name. +A project contains the following properties: +- The image data of each individual [cel](cel). +- The properties of the project itself, such as its name, size and FPS (frames per second). +- All of the properties of frames, [layers](layer), cels, animation tags, [guides](../user_manual/user_interface/canvas/#rulers-and-guides). - [Brushes](brush) that are local to that specific project. -- [Guides](../user_manual/user_interface/canvas/#rulers-and-guides) - lines that help you draw. ## Saving a project See [this page](../user_manual/save_and_export/#saving) to learn how to save a project. @@ -20,11 +19,11 @@ See [this page](../user_manual/save_and_export/#saving) to learn how to save a p Pxo files are Pixelorama's custom file format that saves the entire content of the project. It cannot be opened in other image editors. ### File structure -The file essentially consists of two lines. The first line is all of the project's metadata, such as project name, size, number of layers, number of frames, tags, [project brushes](brush/#project-brushes), fps etc. They are stored in JSON form, so they can easily be read by other software. +The file format is essentially a .zip file in disguise. It contains a `data.json` file, and an `image_data` folder. The `data.json` file contains all of the project's metadata, such as project name, size, FPS, and the metadata of layers, frames, cels, etc. They are stored in JSON form, so they can easily be read by other software. -The second line contains all of the image data as buffers. First, all of the image data for every [cel](cel) is being stored. It starts from the very first cel, which is equivalent to the bottom-most layer and the first frame, then it continues for every layer from bottom to top and once it reaches the final layer, moves on to the next frame, where it again starts from the bottommost layer and continues saving up to the top. After all of the cel image data has been saved, the image data of the project brushes are saved if the project has any. +The `image_data` folder contains all of the image data. It contains another folder called `frames`, which in turn contains a folder for each `frame` of the project, and each frame folder contains the image data of every [cel](cel) that belongs to that frame. To preserve a non-destructive workflow, the cel image data are not affected by layer blend modes and layer effects. If the project has [brushes](brush), a `brushes` folder is also created, containing all of the brush image data. If you have enabled the option to include the blended images, the `image_data` folder will also contain all of the final image data for each frame. A final image is composed of every cel, with the layer effects applied to each cel, blended together into a single image, taking the blend modes of each layer into account. -So, in order for a software to read the data of a pxo, it first reads the first line as a JSON object, and then it loops through the buffers, which all have the same size as the project size, until it reads all the frames and layers. After that, if there are more buffers, they correspond to the project brushes, the size of which is stored in the JSON object. +In order for a software to read the data of a pxo, it has to open it as a zip file, and then it has to read the `data.json` file, and parse it as JSON object. Then, it either has to loop through the all of the folders included in `image_data/frames`, where each folder contains the cel data for each frame seperately, or, if the final blended images are included and that's all we care about, it just has to loop through all of the images inside the `image_data` folder, where each image corresponds to every frame of the project, and import them. -### ZSTD compression -During save, you are given the option to select ZSTD compression. If you do, this will reduce your pxo size, but if your project is large and has a lot of content in it, it may take some time to save and load it. Saving projects with ZSTD compression is currently unsupported in the Web version. If you are writing software that supports .pxo files, make sure to detect if the files are compressed first. +### Include blended images +During save, you are given the option to select if the blended images will be included in the exported file. If enabled, the final blended images are also being stored in the pxo, for each frame. This makes the pxo file larger and is useful for importing by third-party software or [CLI exporting](../user_manual/cli). Loading pxo files in Pixelorama does not need this option to be enabled. diff --git a/docs/user_manual/cli.md b/docs/user_manual/cli.md new file mode 100644 index 00000000..8c364b53 --- /dev/null +++ b/docs/user_manual/cli.md @@ -0,0 +1,39 @@ +--- +id: cli +title: Command Line Interface +sidebar_label: Command Line Interface +--- +Pixelorama offers a Command Line Interface (CLI), allowing you to use some of its features, such as project [exporting](save_and_export), from the command line. The CLI can be used to automate tasks easily. It can only be used on desktop platforms, such as Windows, Linux and macOS. + +## Options +For the full list of the system options, you can refer to [Godot's documentation](https://docs.godotengine.org/en/stable/tutorials/editor/command_line_tutorial.html). Only the options that have the green checkbox icon in their description can be used in Pixelorama. +``` +Usage: + Pixelorama.x86_64 [SYSTEM OPTIONS] -- [USER OPTIONS] [FILES]... + +Use -h in place of [SYSTEM OPTIONS] to see [SYSTEM OPTIONS]. +Or use -h in place of [USER OPTIONS] to see [USER OPTIONS]. + +Some useful [SYSTEM OPTIONS] are: +--headless Run in headless mode. +--quit Close pixelorama after current command. + + +[USER OPTIONS]: + +(The terms in [ ] reflect the valid type for corresponding argument). + +--version, --pixelorama-version Prints current Pixelorama version +--size Prints size of the given project +--framecount Prints total frames in the current project +--export, -e Indicates given project should be exported +--spritesheet, -s Indicates given project should be exported as spritesheet +--output, -o [path] Name of output file (with extension) +--scale [integer] Scales up the export image by a number +--frames, -f [integer-integer] Used to specify frame range +--direction, -d [0, 1, 2] Specifies direction +--json Export the JSON data of the project +--split-layers Each layer exports separately +--help, -h, -? Displays this help page + +``` diff --git a/docs/user_manual/image_effects.md b/docs/user_manual/image_effects.md index f853f76a..b4f91752 100644 --- a/docs/user_manual/image_effects.md +++ b/docs/user_manual/image_effects.md @@ -5,6 +5,10 @@ sidebar_label: Image effects --- You can apply multiple image effects to an image, to easily and quickly affect its content, without modifying it pixel by pixel. The image effects can be found under the Image menu. +:::warning +Image effects are **destructive**. This means that, once they are applied, they directly modify the image data, and the only way to reverse this change is by undoing. If you want to use a non-destructive workflow, use [layer effects](../concepts/layer#layer-effects) instead. +::: + ## List of image effects | Name | Description | | ----------- | ----------- | @@ -16,6 +20,8 @@ You can apply multiple image effects to an image, to easily and quickly affect i | Invert colors | Inverts the colors of the image. Can choose whether this affects the red, blue, green or alpha channels, or multiple at once. | | Desaturation | Desaturates the colors of the image, turning them to grayscale. Can choose whether this affects the red, blue, green or alpha channels, or multiple at once. | | Adjust Hue/Saturation/Value | Adjusts the hue, saturation and the value of the colors of the image. | +| Palettize | Limits the number of colors of the image to the colors of the currently active palette. Each color is being mapped to the nearest color in the palette. | +| Pixelize | Pixelates the image by combining its pixels into larger squares, containing their average color. | | Posterize | Limits the number of colors of the image to the posterization level. Can also set an optional dither intensity. | | Gradient | Generates a gradient. Its colors can be modified from the gradient edit, by clicking on the colored area to add new color steps. Clicking on the color steps with the left mouse allows you to change the color of that step, and right clicking on a step, removes it. Gradients can either be linear or radial, and they can optionally be dithered and/or repeated. You can also generate step gradients by changing the interpolation type to constant. | | Gradient map | Converts the colors of the image into a gradient, based on their lightness. Darker colors are mapped to colors on the left side of the gradient, and brighter colors are mapped to colors on the right side of the gradient. | @@ -29,4 +35,4 @@ By default, image effects will affect only the selected area of the cel(s). If t :::tip Affecting multiple cels at once By default, image effects will apply in all of the currently selected cels. It is also possible to make them apply to the entire selected frame, to all frames of the project, and to all projects as well, by selecting one of these options from the option button found next to the "Only affect selection" checkbox, in the dialog of the image effect you wish to apply. -::: \ No newline at end of file +::: diff --git a/docs/user_manual/palettes.md b/docs/user_manual/palettes.md index 028c0e32..0de45e13 100644 --- a/docs/user_manual/palettes.md +++ b/docs/user_manual/palettes.md @@ -127,16 +127,15 @@ You can import any image as a palette and extract colors from it. Every color fr | Format | File extension | | -------- | -------- | -| Pixelorama palette | .tres | +| Pixelorama palette | .json | | GIMP GPL | .gpl | | PAL | .pal | | Image palette | .png, .bmp, .hdr, .jpg, .jpeg, .svg, .tga, .webp | -| Pixelorama old palette | .json | :::caution file extensions Palette format detection uses file extensions to determine how to parse palette formats. An incorrect extension will result in an import error. ::: -:::caution pre-0.9 pixelorama palettes -Palettes created in versions of Pixelorama prior to 0.9 have to be reimported. The save format was changed from `.json` to more Godot-compatible `.tres`. +:::caution pre-1.0 pixelorama palettes +Palettes created in versions of Pixelorama prior to 1.0 cannot be reimported. The save format was changed from `.tres` to `.json`, due to security concerns. In order to convert an old palette to a new one, you can export it as an image from version 0.11.4, and import that image to the newest version. ::: diff --git a/docs/user_manual/user_interface/timeline.md b/docs/user_manual/user_interface/timeline.md index 305ff342..e4e1eefe 100644 --- a/docs/user_manual/user_interface/timeline.md +++ b/docs/user_manual/user_interface/timeline.md @@ -31,16 +31,16 @@ If you want a layer to ignore onion skinning simply add the "_io" suffix in its ::: ## Layers -On the left side of the timeline, you will see the layer buttons. Clicking on a layer button will select the current layer. Double-clicking will let you change the name of that layer. +On the left side of the timeline, you will see the layer buttons. Clicking on a layer button will select the current layer. Double-clicking will let you change the name of that layer. Right clicking a layer button will open up a menu, with options such as the layer's properties, and whether it's a clipping mask or not. The layer buttons have three more buttons on them. The first toggles the layer's visibility. While invisible, the layer cannot be edited by the user. It will also remain invisible on export. The second locks and unlocks the layer. If the layer is locked, it cannot be edited by the user, but it does remain visible. The third button is used to automatically link the new cels that are being created. If it's toggled on, it is essentially a fast way to create linked cels. -There are 6 more buttons located on top of the layers. These, in order of appearance: add a new layer, remove the currently active layer, move the current layer up and down, clone the current layer and merge the current layer with the one directly below it. +There are 7 more buttons located on top of the layers. These, in order of appearance: add a new layer, remove the currently active layer, move the current layer up and down, clone the current layer, merge the current layer with the one directly below it, and open up a dialog for layer effects. Below these buttons, you can change the selected layer's blend mode and opacity. ## Frames Directly above the cels, you will notice some buttons with each one having a number. These are the frame buttons, and the number they have is their order in the animation. -Clicking on a frame button will select that frame, and right-clicking a frame button will open up a menu. The menu options include a remove frame option, clone frame, move frame to the left, move frame to the right and frame properties. Clicking on frame properties brings up a window that lets you change the duration of that frame. +Clicking on a frame button will select that frame, and right-clicking a frame button will open up a menu. The menu options include frame properties, remove frame, clone frame, move frame to the left, move frame to the right, new tag, reverse frames (only works when multiple frames are selected), and center frames. Clicking on frame properties brings up a window that lets you change the duration of that frame, as well as set custom user-defined data. :::tip frame duration By default, the duration of each frame is set to 1x, which means it will take exactly as much time as the timeline FPS (frames per second). Setting it to 2x, for example, that frame will take twice as much time, while setting it to 0.5x will take half the time, meaning it will play out faster. @@ -48,25 +48,21 @@ By default, the duration of each frame is set to 1x, which means it will take ex You can also drag and drop frame buttons to re-arrange them. This will also affect their corresponding cels. -On the top side of the timeline, you will find frame-related buttons which offer the same functionality as the frame button right-click menu, like adding, removing, cloning and moving frames. You will also find a button that is used to modify `frame tags`. +On the top side of the timeline, you will find frame-related buttons which offer the same functionality as the frame button right-click menu, like adding, removing, cloning and moving frames. ### Frame tags Frame tags are used to organize different parts of your animated sprite. Those parts can also be exported independently using frame tags. -Clicking on the button mentioned above will bring up this window. +To create a new tag, you can right click on a frame button and select "New Tag". A popup will appear that lets you set a name for the tag, a color, the starting (from) and ending (to) frame, as well as custom user-defined data. -![Frame tags](../../../static/img/frame_tag_window.png) +To edit an already existing tag, you can click on its name on the timeline, above the frame area. You can quickly move and resize it by dragging its edges. -Here you can see the list of all of the frame tags of the current [project](../../concepts/project). Using the plus (+) sign, you can add more tags. A tag has a starting frame (from), an ending frame (to), a name and a color. - -To edit an already existing tag, you can click on the "Edit" button next to the tag you want. - -If "Animation plays only on frames of the same tag" is toggled on, then, when you preview your animation, it will only preview the frames that belong on the same tag as the currently selected frame. This is a great way to preview parts of your animation separately. +If "Animation plays only on frames of the same tag" is toggled on in the timeline options, then, when you preview your animation, it will only preview the frames that belong on the same tag as the currently selected frame. This is a great way to preview parts of your animation separately. ## Cels Cels are the intersection of layers and frames. For a more detailed explanation, you can [read this page](../../concepts/cel). To select a cel in order to draw on it, you can left-click on their respective button. The cel buttons take the most space in the timeline, and they are located to the right of the layer buttons and below the frame buttons. They also have a small preview of their image data on them. -Right-clicking on a cel button will bring up a menu, with options such as Link (or Unlink) Cel, and Delete, which clears the content of the cel, making it fully transparent. +Right-clicking on a cel button will bring up a menu, with options such as properties, link (or unlink) cel, and delete, which clears the content of the cel, making it fully transparent. In the cel properties, you can change their opacity (cel opacity is different than layer opacity), their z-index and also set custom user-defined data. :::tip Selecting multiple cels You can select/deselect multiple cels by holding the Control key and left-clicking individual cels, or hold the Shift key and left-click a cel to also select all of the cels between the one that was clicked and the one that has been selected last. diff --git a/static/img/favicon.ico b/static/img/favicon.ico index d942cf70de5550dfccbf270930fcac4fb37c2157..18f6f267183043e740e4d7f7a797b942139fa376 100644 GIT binary patch literal 21819 zcmeI4U2IfE6vxlDg)S)F-58*PK(lQcG<>vaf)7ww%;MUImZoui!P>At|ldA=DNL^xgM|I@A3LlWX)RXDap*8US%6e#AAG% zZc#HtWnOmWR*y3%UpNRQuQxBxBR~$SSE?tbeo;Ka9#SG{+bGYT{iO!w>jj|=$wXYo zS`f#a(nZY?HLjeBafFkCL7O%udA*r=dAS~sICC~_!C}y6fQen3;l{Yxw0%S=V0#N~ zZi0TtHuIG7hA&A|G5)?(Y$z>s|3n?f1VUoS+~B818~)%jS~dJ60r0Xu`EuL(w9IY&9R=c`CSE0A_^AX;{-^}7 zZlG%R+`jdv?-#au_J*&2%m)6tns}7}cWJm9Y@;-K)?RgZ&>IH(>68~(Z?4hnx=^*GpwgX(dx;jb&=pzzmKkAsaks2&F! z{<T$5)uPfr9@Yhw3gN-<-9tRu#x*`q=e_i!B*ocGbaj@a9E8?K= z*Hw>$jX0@1VNHD7I$P5=1PlQ~zz~=?1SZ=3PM`0a#YKT>Q)h|4N=VZR9`lzB z{NPah=+HS?^gOw#cAfZJZCM5Wm5*1vf1#zWYIyw)}o4MkF3v(82 z*nH(&U)_q!dzVD7xi;+i=JV!=bAR>f`oi5g&qW*m?D)O+VAA!r|^JwXUq62~SmoG+Miu7$x4(B-HwH^6B zLZ?qXRo!3NbMm{^_O9O3KfKeqzq4#v{+#^n@6D#yr`)w$-6yHFYs&Vm-tDW2>paAM zYI=UXuqkp~WRCzikUekxG44zlP5vAVys&Rq+D4JPUA;Na_H~@@>fJ!@?6_^mwq5GJ z7`b=vSx4xrYnQfdZRreDzOnO4NAIrBt{&cZ!qG6J;$qKFMc1!vc7&r1>lb&IddPWS zY->s?U%b74eeZ|MXVTxUUwV?xOm~DAhFr9zCZF0`ElKvgqmqs^o_Em0pQh5%ujkUn zzf$N6Y{$a+)U>vT!n2!`!*kZT==duZTx;46^-z8Cg06KxE-wDIly4mctBU-G9tpkn EFZvRbwg3PC literal 18810 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 h+nV2W1Q#>6b9`#=wDw26Bsd77D5oNuk9_>